Package org.eclipse.rdf4j.model.util

Class RDFContainers

  • public class RDFContainers
extends Object
    Utilities for working with RDF Containers and converting to/from Java Collection classes.

    RDF Containers are represented using 3 different types of structures:

    1. RDF.BAG : A Bag (a resource having type rdf:Bag) represents a group of resources or literals, possibly including duplicate members, where there is no significance in the order of the members.

    2. RDF.SEQ : A Sequence or Seq (a resource having type rdf:Seq) represents a group of resources or literals, possibly including duplicate members, where the order of the members is significant.

    3. RDF.ALT : An Alternative or Alt (a resource having type rdf:Alt) represents a group of resources or literals that are alternatives (typically for a single value of a property).

    So, in each of the above types, the container starts with a first resource node, via the rdf:_1 relation. Similarly, the next member is connected via the rdf:_2 relation and so on.

    For eg. Bag containing three literal values "A", "B", and "C" looks like this as an RDF Container: 

       _:n1 -rdf:type--> rdf:Bag
     |
     +---rdf:_1--> "A"
     |
     +---rdf:_2--> "B"
     |
     +---rdf:_3--> "C"
    See Also:
    RDF Schema 1.1 section on Collection vocabulary

    • Constructor Detail

      • RDFContainers

        public RDFContainers()

    • Method Detail

      • toRDF

        public static <C extends Collection<Statement>> C toRDF​(IRI containerType,
                                                        Iterable<?> values,
                                                        Resource container,
                                                        C sink,
                                                        Resource... contexts)
        Converts the supplied Iterable to an RDF Container, using the supplied head resource as the starting resource of the RDF Containter. The statements making up the new RDF Containter will be added to the supplied statement collection.
        Parameters:
        containerType - defines the type of RDF Container
        values - an Iterable of objects (such as a Java Collection ), which will be converted to an RDF Containter. May not be null. The method attempts to convert each value that is not already an instance of Value to a Literal. This conversion will fail with a LiteralUtilException if the value's object type is not supported. See Literals.createLiteralOrFail(ValueFactory, Object) for an overview of supported types.
        container - a Resource which will be used as the head of the container, that is, the starting point of the created RDF Container. May be null, in which case a new resource is generated to represent the container head.
        sink - a Collection of Statement objects (for example a Model) to which the RDF Collection statements will be added. May not be null.
        contexts - the context(s) in which to add the RDF Containter. This argument is an optional vararg and can be left out.
        Returns:
        the supplied sink Collection of Statements, with the new Statements forming the RDF Collection added.
        Throws:
        LiteralUtilException - if one of the supplied values can not be converted to a Literal.
        See Also:
        RDF Schema 1.1 section on Collection vocabulary

      • toRDF

        public static <C extends Collection<Statement>> C toRDF​(IRI containerType,
                                                        Iterable<?> values,
                                                        Resource container,
                                                        C sink,
                                                        ValueFactory vf,
                                                        Resource... contexts)
        Converts the supplied Iterable to an RDF Container, using the supplied head resource as the starting resource of the RDF Containter. The statements making up the new RDF Containter will be added to the supplied statement collection.
        Parameters:
        containerType - defines the type of RDF Container
        values - an Iterable of objects (such as a Java Collection ), which will be converted to an RDF Containter. May not be null. The method attempts to convert each value that is not already an instance of Value to a Literal. This conversion will fail with a LiteralUtilException if the value's object type is not supported. See Literals.createLiteralOrFail(ValueFactory, Object) for an overview of supported types.
        container - a Resource which will be used as the head of the container, that is, the starting point of the created RDF Container. May be null, in which case a new resource is generated to represent the container head.
        sink - a Collection of Statement objects (for example a Model) to which the RDF Collection statements will be added. May not be null.
        vf - the ValueFactory to be used for creation of RDF model objects. May not be null.
        contexts - the context(s) in which to add the RDF Containter. This argument is an optional vararg and can be left out.
        Returns:
        the supplied sink Collection of Statements, with the new Statements forming the RDF Collection added.
        Throws:
        LiteralUtilException - if one of the supplied values can not be converted to a Literal.
        See Also:
        RDF Schema 1.1 section on Collection vocabulary

      • toValues

        public static <C extends Collection<Value>> C toValues​(IRI containerType,
                                                       Model m,
                                                       Resource container,
                                                       C collection,
                                                       Resource... contexts)
                                                throws ModelException
        Converts an RDF Containter to a Java Collection of Value objects. The RDF Containter is given by the supplied Model and container. This method expects the RDF Containter to be well-formed. If the collection is not well-formed the method may return part of the collection, or may throw a ModelException.
        Parameters:
        containerType - defines the type of RDF Container
        m - the Model containing the collection to read.
        container - the Resource that represents the container head, that is the start resource of the RDF Container to be read. May not be null.
        collection - the Java Collection to add the collection items to.
        contexts - the context(s) from which to read the RDF Containter. This argument is an optional vararg and can be left out.
        Returns:
        the supplied Java Collection, filled with the items from the RDF Containter (if any).
        Throws:
        ModelException - if a problem occurs reading the RDF Containter, for example if the Collection is not well-formed.
        See Also:
        RDF Schema 1.1 section on Collection vocabulary

      • consumeValues

        public static void consumeValues​(Model m,
                                 Resource container,
                                 IRI containerType,
                                 Consumer<Value> consumer,
                                 Resource... contexts)
                          throws ModelException
        Reads an RDF Container starting with the supplied containter head from the supplied Model and sends each collection member Value to the supplied Consumer function. This method expects the RDF Container to be well-formed. If the collection is not well-formed the method may report only part of the collection, or may throw a ModelException.
        Parameters:
        m - the Model containing the collection to read.
        container - the Resource that represents the containter head, that is the start resource of the RDF Container to be read. May not be null.
        containerType - defines the type of RDF Container
        consumer - the Java Consumer function to which the collection items are reported.
        contexts - the context(s) from which to read the RDF Container. This argument is an optional vararg and can be left out.
        Throws:
        ModelException - if a problem occurs reading the RDF Container, for example if the Collection is not well-formed.
        See Also:
        RDF Schema 1.1 section on Collection vocabulary

      • getContainer

        public static <C extends Collection<Statement>> C getContainer​(IRI containerType,
                                                               Model sourceModel,
                                                               Resource container,
                                                               C sink,
                                                               Resource... contexts)
        Extracts the RDF Container starting with the supplied head resource from the supplied source Model. The statements making up the RDF Container will be added to the supplied statement collection, which will also be returned.
        Parameters:
        containerType - defines the type of RDF Container
        sourceModel - the source model, containing the RDF Container to be read.
        container - the Resource that represents the container head, that is the start resource of the RDF Container to be read. May not be null. a Collection of Statement objects (for example a Model) to which the RDF Container statements will be added. May not be null.
        sink - a Collection of Statement objects (for example a Model) to which the RDF Container statements will be added. May not be null.
        contexts - the context(s) from which to read the RDF Container. This argument is an optional vararg and can be left out.
        Returns:
        the supplied sink Collection of Statements, with the Statements of the RDF Container added.

      • extract

        public static void extract​(IRI containerType,
                           Model sourceModel,
                           Resource container,
                           Consumer<Statement> consumer,
                           Resource... contexts)
        Extracts the RDF Container starting with supplied head resource from the supplied source Model and sends the statements that make up the collection to the supplied Consumer.
        Parameters:
        containerType - defines the type of RDF Container
        sourceModel - the source model, containing the RDF Container to be read.
        container - the Resource that represents the container head, that is the start resource of the RDF Container to be read. May not be null. a Collection of Statement objects (for example a Model) to which the RDF Container statements will be added. May not be null.
        consumer - the Consumer function for the Statements of the RDF Container. May not be null.
        contexts - the context(s) from which to read the RDF Container. This argument is an optional vararg and can be left out.

      • extract

        public static <E extends RDF4JException> void extract​(IRI containerType,
                                                      GetStatementOptional statementSupplier,
                                                      Resource container,
                                                      Consumer<Statement> collectionConsumer,
                                                      Function<String,​Supplier<E>> exceptionSupplier,
                                                      Resource... contexts)
                                               throws E extends RDF4JException
        Extracts an RDF Container starting with the supplied container head from the statement supplier and sends all statements that make up the collection to the supplied Consumer function. This method expects the RDF Container to be well-formed. If the collection is not well-formed the method may report only part of the collection, or may throw an exception.
        Parameters:
        containerType - defines the type of RDF Container
        statementSupplier - the source of the statements from which the RDF Container is to be read, specified as a functional interface.
        container - the Resource that represents the container head, that is the start resource of the RDF Container to be read. May not be null.
        collectionConsumer - the Java Consumer function to which the collection statements are reported.
        exceptionSupplier - a functional interface that produces the exception type this method will throw when an error occurs.
        contexts - the context(s) from which to read the RDF Container. This argument is an optional vararg and can be left out.
        Throws:
        E - if a problem occurs reading the RDF Container, for example if it is not well-formed.
        E extends RDF4JException