org.openrdf.sail
Interface SailConnection

All Known Subinterfaces:

InferencerConnection, NotifyingSailConnection

All Known Implementing Classes:

AutoCommitInferencerConnection, AutoCommitNotifyingConnection, AutoCommitSailConnection, DatasetConnection, InferencerConnectionWrapper, MemoryStoreConnection, NativeStoreConnection, NotifyingSailConnectionBase, NotifyingSailConnectionWrapper, PreconditionInferencerConnection, PreconditionSailConnection, RdbmsConnection, SailConnectionBase, SailConnectionWrapper, SynchronizedInferencerConnection, SynchronizedSailConnection, TrackingInferencerConnection, TrackingSailConnection

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

void	addStatement(Resource subj, URI pred, Value obj, Resource... contexts) Adds a statement to each context in the specified contexts.
void	begin() Begins a transaction requiring commit() or rollback() to be called to close the transaction.
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.
Cursor<? extends BindingSet>	evaluate(QueryModel query, 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.
Cursor<? extends Resource>	getContextIDs() Returns the set of all unique context identifiers that are used to store statements.
String	getNamespace(String prefix) Gets the namespace that is mapped to the specified prefix.
Cursor<? extends Namespace>	getNamespaces() Gets the namespaces relevant to the data contained in this Sail object.
Cursor<? extends Statement>	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.
Isolation	getTransactionIsolation() Retrieves this connection's current transaction isolation level.
ValueFactory	getValueFactory() Gets a ValueFactory object that can be used to create URI-, blank node-, literal- and statement objects.
boolean	isAutoCommit() Indicates if the connection is in auto-commit mode.
boolean	isOpen() Checks whether this SailConnection is open.
boolean	isReadOnly() Indicates whether this connection is in read-only mode.
void	removeNamespace(String prefix) Removes a namespace declaration by removing the association between a prefix and a namespace name.
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 SailConnection, discarding any uncommitted changes that have been made in this SailConnection.
void	setNamespace(String prefix, String name) Sets the prefix of a namespace.
void	setReadOnly(boolean readOnly) Puts this connection in read-only mode as a hint to the driver to enable repository optimizations.
void	setTransactionIsolation(Isolation isolation) Attempts to change the transaction isolation level for this connection to the specified value.
long	size(Resource subj, URI pred, Value obj, boolean includeInferred, Resource... contexts) Returns the number of statements matching the specified pattern.

Method Detail

isOpen

boolean isOpen()
               throws StoreException

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

Throws:

StoreException

See Also:

close()

close

void close()
           throws StoreException

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:

StoreException

getTransactionIsolation

Isolation getTransactionIsolation()
                                  throws StoreException

Retrieves this connection's current transaction isolation level.

Returns:

The current transaction isolation level.

Throws:

StoreException - If an access error occurs or this method is called on a closed connection

See Also:

setTransactionIsolation(org.openrdf.store.Isolation)

setTransactionIsolation

void setTransactionIsolation(Isolation isolation)
                             throws StoreException

Attempts to change the transaction isolation level for this connection to the specified value.

Note: If this method is called during a transaction, the result is implementation-defined.

Parameters:

isolation - Any Isolation except for NONE, since that indicates that transactions are not supported.

Throws:

StoreException - If an access error occurs, this method is called on a closed connection

See Also:

getTransactionIsolation()

isReadOnly

boolean isReadOnly()
                   throws StoreException

Indicates whether this connection is in read-only mode.

Returns:

true if this Connection object is read-only; false otherwise.

Throws:

StoreException - If a repository access error occurs.

setReadOnly

void setReadOnly(boolean readOnly)
                 throws StoreException

Puts this connection in read-only mode as a hint to the driver to enable repository optimizations.

Note: This method cannot be called during a transaction.

Parameters:

readOnly - true enables read-only mode; false disables it

Throws:

StoreException - If a repository access error occurs or this method is called during a transaction.

getValueFactory

ValueFactory getValueFactory()

Gets a ValueFactory object that can be used to create URI-, blank node-, literal- and statement objects.

Returns:

a ValueFactory object for this Sail object.

evaluate

Cursor<? extends BindingSet> evaluate(QueryModel query,
                                      BindingSet bindings,
                                      boolean includeInferred)
                                      throws StoreException

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:

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

getContextIDs

Cursor<? extends Resource> getContextIDs()
                                         throws StoreException

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:

StoreException

getStatements

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

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 supplied the method operates on the entire repository.

Returns:

The statements matching the specified pattern.

Throws:

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

size

long size(Resource subj,
          URI pred,
          Value obj,
          boolean includeInferred,
          Resource... contexts)
          throws StoreException

Returns the number of statements matching the specified pattern.

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 - Indicates whether inferred statements should be counted.

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 supplied the method operates on the entire repository.

Returns:

The number of explicit statements in this Sail.

Throws:

StoreException

isAutoCommit

boolean isAutoCommit()
                     throws StoreException

Indicates if the connection is in auto-commit mode. The connection is not in auto-commit when begin() has been called but commit() or rollback() still has to be called to finish the transaction.

Throws:

StoreException - If a repository access error occurs.

begin

void begin()
           throws StoreException

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

Throws:

StoreException - If the connection could not start a transaction, or if it already has an active transaction.

See Also:

isAutoCommit()

commit

void commit()
            throws StoreException

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

Throws:

StoreException - If the SailConnection could not be committed, or if the connection does not have an active connection.

rollback

void rollback()
              throws StoreException

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

Throws:

StoreException - If the SailConnection could not be rolled back, or if the connection does not have an active connection.

addStatement

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

Adds a statement to each context in the specified contexts.

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 supplied the method operates on the entire repository.

Throws:

StoreException - If the statement could not be added.

removeStatements

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

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 supplied the method operates on the entire repository.

Throws:

StoreException - If the statement could not be removed.

getNamespaces

Cursor<? extends Namespace> getNamespaces()
                                          throws StoreException

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:

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

getNamespace

String getNamespace(String prefix)
                    throws StoreException

Gets the namespace that is mapped to the specified prefix.

Parameters:

prefix - A namespace prefix.

Returns:

The namespace name that the specified prefix maps to.

Throws:

StoreException

setNamespace

void setNamespace(String prefix,
                  String name)
                  throws StoreException

Sets the prefix of a namespace.

Parameters:

prefix - The new prefix.

name - The namespace name that the prefix maps to.

Throws:

StoreException

removeNamespace

void removeNamespace(String prefix)
                     throws StoreException

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

Parameters:

prefix - The namespace prefix of which the assocation with a namespace name is to be removed.

Throws:

StoreException - If the namespace prefix could not be removed.

clearNamespaces

void clearNamespaces()
                     throws StoreException

Removes all namespace declarations from the repository.

Throws:

StoreException - If the namespaces could not be removed.