org.openrdf.sail.helpers

Class SailConnectionBase

java.lang.Object

org.openrdf.sail.helpers.SailConnectionBase

All Implemented Interfaces:

SailConnection

Direct Known Subclasses:

NotifyingSailConnectionBase, RdbmsConnection

public abstract class SailConnectionBase
extends Object
implements SailConnection

Abstract Class offering base functionality for SailConnection implementations.

Author:

Arjohn Kampman, Jeen Broekstra

Field Summary

Fields

Modifier and Type	Field and Description
protected ReentrantReadWriteLock	connectionLock Lock used to give the close() method exclusive access to a connection.
protected org.slf4j.Logger	logger
protected ReentrantLock	updateLock Lock used to prevent concurrent calls to update methods like addStatement, clear, commit, etc.

Constructor Summary

Constructors

Constructor and Description
SailConnectionBase(SailBase sailBase)

Method Summary

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) The default implementation buffers added statements until the update operation is complete.
protected abstract void	addStatementInternal(Resource subj, URI pred, Value obj, Resource... contexts)
protected void	autoStartTransaction() Deprecated. since 2.7.0. Use verifyIsActive() instead. We should not automatically start a transaction at the sail level. Instead, an exception should be thrown when an update is executed without first starting a transaction.
void	begin() Begins a transaction requiring SailConnection.commit() or SailConnection.rollback() to be called to close the transaction.
void	begin(IsolationLevel level) Begins a transaction with the specified IsolationLevel level, requiring SailConnection.commit() or SailConnection.rollback() to be called to close the transaction.
void	clear(Resource... contexts) Removes all statements from the specified/all contexts.
protected abstract void	clearInternal(Resource... contexts)
void	clearNamespaces() Removes all namespace declarations from the repository.
protected abstract void	clearNamespacesInternal()
void	close() Closes the connection.
protected abstract void	closeInternal()
void	commit() Commits any updates that have been performed since the last time SailConnection.commit() or SailConnection.rollback() was called.
protected abstract void	commitInternal()
void	endUpdate(UpdateContext op) Indicates that the given op will not be used in any call again.
protected void	endUpdateInternal(UpdateContext op)
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.
protected abstract CloseableIteration<? extends BindingSet,QueryEvaluationException>	evaluateInternal(TupleExpr tupleExpr, Dataset dataset, BindingSet bindings, boolean includeInferred)
void	flush() Flushes any pending updates and notify changes to listeners as appropriate.
CloseableIteration<? extends Resource,SailException>	getContextIDs() Returns the set of all unique context identifiers that are used to store statements.
protected abstract CloseableIteration<? extends Resource,SailException>	getContextIDsInternal()
protected Lock	getExclusiveConnectionLock() Deprecated. Use connectionLock directly instead.
String	getNamespace(String prefix) Gets the namespace that is associated with the specified prefix, if any.
protected abstract String	getNamespaceInternal(String prefix)
CloseableIteration<? extends Namespace,SailException>	getNamespaces() Gets the namespaces relevant to the data contained in this Sail object.
protected abstract CloseableIteration<? extends Namespace,SailException>	getNamespacesInternal()
protected Lock	getSharedConnectionLock() Deprecated. Use connectionLock directly instead.
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.
protected abstract CloseableIteration<? extends Statement,SailException>	getStatementsInternal(Resource subj, URI pred, Value obj, boolean includeInferred, Resource... contexts)
protected IsolationLevel	getTransactionIsolation() Retrieve the currently set IsolationLevel.
protected Lock	getTransactionLock() Deprecated. Use updateLock directly instead.
boolean	isActive() Indicates if a transaction is currently active on the connection.
protected boolean	isActiveOperation()
boolean	isOpen() Checks whether this SailConnection is open.
protected void	iterationClosed(org.openrdf.sail.helpers.SailBaseIteration iter) Called by SailBaseIteration to indicate that it has been closed.
void	prepare() Checks for an error state in the active transaction that would force the transaction to be rolled back.
protected <T,E extends Exception> CloseableIteration<T,E>	registerIteration(CloseableIteration<T,E> iter) Registers an iteration as active by wrapping it in a SailBaseIteration object and adding it to the list of active iterations.
void	removeNamespace(String prefix) Removes a namespace declaration by removing the association between a prefix and a namespace name.
protected abstract void	removeNamespaceInternal(String prefix)
void	removeStatement(UpdateContext op, Resource subj, URI pred, Value obj, Resource... contexts) The default implementation buffers removed statements until the update operation is complete.
void	removeStatements(Resource subj, URI pred, Value obj, Resource... contexts) Removes all statements matching the specified subject, predicate and object from the repository.
protected abstract void	removeStatementsInternal(Resource subj, URI pred, Value obj, Resource... contexts)
void	rollback() Rolls back the transaction, discarding any uncommitted changes that have been made in this SailConnection.
protected abstract void	rollbackInternal()
void	setNamespace(String prefix, String name) Sets the prefix for a namespace.
protected abstract void	setNamespaceInternal(String prefix, String name)
long	size(Resource... contexts) Returns the number of (explicit) statements in the store, or in specific contexts.
protected abstract long	sizeInternal(Resource... contexts)
protected abstract void	startTransactionInternal()
void	startUpdate(UpdateContext op) Signals the start of an update operation.
protected boolean	transactionActive()
protected void	verifyIsActive() Verifies if a transaction is currently active.
protected void	verifyIsOpen()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

