eu.fbk.rdfpro

Interface RDFProcessor

public interface RDFProcessor

A generic RDF stream transformer.

An RDFProcessor is a reusable Java component that consumes an input stream of RDF Statements in one or more passes, produces an output stream of statements and may have side effect like writing RDF data.

An RDFProcessor can be used by means of a number of methods:

• apply(RDFSource, RDFHandler, int) and applyAsync(RDFSource, RDFHandler, int) apply the RDFProcessor to data from a given RDFSource, emitting the results to a supplied RDFHandler in one or more passes;
• wrap(RDFSource) wraps an RDFSource, returning a new RDFSource that post-process returned data with the RDFProcessor;
• wrap(RDFHandler) wraps an RDFHandler, returning a new RDFHandler that pre-process input data with the RDFProcessor.

The transformation encapsulated by an RDFProcessor may require multiple passes on input data before results can be emitted. To this end, method getExtraPasses() declares how many extra passes a RDFProcessor needs on its input with method before the result is produced in successive passes.

Implementers of this interface should provide an implementation of wrap(RDFHandler) and, optionally, of getExtraPasses() in case their RDFProcessor requires extra passes. Other methods have reasonable default implementations that do not need (in principle) to be overridden.

Implementations of this interface should be thread-safe, as it is allowed for its methods to be called concurrently by multiple threads (still, no particular contention is expected so basic synchronization is enough).

Method Summary

Modifier and Type	Method and Description
default void	apply(RDFSource input, org.openrdf.rio.RDFHandler output, int passes) Applies the processor to the supplied RDFSource, emitting output data to the specified RDFHandler in one or more passes.
default CompletableFuture<Void>	applyAsync(RDFSource input, org.openrdf.rio.RDFHandler output, int passes) Asynchronously applies the processor to the supplied RDFSource, emitting output data to the specified RDFHandler in one or more passes.
default int	getExtraPasses() Returns the number of extra passes required by the processor before starting emitting output data.
org.openrdf.rio.RDFHandler	wrap(org.openrdf.rio.RDFHandler handler) Wraps the supplied RDFHandler so to pre-process data fed to it with this RDFProcessor.
default RDFSource	wrap(RDFSource source) Wraps the supplied RDFSource so to post-process data of the source with this RDFProcessor before returning it.

Method Detail

getExtraPasses

default int getExtraPasses()

Returns the number of extra passes required by the processor before starting emitting output data. This default implementation returns 0 (the common case).

Returns:

then number of extra passes, not negative

wrap

default RDFSource wrap(RDFSource source)

Wraps the supplied RDFSource so to post-process data of the source with this RDFProcessor before returning it. Note that this method does not perform any real work, apart creating a wrapper. This default implementation delegates to wrap(RDFHandler).

Parameters:

source - the RDFSource to wrap, not null

Returns:

the wrapped RDFSource

wrap

org.openrdf.rio.RDFHandler wrap(org.openrdf.rio.RDFHandler handler)

Wraps the supplied RDFHandler so to pre-process data fed to it with this RDFProcessor. Note that this method does not perform any real work, apart creating a wrapper.

Parameters:

handler - the RDFHandler to wrap, not null

Returns:

the wrapped RDFHandler

apply

default void apply(RDFSource input,
                   org.openrdf.rio.RDFHandler output,
                   int passes)
            throws RDFSourceException,
                   org.openrdf.rio.RDFHandlerException

Applies the processor to the supplied RDFSource, emitting output data to the specified RDFHandler in one or more passes. This default implementation is based on wrap(RDFHandler).

Parameters:

input - the input RDFSource, not null

output - the output RDFHandler, not null

passes - the requested number of passes to be fed to the supplied RDFHandler (if zero nothing will be done)

Throws:

RDFSourceException - on error in retrieving data from the source

org.openrdf.rio.RDFHandlerException - on error in the supplied RDFHandler or inside the RDFProcessor

applyAsync

default CompletableFuture<Void> applyAsync(RDFSource input,
                                           org.openrdf.rio.RDFHandler output,
                                           int passes)

Asynchronously applies the processor to the supplied RDFSource, emitting output data to the specified RDFHandler in one or more passes. This method operates similarly to apply(RDFSource, RDFHandler, int), but immediately returns providing a CompletableFuture that can be used to track the result of the computation. This default implementation is based on apply(RDFSource, RDFHandler, int) (and thus indirectly on wrap(RDFHandler)) and makes use of the common thread pool provided by Environment.getPool().

Parameters:

input - the input RDFSource, not null

output - the output RDFHandler, not null

passes - the requested number of passes to be fed to the supplied RDFHandler (if zero nothing will be done)

Returns:

a CompletableFuture that can be used for querying the state of the asynchronous computation and possibly execute a callback when it ends (note that cancellation is not supported).