org.openrdf.sail

Interface SailConnection

All Known Subinterfaces:

NotifyingSailConnection

All Known Implementing Classes:

NotifyingSailConnectionBase, NotifyingSailConnectionWrapper, SailConnectionBase, SailConnectionWrapper

public interface SailConnection

A connection to an RDF Sail object. A SailConnection is active from the moment it is created until it is closed. Care should be taken to properly close SailConnections as they might block concurrent queries and/or updates on the Sail while active, depending on the Sail-implementation that is being used.

Author:

jeen, Arjohn Kampman

Method Summary

Methods

Modifier and Type	Method and Description
void	addStatement(Resource subj, URI pred, Value obj, Resource... contexts) Adds a statement to the store.
void	addStatement(UpdateContext op, Resource subj, URI pred, Value obj, Resource... contexts) Adds a statement to the store.
void	begin() Begins a transaction requiring commit() or rollback() to be called to close the transaction.
void	clear(Resource... contexts) Removes all statements from the specified/all contexts.
void	clearNamespaces() Removes all namespace declarations from the repository.
void	close() Closes the connection.
void	commit() Commits any updates that have been performed since the last time commit() or rollback() was called.
void	endUpdate(UpdateContext op) Indicates that the given op will not be used in any call again.
CloseableIteration<? extends BindingSet,QueryEvaluationException>	evaluate(TupleExpr tupleExpr, Dataset dataset, BindingSet bindings, boolean includeInferred) Evaluates the supplied TupleExpr on the data contained in this Sail object, using the (optional) dataset and supplied bindings as input parameters.
CloseableIteration<? extends Resource,SailException>	getContextIDs() Returns the set of all unique context identifiers that are used to store statements.
String	getNamespace(String prefix) Gets the namespace that is associated with the specified prefix, if any.
CloseableIteration<? extends Namespace,SailException>	getNamespaces() Gets the namespaces relevant to the data contained in this Sail object.
CloseableIteration<? extends Statement,SailException>	getStatements(Resource subj, URI pred, Value obj, boolean includeInferred, Resource... contexts) Gets all statements from the specified contexts that have a specific subject, predicate and/or object.
boolean	isActive() Indicates if a transaction is currently active on the connection.
boolean	isOpen() Checks whether this SailConnection is open.
void	prepare() Checks for an error state in the active transaction that would force the transaction to be rolled back.
void	removeNamespace(String prefix) Removes a namespace declaration by removing the association between a prefix and a namespace name.
void	removeStatement(UpdateContext op, Resource subj, URI pred, Value obj, Resource... contexts) Removes all statements matching the specified subject, predicate and object from the repository.
void	removeStatements(Resource subj, URI pred, Value obj, Resource... contexts) Removes all statements matching the specified subject, predicate and object from the repository.
void	rollback() Rolls back the transaction, discarding any uncommitted changes that have been made in this SailConnection.
void	setNamespace(String prefix, String name) Sets the prefix for a namespace.
long	size(Resource... contexts) Returns the number of (explicit) statements in the store, or in specific contexts.
void	startUpdate(UpdateContext op) Signals the start of an update operation.

Method Detail

isOpen

boolean isOpen()
               throws SailException

Checks whether this SailConnection is open. A SailConnection is open from the moment it is created until it is closed.

Throws:

SailException

See Also:

close()

close

void close()
           throws SailException

Closes the connection. Any updates that haven't been committed yet will be rolled back. The connection can no longer be used once it is closed.

Throws:

SailException

evaluate

CloseableIteration<? extends BindingSet,QueryEvaluationException> evaluate(TupleExpr tupleExpr,
                                                                         Dataset dataset,
                                                                         BindingSet bindings,
                                                                         boolean includeInferred)
                                                                           throws SailException

Evaluates the supplied TupleExpr on the data contained in this Sail object, using the (optional) dataset and supplied bindings as input parameters.

Parameters:

tupleExpr - The tuple expression to evaluate.

dataset - The dataset to use for evaluating the query, null to use the Sail's default dataset.

bindings - A set of input parameters for the query evaluation. The keys reference variable names that should be bound to the value they map to.

includeInferred - Indicates whether inferred triples are to be considered in the query result. If false, no inferred statements are returned; if true, inferred statements are returned if available

Returns:

The TupleQueryResult.

Throws:

SailException - If the Sail object encountered an error or unexpected situation internally.

IllegalStateException - If the connection has been closed.

getContextIDs

CloseableIteration<? extends Resource,SailException> getContextIDs()
                                                                   throws SailException