protected final org.slf4j.Logger logger

connectionLock

protected final ReentrantReadWriteLock connectionLock

Lock used to give the close() method exclusive access to a connection.

• write lock: close()
• read lock: all other (public) methods

updateLock

protected final ReentrantLock updateLock

Lock used to prevent concurrent calls to update methods like addStatement, clear, commit, etc. within a transaction.

Constructor Detail

SailConnectionBase

public SailConnectionBase(SailBase sailBase)

Method Detail

isOpen

public final boolean isOpen()
                     throws SailException

Description copied from interface: SailConnection

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

Specified by:

isOpen in interface SailConnection

Throws:

SailException

See Also:

SailConnection.close()

verifyIsOpen

protected void verifyIsOpen()
                     throws SailException

Throws:

SailException

verifyIsActive

protected void verifyIsActive()
                       throws SailException

Verifies if a transaction is currently active. Throws a SailException if no transaction is active.

Throws:

SailException - if no transaction is active.

Since:

2.7.0

begin

public void begin()
           throws SailException

Description copied from interface: SailConnection

Begins a transaction requiring SailConnection.commit() or SailConnection.rollback() to be called to close the transaction. The transaction will use the default IsolationLevel level for the SAIL, as returned by Sail.getDefaultIsolationLevel().

Specified by:

begin in interface SailConnection

Throws:

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

begin

public void begin(IsolationLevel level)
           throws SailException

Description copied from interface: SailConnection

Begins a transaction with the specified IsolationLevel level, requiring SailConnection.commit() or SailConnection.rollback() to be called to close the transaction.

Specified by:

begin in interface SailConnection

Parameters:

level - the transaction isolation level on which this transaction operates.

Throws:

UnknownSailTransactionStateException - If the IsolationLevel is not supported by this implementation

SailException - If the connection could not start a transaction, if the supplied transaction isolation level is not supported, or if a transaction is already active on this connection.

getTransactionIsolation

protected IsolationLevel getTransactionIsolation()

Retrieve the currently set IsolationLevel.

Returns:

the current IsolationLevel. If no transaction is active, this may be null.

isActive

public boolean isActive()
                 throws UnknownSailTransactionStateException

Description copied from interface: SailConnection

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

Specified by:

isActive in interface SailConnection

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).

close

public final void close()
                 throws SailException

Description copied from interface: SailConnection

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.

Specified by:

close in interface SailConnection

Throws:

SailException

evaluate

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

Description copied from interface: SailConnection

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

Specified by:

evaluate in interface SailConnection

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.

getContextIDs

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

Description copied from interface: SailConnection

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

Specified by:

getContextIDs in interface SailConnection

Returns:

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

Throws:

SailException

getStatements

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

Description copied from interface: SailConnection

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.

Specified by:

getStatements in interface SailConnection

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.

size

public final long size(Resource... contexts)
                throws SailException

Description copied from interface: SailConnection

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

Specified by:

size in interface SailConnection

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:

SailException

transactionActive

protected final boolean transactionActive()

autoStartTransaction

@Deprecated
protected void autoStartTransaction()
                                         throws SailException

Deprecated. since 2.7.0. Use verifyIsActive() instead. We should not automatically start a transaction at the sail level. Instead, an exception should be thrown when an update is executed without first starting a transaction.

IMPORTANT Since Sesame 2.7.0. this method no longer automatically starts a transaction, but instead verifies if a transaction is active and if not throws an exception. The method is left in for transitional purposes only. Sail implementors are advised that by contract, any update operation on the Sail should check if a transaction has been started via SailConnection.isActive() and throw a SailException if not. Implementors can use verifyIsActive() as a convenience method for this check.

Throws:

SailException - if no transaction is active.

flush

public void flush()
           throws SailException

Description copied from interface: SailConnection

Flushes any pending updates and notify changes to listeners as appropriate. This is an optional call; calling or not calling this method should have no effect on the outcome of other calls. This method exists to give the caller more control over the efficiency when calling SailConnection.prepare(). This method may be called multiple times within the same transaction.

Specified by:

flush in interface SailConnection

Throws:

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

prepare

public void prepare()
             throws SailException

Description copied from interface: SailConnection

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 SailConnection.commit() or SailConnection.rollback(). A call to this method must be followed by (in the same thread) with a call to SailConnection.prepare() , SailConnection.commit(), SailConnection.rollback(), or SailConnection.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 SailConnection.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 SailConnection.commit().

Specified by:

prepare in interface 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 there is an active transaction and it cannot be committed.

commit

public final void commit()
                  throws SailException

Description copied from interface: SailConnection

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

Specified by:

commit in interface 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 committed.

rollback

public final void rollback()
                    throws SailException

