eu.fbk.knowledgestore.triplestore

Interface TripleTransaction

All Known Implementing Classes:

ForwardingTripleTransaction

public interface TripleTransaction

A triple store transaction.

A TripleTransaction is a unit of work over the contents of a TripleStore that provides atomicity (i.e., changes are either completely stored or discarded), isolation (i.e., other transaction do not see the modifications of this transaction) and durability (i.e., changes are persisted across different program runs) guarantees.

A TripleTransaction supports the following four main features:

• Statement retrieval, via method get(Resource, URI, Value, Resource);
• SPARQL querying, via method #query(SelectQuery, BindingSet);
• Inference materialization, via method infer(Handler)
• Triple modification, via bulk methods add(Iterable) and remove(Iterable).

Note that the latter two functionalities are not available for read-only transactions (an IllegalStateException is thrown in that case).

Transactions are terminated via end(boolean), whose parameter specifies whether changes should be committed. Method end() always tries to terminate the transaction: if it throws an IOException exception a rollback must be assumed, even if a commit was asked; if it throws a DataCorruptedException, then neither commit or rollback were possible and the TripleStore is left in some unpredictable state with no possibility of automatic recovery. In that case, external code may resort to the TripleStore.reset() and re-population procedure to recover the situation. In case the JVM is abruptly shutdown during a transaction, the effects of the transaction should be the same as if a rollback was performed.

TripleTransaction objects are not required to be thread safe. Access by at most one thread at a time can be assumed and must be guaranteed externally, with the only exception of method end(boolean) that can be called at any moment by any thread in case the transaction need to be rolled back. Note also that it must be allowed for operations to be issued while streams from previous operations are still open; if a stream is open and a write operations is performed that affects one of the statements/query solutions still to be returned by the stream (or made a statement/query solution returnable/not returnable by the stream), then the behaviour of the stream is undefined.

Method Summary

Modifier and Type	Method and Description
void	add(Iterable<? extends org.openrdf.model.Statement> statements) Adds all the RDF statements in the Iterable specified to the triple store.
void	end(boolean commit) Ends the transaction, either committing or rolling back its changes (if any).
info.aduna.iteration.CloseableIteration<? extends org.openrdf.model.Statement,? extends Exception>	get(org.openrdf.model.Resource subject, org.openrdf.model.URI predicate, org.openrdf.model.Value object, org.openrdf.model.Resource context) Returns a Sesame CloseableIteration over all the RDF statements matching the (optional) subject, predicate, object, context supplied.
void	infer(Handler<? super org.openrdf.model.Statement> handler) Performs inference, materializing the logical closure of the RDF statements contained in the triple store.
info.aduna.iteration.CloseableIteration<org.openrdf.query.BindingSet,org.openrdf.query.QueryEvaluationException>	query(SelectQuery query, org.openrdf.query.BindingSet bindings, Long timeout) Evaluates the supplied SPARQL SELECT query, returning a Sesame CloseableIteration over its solutions.
void	remove(Iterable<? extends org.openrdf.model.Statement> statements) Removes all the RDF statements in the Iterable specified from the triple store.

Method Detail

get

info.aduna.iteration.CloseableIteration<? extends org.openrdf.model.Statement,? extends Exception> get(@Nullable
                                                                                                       org.openrdf.model.Resource subject,
                                                                                                       @Nullable
                                                                                                       org.openrdf.model.URI predicate,
                                                                                                       @Nullable
                                                                                                       org.openrdf.model.Value object,
                                                                                                       @Nullable
                                                                                                       org.openrdf.model.Resource context)
                                                                                                throws IOException,
                                                                                                       IllegalStateException

Returns a Sesame CloseableIteration over all the RDF statements matching the (optional) subject, predicate, object, context supplied. Null values are used as wildcard. Implementations are designed to perform high throughput statement extraction (likely more efficient than doing a SPARQL query).

Parameters:

subject - the subject to match, null to match any subject

predicate - the predicate to match, null to match any predicate

object - the object to match, null to match any object

context - the context to match, null to match any context

Returns:

an iteration over matching RDF statements

Throws:

IOException - in case some IO error occurs

IllegalStateException - if the TripleTransaction has been already ended

