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 and Description
RDFContainers()

Method Summary

Modifier and Type	Method and Description
static void	consumeContainer(IRI containerType, Iterable<?> values, Resource container, java.util.function.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, java.util.function.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, java.util.function.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 <E extends RDF4JException> void	extract(IRI containerType, GetStatementOptional statementSupplier, Resource container, java.util.function.Consumer<Statement> collectionConsumer, java.util.function.Function<String,java.util.function.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 void	extract(IRI containerType, Model sourceModel, Resource container, java.util.function.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 <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 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.

consumeContainer

public static void consumeContainer(IRI containerType,
                                    Iterable<?> values,
                                    Resource container,
                                    java.util.function.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,
                                    java.util.function.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,
                                 java.util.function.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,
                           java.util.function.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,
                                                      java.util.function.Consumer<Statement> collectionConsumer,
                                                      java.util.function.Function<String,java.util.function.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