Package org.eclipse.rdf4j.model.util

Class RDFCollections

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

    RDF Collections are represented using a Lisp-like structure: the list starts with a head resource (typically a blank node), which is connected to the first collection member via the RDF.FIRST relation. The head resource is then connected to the rest of the list via an RDF.REST relation. The last resource in the list is marked using the RDF.NIL node.

    As an example, a list containing three literal values "A", "B", and "C" looks like this as an RDF Collection: 

       _:n1 -rdf:type--> rdf:List
     |
     +---rdf:first--> "A"
     |
     +---rdf:rest --> _:n2 -rdf:first--> "B"
                        |
                        +---rdf:rest--> _:n3 -rdf:first--> "C"
                                          |
                                          +---rdf:rest--> rdf:nil

    Here, _:n1 is the head resource of the list. Note that in this example it is declared an instance of RDF.LIST, however this is not required for the collection to be considered well-formed.

    Author:
    Jeen Broekstra
    See Also:
    RDF Schema 1.1 section on Collection vocabulary

    • Constructor Detail

      • RDFCollections

        public RDFCollections()

    • Method Detail

      • asRDF

        public static <C extends Collection<Statement>> C asRDF​(Iterable<?> values,
                                                        Resource head,
                                                        C sink,
                                                        Resource... contexts)
        Converts the supplied Iterable to an RDF Collection, using the supplied head resource as the starting resource of the RDF Collection. The statements making up the new RDF Collection will be added to the supplied statement collection.
        Parameters:
        values - an Iterable of objects (such as a Java Collection ), which will be converted to an RDF Collection. 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.
        head - a Resource which will be used as the head of the list, that is, the starting point of the created RDF Collection. May be null, in which case a new resource is generated to represent the list 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 Collection. 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

      • asRDF

        public static <C extends Collection<Statement>> C asRDF​(Iterable<?> values,
                                                        Resource head,
                                                        C sink,
                                                        ValueFactory valueFactory,
                                                        Resource... contexts)
        Converts the supplied Iterable to an RDF Collection, using the supplied head resource as the starting resource of the RDF Collection. The statements making up the new RDF Collection will be added to the supplied statement collection.
        Parameters:
        values - an Iterable of objects (such as a Java Collection ), which will be converted to an RDF Collection. 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.
        head - a Resource which will be used as the head of the list, that is, the starting point of the created RDF Collection. May be null, in which case a new resource is generated to represent the list head.
        sink - a Collection of Statement objects (for example a Model) to which the RDF Collection statements will be added. May not be null.
        valueFactory - 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 Collection. 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.
        Since:
        3.0
        See Also:
        RDF Schema 1.1 section on Collection vocabulary

      • asValues

        public static <C extends Collection<Value>> C asValues​(Model m,
                                                       Resource head,
                                                       C collection,
                                                       Resource... contexts)
                                                throws ModelException
        Converts an RDF Collection to a Java Collection of Value objects. The RDF Collection is given by the supplied Model and head. This method expects the RDF Collection 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:
        m - the Model containing the collection to read.
        head - the Resource that represents the list head, that is the start resource of the RDF Collection 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 Collection. This argument is an optional vararg and can be left out.
        Returns:
        the supplied Java Collection, filled with the items from the RDF Collection (if any).
        Throws:
        ModelException - if a problem occurs reading the RDF Collection, 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 head,
                                 Consumer<Value> consumer,
                                 Resource... contexts)
                          throws ModelException
        Reads an RDF Collection starting with the supplied list head from the supplied Model and sends each collection member Value to the supplied Consumer function. This method expects the RDF Collection 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.
        head - the Resource that represents the list head, that is the start resource of the RDF Collection to be read. May not be null.
        consumer - the Java Consumer function to which the collection items are reported.
        contexts - the context(s) from which to read the RDF Collection. This argument is an optional vararg and can be left out.
        Throws:
        ModelException - if a problem occurs reading the RDF Collection, for example if the Collection is not well-formed.
        See Also:
        RDF Schema 1.1 section on Collection vocabulary

      • getCollection

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

      • extract

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

      • extract

        public static <E extends RDF4JException> void extract​(GetStatementOptional statementSupplier,
                                                      Resource head,
                                                      Consumer<Statement> collectionConsumer,
                                                      Function<String,​Supplier<E>> exceptionSupplier,
                                                      Resource... contexts)
                                               throws E extends RDF4JException
        Extracts an RDF Collection starting with the supplied list head from the statement supplier and sends all statements that make up the collection to the supplied Consumer function. This method expects the RDF Collection 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:
        statementSupplier - the source of the statements from which the RDF collection is to be read, specified as a functional interface.
        head - the Resource that represents the list head, that is the start resource of the RDF Collection 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 Collection. This argument is an optional vararg and can be left out.
        Throws:
        E - if a problem occurs reading the RDF Collection, for example if it is not well-formed.
        E extends RDF4JException