eu.fbk.rdfpro

Interface RDFSource

All Superinterfaces:

Iterable<org.openrdf.model.Statement>

public interface RDFSource
extends Iterable<org.openrdf.model.Statement>

A source of RDF data.

An RDFSource provides repeatable access to RDF data consisting of RDF statements but also namespace declarations and comments. Source data is assumed immutable and can be accessed multiple times in different ways:

• calling emit(RDFHandler, int) that allows full access to all the kinds of data items (statements, namespaces, comments) and allow for optimizing multiple passes over source data;
• calling methods of the Iterable interface, i.e., iterator() and forEach(Consumer); they allow access only to statements and may not be as efficient as emit().
• obtaining a Stream using methods stream() and parallelStream(), as can be done on Java Collections.

In order to implement this interface it is enough to implement method emit(RDFHandler, int), as default implementations are provided for the remaining methods. However, consider overriding also methods spliterator() (and possibly iterator()) in case you have access to a better Splititerator implementation, as the supplied one requires to launch a background thread performing emit(RDFHandler, int) (this is not necessarily bad, as it decouples data extraction from data consumption); in general it is not necessary to override other methods.

Method Summary

Modifier and Type	Method and Description
void	emit(org.openrdf.rio.RDFHandler handler, int passes) Emits the RDF data of the source to the RDFHandler supplied, performing the requested number of passes.
default void	forEach(Consumer<? super org.openrdf.model.Statement> action) This default implementation delegates to emit(RDFHandler, int), enforcing a sequential invocation (but possibly by different threads) of the supplied action.
default Iterator<org.openrdf.model.Statement>	iterator() This default implementation delegates to spliterator().
default Stream<org.openrdf.model.Statement>	parallelStream() Returns a parallel Java 8 Stream over the statements of this RDFSource.
default Spliterator<org.openrdf.model.Statement>	spliterator() This default implementation either delegates to forEach(Consumer), in case Spliterator.forEachRemaining(Consumer) is immediately called (more efficient), or run emit(RDFHandler, int) in a separate thread, populating a queue from where the returned Spliterator retrieves its elements.
default Stream<org.openrdf.model.Statement>	stream() Returns a sequential Java 8 Stream over the statements of this RDFSource.

Method Detail

emit

void emit(org.openrdf.rio.RDFHandler handler,
          int passes)
   throws RDFSourceException,
          org.openrdf.rio.RDFHandlerException

Emits the RDF data of the source to the RDFHandler supplied, performing the requested number of passes. For each pass, the handler method startRDF() is called, followed by possibly concurrent invocations to handleXXX() methods and finally an invocation to endRDF(). Any exception causes this process to be interrupted. In any case, both after the successful completion of the requested passes or after a failure, method AutoCloseable.close() is called on the handler in case it implements interface AutoCloseable (or a sub-interface), thus giving it the possibility to release allocated resources.

Parameters:

handler - the handler where to emit RDF data (statements, comments, namespaces)

passes - the number of passes to perform on source data

Throws:

RDFSourceException - in case of specific errors in retrieving data from this source

org.openrdf.rio.RDFHandlerException - in case of specific errors in the invoked RDFHandler

iterator

default Iterator<org.openrdf.model.Statement> iterator()

This default implementation delegates to spliterator(). This baseline implementation is as good as the underlying Spliterator (wrapping is not expensive); it should be overridden if a more efficient can be produced.

Specified by:

iterator in interface Iterable<org.openrdf.model.Statement>

spliterator

default Spliterator<org.openrdf.model.Statement> spliterator()

This default implementation either delegates to forEach(Consumer), in case Spliterator.forEachRemaining(Consumer) is immediately called (more efficient), or run emit(RDFHandler, int) in a separate thread, populating a queue from where the returned Spliterator retrieves its elements. This baseline implementation should be overridden whenever possible.

Specified by:

spliterator in interface Iterable<org.openrdf.model.Statement>

forEach

default void forEach(Consumer<? super org.openrdf.model.Statement> action)
              throws RDFSourceException

This default implementation delegates to emit(RDFHandler, int), enforcing a sequential invocation (but possibly by different threads) of the supplied action. Iteration order is unspecified and may differ across successive invocations of this method. There is usually no need to override this method.

Specified by:

forEach in interface Iterable<org.openrdf.model.Statement>

Throws:

RDFSourceException - in case of errors in retrieving data from this source

stream

default Stream<org.openrdf.model.Statement> stream()

Returns a sequential Java 8 Stream over the statements of this RDFSource. This method is meant for integration with the Java 8 Stream API. Its default implementation builds on top of the Spliterator returned by spliterator(). There is usually no need to override this method.

Returns:

a sequential Stream over the statements of this RDFSource

parallelStream

default Stream<org.openrdf.model.Statement> parallelStream()

Returns a parallel Java 8 Stream over the statements of this RDFSource. This method is meant for integration with the Java 8 Stream API. Its default implementation builds on top of the Spliterator returned by spliterator(). There is usually no need to override this method.

Returns:

a parallel Stream over the statements of this RDFSource