Description copied from interface: SailConnection

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

Specified by:

rollback in interface 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.

addStatement

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

Description copied from interface: SailConnection

Adds a statement to the store.

Specified by:

addStatement in interface SailConnection

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.

removeStatements

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

Description copied from interface: SailConnection

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

Specified by:

removeStatements in interface SailConnection

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.

startUpdate

public void startUpdate(UpdateContext op)
                 throws SailException

Description copied from interface: SailConnection

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

Specified by:

startUpdate in interface SailConnection

Throws:

SailException

addStatement

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

The default implementation buffers added statements until the update operation is complete.

Specified by:

addStatement in interface SailConnection

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.

removeStatement

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

The default implementation buffers removed statements until the update operation is complete.

Specified by:

removeStatement in interface SailConnection

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.

endUpdate

public final void endUpdate(UpdateContext op)
                     throws SailException

Description copied from interface: SailConnection

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.

Specified by:

endUpdate in interface SailConnection

Throws:

SailException

endUpdateInternal

protected void endUpdateInternal(UpdateContext op)
                          throws SailException

Throws:

SailException

clear

public final void clear(Resource... contexts)
                 throws SailException

Description copied from interface: SailConnection

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

Specified by:

clear in interface SailConnection

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.

getNamespaces

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

Description copied from interface: SailConnection

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

Specified by:

getNamespaces in interface SailConnection

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.

getNamespace

public final String getNamespace(String prefix)
                          throws SailException

Description copied from interface: SailConnection

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

Specified by:

getNamespace in interface SailConnection

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.

setNamespace

public final void setNamespace(String prefix,
                               String name)
                        throws SailException

Description copied from interface: SailConnection

Sets the prefix for a namespace.

Specified by:

setNamespace in interface SailConnection

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.

removeNamespace

public final void removeNamespace(String prefix)
                           throws SailException

Description copied from interface: SailConnection

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

Specified by:

removeNamespace in interface SailConnection

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.

clearNamespaces

public final void clearNamespaces()
                           throws SailException

Description copied from interface: SailConnection

Removes all namespace declarations from the repository.

Specified by:

clearNamespaces in interface SailConnection

Throws:

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

getSharedConnectionLock

protected Lock getSharedConnectionLock()
                                throws SailException

Deprecated. Use connectionLock directly instead.

Throws:

SailException

getExclusiveConnectionLock

protected Lock getExclusiveConnectionLock()
                                   throws SailException

Deprecated. Use connectionLock directly instead.

Throws:

SailException

getTransactionLock

@Deprecated
protected Lock getTransactionLock()
                                       throws SailException

Deprecated. Use updateLock directly instead.

Throws:

SailException

registerIteration

protected <T,E extends Exception> CloseableIteration<T,E> registerIteration(CloseableIteration<T,E> iter)

Registers an iteration as active by wrapping it in a SailBaseIteration object and adding it to the list of active iterations.

iterationClosed

protected void iterationClosed(org.openrdf.sail.helpers.SailBaseIteration iter)

Called by SailBaseIteration to indicate that it has been closed.

closeInternal

protected abstract void closeInternal()
                               throws SailException

Throws:

SailException

evaluateInternal

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

Throws:

SailException

getContextIDsInternal

protected abstract CloseableIteration<? extends Resource,SailException> getContextIDsInternal()
                                                                                       throws SailException

Throws:

SailException

getStatementsInternal

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

Throws:

SailException

sizeInternal

protected abstract long sizeInternal(Resource... contexts)
                              throws SailException

Throws:

SailException

startTransactionInternal

protected abstract void startTransactionInternal()
                                          throws SailException

Throws:

SailException

commitInternal

protected abstract void commitInternal()
                                throws SailException

Throws:

SailException

rollbackInternal

protected abstract void rollbackInternal()
                                  throws SailException

Throws:

SailException

addStatementInternal

protected abstract void addStatementInternal(Resource subj,
                                             URI pred,
                                             Value obj,
                                             Resource... contexts)
                                      throws SailException

Throws:

SailException

removeStatementsInternal

protected abstract void removeStatementsInternal(Resource subj,
                                                 URI pred,
                                                 Value obj,
                                                 Resource... contexts)
                                          throws SailException

Throws:

SailException

clearInternal

protected abstract void clearInternal(Resource... contexts)
                               throws SailException

Throws:

SailException

getNamespacesInternal

protected abstract CloseableIteration<? extends Namespace,SailException> getNamespacesInternal()
                                                                                        throws SailException

Throws:

SailException

getNamespaceInternal

protected abstract String getNamespaceInternal(String prefix)
                                        throws SailException

Throws:

SailException

setNamespaceInternal

protected abstract void setNamespaceInternal(String prefix,
                                             String name)
                                      throws SailException

Throws:

SailException

removeNamespaceInternal

protected abstract void removeNamespaceInternal(String prefix)
                                         throws SailException

Throws:

SailException

clearNamespacesInternal

protected abstract void clearNamespacesInternal()
                                         throws SailException

Throws:

SailException

isActiveOperation

protected boolean isActiveOperation()