query

info.aduna.iteration.CloseableIteration<org.openrdf.query.BindingSet,org.openrdf.query.QueryEvaluationException> query(SelectQuery query,
                                                                                                                       @Nullable
                                                                                                                       org.openrdf.query.BindingSet bindings,
                                                                                                                       @Nullable
                                                                                                                       Long timeout)
                                                                                                                throws IOException,
                                                                                                                       UnsupportedOperationException,
                                                                                                                       IllegalStateException

Evaluates the supplied SPARQL SELECT query, returning a Sesame CloseableIteration over its solutions. The method accepts an optional BindingSet object, providing bindings for variables in the query; it can be used to instantiate parametric queries, similarly to PreparedStatements in JDBC.

Parameters:

query - the SPARQL SELECT query to evaluate

bindings - optional bindings for variables in the query;

timeout - optional timeout in milliseconds for the query

Returns:

an iteration over the results of the query

Throws:

IOException - in case some IO error occurs

UnsupportedOperationException - in case the query, while being valid according to SPARQL, uses a construct, function or feature that is not supported by the triple store implementation (refer to the implementation documentation for unsupported features)

IllegalStateException - if the TripleTransaction has been already ended

infer

void infer(@Nullable
           Handler<? super org.openrdf.model.Statement> handler)
    throws IOException,
           IllegalStateException

Performs inference, materializing the logical closure of the RDF statements contained in the triple store. The method accepts an optional Handler inferred statements can be notified to, allowing for their additional processing by external code.

Parameters:

handler - an optional handler inferred RDF statements can be notified to

Throws:

IOException - in case some IO error occurs, with no guarantee that the TripleStore is left in the same state if was when the method was called; note that this exception may trigger a rollback on the caller side

IllegalStateException - if the TripleTransaction has been already ended, or if it is read-only

add

void add(Iterable<? extends org.openrdf.model.Statement> statements)
  throws IOException,
         IllegalStateException

Adds all the RDF statements in the Iterable specified to the triple store. Implementations are designed to perform high throughput insertion. They are also allowed to buffer part or all of the operation, successfully returning before specified triples have been completely modified; in this case, it must be however guaranteed that subsequent calls to #query(SelectQuery, BindingSet) will 'see' all the triples added.

Parameters:

statements - the statements to add

Throws:

IOException - in case some IO error occurs, with no guarantee that the TripleStore is left in the same state if was when the method was called; note that this exception may trigger a rollback on the caller side

IllegalStateException - if the TripleTransaction has been already ended, or if it is read-only

remove

void remove(Iterable<? extends org.openrdf.model.Statement> statements)
     throws IOException,
            IllegalStateException

Removes all the RDF statements in the Iterable specified from the triple store. Implementations are designed to perform high throughput deletion. They are also allowed to return before specified triples have been completely removed; in this case, it must be however guaranteed that subsequent calls to #query(SelectQuery, BindingSet) will not 'see' any of the triples removed.

Parameters:

statements - the statements to remove

Throws:

IOException - in case some IO error occurs, with no guarantee that the TripleStore is left in the same state if was when the method was called; note that this exception may trigger a rollback on the caller side

IllegalStateException - if the TripleTransaction has been already ended, or if it is read-only

end

void end(boolean commit)
  throws DataCorruptedException,
         IOException,
         IllegalStateException

Ends the transaction, either committing or rolling back its changes (if any). This method always tries to terminate the transaction: if commit is requested but fails, a rollback is forced by the method and an IOException is thrown. If it is not possible either to commit or rollback, then the TripleStore is possibly left in an unknown state and a DataCorruptedException is thrown to signal a data corruption situation that cannot be automatically recovered (apart from calling TripleStore.reset() and repopulating the TripleStore).

Parameters:

commit - true in case changes made by the transaction should be committed

Throws:

IOException - in case some IO error occurs or the commit request cannot be satisfied for any reason; it is however guaranteed that a forced rollback has been performed

DataCorruptedException - in case it was not possible either to commit or rollback, which implies the state of the TripleStore is unknown and automatic recovery is not possible (hence, data is corrupted)

IllegalStateException - if the TripleTransaction has been already ended