Package org.eclipse.rdf4j.model.util

Class RDFCollections

java.lang.Object
org.eclipse.rdf4j.model.util.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:

  • Constructor Details

    • RDFCollections

      public RDFCollections()

  • Method Details

    • 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:

    • 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:

    • 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:

    • consumeCollection

      public static void consumeCollection(Iterable<?> values, Resource head, Consumer<Statement> consumer, 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 reported to the supplied Consumer function.
      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.
      consumer - the Consumer function for the Statements of the RDF Collection. 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.
      Throws:
      LiteralUtilException - if one of the supplied values can not be converted to a Literal.
      See Also:

    • consumeCollection

      public static void consumeCollection(Iterable<?> values, Resource head, Consumer<Statement> consumer, ValueFactory vf, 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 reported to the supplied Consumer function.
      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.
      consumer - the Consumer function for the Statements of the RDF Collection. May not be null.
      vf - the ValueFactory to use for creation of new 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.
      Throws:
      LiteralUtilException - if one of the supplied values can not be converted to a Literal.
      Since:
      3.0
      See Also:

    • 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:

    • 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
      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.