Returns the set of all unique context identifiers that are used to store statements.

Returns:

An iterator over the context identifiers, should not contain any duplicates.

Throws:

IllegalStateException - If the connection has been closed.

SailException

getStatements

CloseableIteration<? extends Statement,SailException> getStatements(Resource subj,
                                                                  URI pred,
                                                                  Value obj,
                                                                  boolean includeInferred,
                                                                  Resource... contexts)
                                                                    throws SailException

Gets all statements from the specified contexts that have a specific subject, predicate and/or object. All three parameters may be null to indicate wildcards. The includeInferred parameter can be used to control which statements are fetched: all statements or only the statements that have been added explicitly.

Parameters:

subj - A Resource specifying the subject, or null for a wildcard.

pred - A URI specifying the predicate, or null for a wildcard.

obj - A Value specifying the object, or null for a wildcard.

includeInferred - if false, no inferred statements are returned; if true, inferred statements are returned if available

contexts - The context(s) to get the data from. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.

Returns:

The statements matching the specified pattern.

Throws:

SailException - If the Sail object encountered an error or unexpected situation internally.

IllegalStateException - If the connection has been closed.

size

long size(Resource... contexts)
          throws SailException

Returns the number of (explicit) statements in the store, or in specific contexts.

Parameters:

contexts - The context(s) to determine the size of. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.

Returns:

The number of explicit statements in this store, or in the specified context(s).

Throws:

IllegalStateException - If the connection has been closed.

SailException

begin

void begin()
           throws SailException

Begins a transaction requiring commit() or rollback() to be called to close the transaction.

Throws:

SailException - If the connection could not start a transaction or if a transaction is already active on this connection.

Since:

2.7.0

prepare

void prepare()
             throws SailException

Checks for an error state in the active transaction that would force the transaction to be rolled back. This is an optional call; calling or not calling this method should have no effect on the outcome of commit() or rollback(). A call to this method must be followed by (in the same thread) with a call to prepare() , commit(), rollback(), or close(). This method may be called multiple times within the same transaction by the same thread. If this method returns normally, the caller can reasonably expect that a subsequent call to commit() will also return normally. If this method returns with an exception the caller should treat the exception as if it came from a call to commit().

Throws:

UnknownSailTransactionStateException - If the transaction state can not be determined (this can happen for instance when communication between client and server fails or times-out). It does not indicate a problem with the integrity of the store.

SailException - If there is an active transaction and it cannot be committed.

IllegalStateException - If the connection has been closed or prepare was already called by another thread.

Since:

2.7.0

commit

void commit()
            throws SailException

Commits any updates that have been performed since the last time commit() or rollback() was called.

Throws:

UnknownSailTransactionStateException - If the transaction state can not be determined (this can happen for instance when communication between client and server fails or times-out). It does not indicate a problem with the integrity of the store.

SailException - If the SailConnection could not be committed.

IllegalStateException - If the connection has been closed.

rollback

void rollback()
              throws SailException

Rolls back the transaction, discarding any uncommitted changes that have been made in this SailConnection.

Throws:

UnknownSailTransactionStateException - If the transaction state can not be determined (this can happen for instance when communication between client and server fails or times-out). It does not indicate a problem with the integrity of the store.

SailException - If the SailConnection could not be rolled back.

IllegalStateException - If the connection has been closed.

isActive

boolean isActive()
                 throws UnknownSailTransactionStateException

Indicates if a transaction is currently active on the connection. A transaction is active if begin() has been called, and becomes inactive after commit() or rollback() has been called.

Returns:

true iff a transaction is active, false iff no transaction is active.

Throws:

UnknownSailTransactionStateException - if the transaction state can not be determined (this can happen for instance when communication between client and server fails or times out).

Since:

2.7.0

addStatement

void addStatement(Resource subj,
                URI pred,
                Value obj,
                Resource... contexts)
                  throws SailException

Adds a statement to the store.

Parameters:

subj - The subject of the statement to add.

pred - The predicate of the statement to add.

obj - The object of the statement to add.

contexts - The context(s) to add the statement to. Note that this parameter is a vararg and as such is optional. If no contexts are specified, a context-less statement will be added.

Throws:

SailException - If the statement could not be added, for example because no transaction is active.

IllegalStateException - If the connection has been closed.

removeStatements

void removeStatements(Resource subj,
                    URI pred,
                    Value obj,
                    Resource... contexts)
                      throws SailException

Removes all statements matching the specified subject, predicate and object from the repository. All three parameters may be null to indicate wildcards.

