Package org.eclipse.rdf4j.model.util

## Class RDFContainers

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

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

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `consumeContainer​(IRI containerType, Iterable<?> values, Resource container, Consumer<Statement> consumer, Resource... contexts)` | Converts the supplied `Iterable` to an RDF Container, using the supplied `head` resource as the starting resource of the RDF Containter.
    `static void` | `consumeContainer​(IRI containerType, Iterable<?> values, Resource container, Consumer<Statement> consumer, ValueFactory vf, Resource... contexts)` | Converts the supplied `Iterable` to an RDF Container, using the supplied `head` resource as the starting resource of the RDF Container.
    `static void` | `consumeValues​(Model m, Resource container, IRI containerType, Consumer<Value> consumer, Resource... contexts)` | 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.
    `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`.
    `static <E extends RDF4JException> void` | `extract​(IRI containerType, GetStatementOptional statementSupplier, Resource container, Consumer<Statement> collectionConsumer, Function<String,​Supplier<E>> exceptionSupplier, Resource... contexts)` | 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.
    `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`.
    `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.
    `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.
    `static <C extends Collection<Value>> C` | `toValues​(IRI containerType, Model m, Resource container, C collection, Resource... contexts)` | Converts an RDF Containter to a Java `Collection` of `Value` objects.

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

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

- - ### 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 `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

    - #### 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 `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

    - #### 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

    - #### consumeContainer

          public static void consumeContainer​(IRI containerType,
                                              Iterable<?> values,
                                              Resource container,
                                              Consumer<Statement> consumer,
                                              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 reported to the supplied `Consumer` function.
      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 Containter. May be `null`, in which case a new resource is generated to represent the containter head.
        `consumer` - the `Consumer` function for the Statements of the RDF Containter. 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.
      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)`

    - #### consumeContainer

          public static void consumeContainer​(IRI containerType,
                                              Iterable<?> values,
                                              Resource container,
                                              Consumer<Statement> consumer,
                                              ValueFactory vf,
                                              Resource... contexts)

      Converts the supplied `Iterable` to an RDF Container, using the supplied `head` resource as the starting resource of the RDF Container. The statements making up the new RDF Container will be reported to the supplied `Consumer` function.
      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 Container. 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 containter head.
        `consumer` - the `Consumer` function for the Statements of the RDF Container. 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 Container. 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.3.0
      See Also:
        RDF Schema 1.1 section on Collection vocabulary, `Literals.createLiteralOrFail(ValueFactory, Object)`

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