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

Method Summary

Modifier and Type	Method and 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, java.util.function.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, java.util.function.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, java.util.function.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 <E extends RDF4JException> void	extract(GetStatementOptional statementSupplier, Resource head, java.util.function.Consumer<Statement> collectionConsumer, java.util.function.Function<String,java.util.function.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 void	extract(Model sourceModel, Resource head, java.util.function.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 <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 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.

consumeCollection

public static void consumeCollection(Iterable<?> values,
                                     Resource head,
                                     java.util.function.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,
                                     java.util.function.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,
                                 java.util.function.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,
                           java.util.function.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,
                                                      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 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