Parameters:

subj - The subject of the statement that should be removed, or null to indicate a wildcard.

pred - The predicate of the statement that should be removed, or null to indicate a wildcard.

obj - The object of the statement that should be removed , or null to indicate a wildcard. *

contexts - The context(s) from which to remove the statement. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.

Throws:

SailException - If the statement could not be removed, for example because no transaction is active.

IllegalStateException - If the connection has been closed.

startUpdate

void startUpdate(UpdateContext op)
                 throws SailException

Signals the start of an update operation. The given op maybe passed to subsequent addStatement(UpdateContext, Resource, URI, Value, Resource...) or removeStatement(UpdateContext, Resource, URI, Value, Resource...) calls before endUpdate(UpdateContext) is called.

Throws:

SailException

addStatement

void addStatement(UpdateContext op,
                Resource subj,
                URI pred,
                Value obj,
                Resource... contexts)
                  throws SailException

Adds a statement to the store. Called when adding statements through a UpdateExpr operation.

Parameters:

op - operation properties of the UpdateExpr operation producing these statements.

subj - The subject of the statement to add.

pred - The predicate of the statement to add.

obj - The object of the statement to add.

contexts - The context(s) to add the statement to. Note that this parameter is a vararg and as such is optional. If no contexts are specified, a context-less statement will be added.

Throws:

SailException - If the statement could not be added, for example because no transaction is active.

IllegalStateException - If the connection has been closed.

removeStatement

void removeStatement(UpdateContext op,
                   Resource subj,
                   URI pred,
                   Value obj,
                   Resource... contexts)
                     throws SailException

Removes all statements matching the specified subject, predicate and object from the repository. All three parameters may be null to indicate wildcards. Called when removing statements through a UpdateExpr operation.

Parameters:

op - operation properties of the UpdateExpr operation removing these statements.

subj - The subject of the statement that should be removed.

pred - The predicate of the statement that should be removed.

obj - The object of the statement that should be removed.

contexts - The context(s) from which to remove the statement. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.

Throws:

SailException - If the statement could not be removed, for example because no transaction is active.

IllegalStateException - If the connection has been closed.

endUpdate

void endUpdate(UpdateContext op)
               throws SailException

Indicates that the given op will not be used in any call again. Implementations should use this to flush of any temporary operation states that may have occurred.

Parameters:

op -

Throws:

SailException

clear

void clear(Resource... contexts)
           throws SailException

Removes all statements from the specified/all contexts. If no contexts are specified the method operates on the entire repository.

Parameters:

contexts - The context(s) from which to remove the statements. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.

Throws:

SailException - If the statements could not be removed.

IllegalStateException - If the connection has been closed.

getNamespaces

CloseableIteration<? extends Namespace,SailException> getNamespaces()
                                                                    throws SailException

Gets the namespaces relevant to the data contained in this Sail object.

Returns:

An iterator over the relevant namespaces, should not contain any duplicates.

Throws:

SailException - If the Sail object encountered an error or unexpected situation internally.

IllegalStateException - If the connection has been closed.

getNamespace

String getNamespace(String prefix)
                    throws SailException

Gets the namespace that is associated with the specified prefix, if any.

Parameters:

prefix - A namespace prefix, or an empty string in case of the default namespace.

Returns:

The namespace name that is associated with the specified prefix, or null if there is no such namespace.

Throws:

SailException - If the Sail object encountered an error or unexpected situation internally.

NullPointerException - In case prefix is null.

IllegalStateException - If the connection has been closed.

setNamespace

void setNamespace(String prefix,
                String name)
                  throws SailException

Sets the prefix for a namespace.

Parameters:

prefix - The new prefix, or an empty string in case of the default namespace.

name - The namespace name that the prefix maps to.

Throws:

SailException - If the Sail object encountered an error or unexpected situation internally.

NullPointerException - In case prefix or name is null.

IllegalStateException - If the connection has been closed.

removeNamespace

void removeNamespace(String prefix)
                     throws SailException

Removes a namespace declaration by removing the association between a prefix and a namespace name.

Parameters:

prefix - The namespace prefix, or an empty string in case of the default namespace.

Throws:

SailException - If the Sail object encountered an error or unexpected situation internally.

NullPointerException - In case prefix is null.

IllegalStateException - If the connection has been closed.

clearNamespaces

void clearNamespaces()
                     throws SailException

Removes all namespace declarations from the repository.

Throws:

SailException - If the Sail object encountered an error or unexpected situation internally.

IllegalStateException - If the connection has been closed.