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:
    RDF Schema 1.1 section on Collection vocabulary

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `RDFCollections()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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.
    `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.
    `static <C extends Collection<Value>> C` | `asValues​(Model m, Resource head, C collection, Resource... contexts)` | Converts an RDF Collection to a Java `Collection` of `Value` objects.
    `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.
    `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.
    `static void` | `consumeValues​(Model m, Resource head, Consumer<Value> consumer, Resource... contexts)` | 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.
    `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`.
    `static <E extends RDF4JException> void` | `extract​(GetStatementOptional statementSupplier, Resource head, Consumer<Statement> collectionConsumer, Function<String,​Supplier<E>> exceptionSupplier, Resource... contexts)` | 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.
    `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`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### 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 `Statement`s, 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 `Statement`s, 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

    - #### 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:
        RDF Schema 1.1 section on Collection vocabulary, `Literals.createLiteralOrFail(ValueFactory, Object)`

    - #### 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:
        RDF Schema 1.1 section on Collection vocabulary, `Literals.createLiteralOrFail(ValueFactory, Object)`

    - #### 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 `Statement`s, 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`