com.bigdata.rdf.sail
Class BigdataSail.BigdataSailConnection

java.lang.Object
  com.bigdata.rdf.sail.BigdataSail.BigdataSailConnection

All Implemented Interfaces:

NotifyingSailConnection, SailConnection

Enclosing class:

BigdataSail

public class BigdataSail.BigdataSailConnection
extends Object
implements NotifyingSailConnection

Inner class implements the SailConnection. Some additional functionality is available on this class, including computeClosure().

Author:

Bryan Thompson TODO This should be made into a static class. As it is, there is a possibility for subtle errors introduced by inheritence of variables from the BigdataSail. For example, this was causing a problem with the close() method on this class and on the classes derived from this class.

Field Summary

protected DelegatingChangeLog	changeLog Note: This needs to be visible to BigdataSailRWTxConnection#commit2().
protected AbstractTripleStore	database The database view.
protected boolean	openConn True iff the SailConnection is open.
protected boolean	readOnly True iff the database view is read-only.

Constructor Summary

protected	BigdataSail.BigdataSailConnection(AbstractTripleStore database, Lock lock, boolean unisolated) Create a SailConnection for the database.
protected	BigdataSail.BigdataSailConnection(Lock lock, boolean unisolated)

Method Summary

void	addChangeLog(IChangeLog changeLog) Set the change log on the SAIL connection.
void	addConnectionListener(SailConnectionListener listener) Note: This method is strongly discouraged as it imposes an extremely high burden on the database requiring the materialization at the client of every statement to be added or removed from the database in the scope of this SailConnection.
void	addStatement(Resource s, URI p, Value o, Resource... contexts) Sesame has a concept of a "null" graph.
protected void	assertOpenConn()
protected void	assertWritableConn()
protected void	attach(AbstractTripleStore database) Attach to a new database view.
void	clear(Resource... contexts)
void	clearNamespaces()
void	close() Note: This does NOT implicitly rollback() the SailConnection.
void	commit() Commit the write set.
long	commit2() Commit the write set.
void	computeClosure() Computes the closure of the triple store for RDF(S)+ entailments.
CloseableIteration<? extends BindingSet,QueryEvaluationException>	evaluate(QueryRoot queryRoot, Dataset dataset, BindingSet bindings, boolean includeInferred) Deprecated. Consider removing this method from our public API. It is no longer in any code path for the bigdata code base. Embedded applications requiring high level evaluation should use BigdataSailRepositoryConnection. It does not call through here, but goes directly to the ASTEvalHelper.
CloseableIteration<? extends BindingSet,QueryEvaluationException>	evaluate(TupleExpr tupleExpr, Dataset dataset, BindingSet bindings, boolean includeInferred) Bigdata now uses an internal query model which differs significantly from the Sesame query model.
long	exactSize(Resource... contexts) Note: This method is quite expensive since it must materialize all statement in either the database or in the specified context(s) and then filter for the explicit statements in order to obtain an exact count.
void	executeUpdate(UpdateExpr updateExpr, Dataset dataset, BindingSet bindingSet, boolean includeInferred) Bigdata now uses an internal query model which differs significantly from the Sesame query model.
protected void	finalize() Invoke close, which will be harmless if we are already closed.
protected void	fireSailChangedEvent(boolean added, Statement stmt) Notifies SailConnectionListeners if one or more statements have been added to or removed from the repository using the SAIL methods: #addStatement(Resource, URI, Value) #removeStatements(Resource, URI, Value) #clearRepository()
void	flush() Flush the statement buffers.
protected void	flushStatementBuffers(boolean flushAssertBuffer, boolean flushRetractBuffer) Flush pending assertions and/or retractions to the database using efficient batch operations.
boolean	getAllowAutoCommit() Used by the RepositoryConnection to determine whether or not to allow auto-commits.
protected StatementBuffer<Statement>	getAssertionBuffer() Return the assertion buffer.
BigdataSail	getBigdataSail()
CloseableIteration<? extends Resource,SailException>	getContextIDs()
String	getNamespace(String prefix)
com.bigdata.rdf.sail.BigdataSail.BigdataSailConnection.NamespaceIterator	getNamespaces()
protected StatementBuffer<Statement>	getRetractionBuffer() Return the retraction buffer (truth maintenance only).
CloseableIteration<? extends Statement,SailException>	getStatements(Resource s, URI p, Value o, boolean includeInferred, Resource... contexts) Note: if the context is null, then you will see data from each context in a quad store, including anything in the BigdataSail.NULL_GRAPH.
CloseableIteration<? extends Statement,SailException>	getStatements(Resource s, URI p, Value o, Resource context)
AbstractTripleStore	getTripleStore() The implementation object.
boolean	isOpen()
boolean	isQueryTimeExpander() When true, SAIL will compute entailments at query time that were excluded from forward closure.
boolean	isReadOnly() When true, the connection does not permit mutation.
boolean	isUnisolated() Return true if this is the ITx.UNISOLATED connection.
void	removeAllEntailments() Removes all "inferred" statements from the database and the proof chains (if any) associated with those inferences (does NOT commit the database).
void	removeConnectionListener(SailConnectionListener listener)
void	removeNamespace(String prefix)
void	removeStatements(Resource s, URI p, Value o, Resource... contexts)
int	removeStatements(Resource s, URI p, Value o, Resource c) Note: The CONTEXT is ignored when in statementIdentifier mode!
void	rollback() Note: The semantics depend on the Options#STORE_CLASS.
void	setNamespace(String prefix, String namespace)
long	size(Resource... contexts) Count the statements in the specified contexts.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

database

protected AbstractTripleStore database

The database view.

readOnly

protected boolean readOnly

True iff the database view is read-only.

openConn

protected boolean openConn

True iff the SailConnection is open.

changeLog

protected DelegatingChangeLog changeLog

Note: This needs to be visible to BigdataSailRWTxConnection#commit2().

Constructor Detail

BigdataSail.BigdataSailConnection

protected BigdataSail.BigdataSailConnection(Lock lock,
                                            boolean unisolated)

BigdataSail.BigdataSailConnection

protected BigdataSail.BigdataSailConnection(AbstractTripleStore database,
                                            Lock lock,
                                            boolean unisolated)

Create a SailConnection for the database.

Parameters:

database - The database. If this is a read-only view, then the SailConnection will not support update.

Method Detail

toString

public String toString()

Overrides:

toString in class Object

getBigdataSail

public BigdataSail getBigdataSail()

getAssertionBuffer

protected StatementBuffer<Statement> getAssertionBuffer()

Return the assertion buffer.

The assertion buffer is used to buffer statements that are being asserted so as to maximize the opportunity for batch writes. Truth maintenance (if enabled) will be performed no later than the commit of the transaction.

Note: When non-null and non-empty, the buffer MUST be flushed (a) if a transaction completes (otherwise writes will not be stored on the database); or (b) if there is a read against the database during a transaction (otherwise reads will not see the unflushed statements).

Note: if BigdataSail.truthMaintenance is enabled then this buffer is backed by a temporary store which accumulates the SPOs to be asserted. Otherwise it will write directly on the database each time it is flushed, including when it overflows.

getRetractionBuffer

protected StatementBuffer<Statement> getRetractionBuffer()

Return the retraction buffer (truth maintenance only).

The retraction buffer is used by the SailConnection API IFF truth maintenance is enabled since the only methods available on the Sail to delete statements, #removeStatements(Resource, URI, Value) and removeStatements(Resource, URI, Value, Resource[]), each accepts a statement pattern rather than a set of statements. The AbstractTripleStore directly supports removal of statements matching a triple pattern, so we do not buffer retractions for those method UNLESS truth maintenance is enabled.

attach

protected void attach(AbstractTripleStore database)

Attach to a new database view. Useful for transactions.

Parameters:

database -

getTripleStore

public AbstractTripleStore getTripleStore()

The implementation object.

isQueryTimeExpander

public final boolean isQueryTimeExpander()

When true, SAIL will compute entailments at query time that were excluded from forward closure.

See Also:

BigdataSail.Options.QUERY_TIME_EXPANDER

isReadOnly

public final boolean isReadOnly()

When true, the connection does not permit mutation.

isUnisolated

public final boolean isUnisolated()

Return true if this is the ITx.UNISOLATED connection.

getAllowAutoCommit

public boolean getAllowAutoCommit()

Used by the RepositoryConnection to determine whether or not to allow auto-commits.

See Also:

BigdataSail.Options.ALLOW_AUTO_COMMIT

addConnectionListener

public void addConnectionListener(SailConnectionListener listener)

Note: This method is strongly discouraged as it imposes an extremely high burden on the database requiring the materialization at the client of every statement to be added or removed from the database in the scope of this SailConnection. Further, while the client is only notified for explicit statements added or removed, it is possible that a statement remains entailed in the database regardless of its removal.

Specified by:

addConnectionListener in interface NotifyingSailConnection

removeConnectionListener

public void removeConnectionListener(SailConnectionListener listener)

Specified by:

removeConnectionListener in interface NotifyingSailConnection

fireSailChangedEvent

protected void fireSailChangedEvent(boolean added,
                                    Statement stmt)

Notifies SailConnectionListeners if one or more statements have been added to or removed from the repository using the SAIL methods:

• #addStatement(Resource, URI, Value)
• #removeStatements(Resource, URI, Value)
• #clearRepository()

TODO:

javadoc update.

setNamespace

public void setNamespace(String prefix,
                         String namespace)
                  throws SailException

Specified by:

setNamespace in interface SailConnection

Throws:

SailException

getNamespace

public String getNamespace(String prefix)

Specified by:

getNamespace in interface SailConnection

removeNamespace

public void removeNamespace(String prefix)

Specified by:

removeNamespace in interface SailConnection

clearNamespaces

public void clearNamespaces()

Specified by:

clearNamespaces in interface SailConnection

getNamespaces

public com.bigdata.rdf.sail.BigdataSail.BigdataSailConnection.NamespaceIterator getNamespaces()

Specified by:

getNamespaces in interface SailConnection

addStatement

public void addStatement(Resource s,
                         URI p,
                         Value o,
                         Resource... contexts)
                  throws SailException

Sesame has a concept of a "null" graph. Any statement inserted whose context position is NOT bound will be inserted into the "null" graph. Statements inserted into the "null" graph are visible from the SPARQL default graph, when no data set is specified (in this case all statements in all contexts are visible).

Specified by:

addStatement in interface SailConnection

Throws:

SailException

See Also:

BigdataSail.NULL_GRAPH

clear

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

Specified by:

clear in interface SailConnection

Throws:

SailException

size

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

Count the statements in the specified contexts. Returns an exact size or an upper bound depending on the value of BigdataSail.Options.EXACT_SIZE. Exact size is an extremely expensive operation, which we turn off by default. In default mode, an upper bound is given for the total number of statements in the database, explicit and inferred. In exact size mode, the entire index will be visited and materialized and each explicit statement will be counted.

Specified by:

size in interface SailConnection

Throws:

SailException

See Also:

BigdataSail.Options.EXACT_SIZE

exactSize

public long exactSize(Resource... contexts)
               throws SailException

Note: This method is quite expensive since it must materialize all statement in either the database or in the specified context(s) and then filter for the explicit statements in order to obtain an exact count. See AbstractTripleStore.getStatementCount() or IAccessPath#rangeCount() for efficient methods for reporting on the #of statements in the database or within a specific context.

Throws:

SailException

See Also:

BigdataSail.Options.EXACT_SIZE

removeStatements

public void removeStatements(Resource s,
                             URI p,
                             Value o,
                             Resource... contexts)
                      throws SailException

Specified by:

removeStatements in interface SailConnection

Throws:

SailException

removeStatements

public int removeStatements(Resource s,
                            URI p,
                            Value o,
                            Resource c)
                     throws SailException

Note: The CONTEXT is ignored when in statementIdentifier mode!

Throws:

SailException

getContextIDs

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

Specified by:

getContextIDs in interface SailConnection

Throws:

SailException

rollback

public void rollback()
              throws SailException

Note: The semantics depend on the Options#STORE_CLASS. See ITripleStore#abort().

Specified by:

rollback in interface SailConnection

Throws:

SailException

commit2

public long commit2()
             throws SailException

Commit the write set.

Note: The semantics depend on the Options#STORE_CLASS. See ITripleStore#commit().

Returns:

The timestamp associated with the commit point. This will be 0L if the write set was empty such that nothing was committed.

Throws:

SailException

commit

public final void commit()
                  throws SailException

Commit the write set.

Note: The semantics depend on the Options#STORE_CLASS. See ITripleStore#commit().

Specified by:

commit in interface SailConnection

Throws:

SailException

isOpen

public final boolean isOpen()
                     throws SailException

Specified by:

isOpen in interface SailConnection

Throws:

SailException

close

public void close()
           throws SailException

Note: This does NOT implicitly rollback() the SailConnection. If you are doing error handling do NOT assume that close() will discard all writes.

Specified by:

close in interface SailConnection

Throws:

SailException

TODO:

Since there is a moderate amount of state (the buffers) it would be nice to not have to reallocate those. In order to reuse the buffer for writable connections we need to separate the concept of whether or not the connection is opened from its buffer state. Note that the scale-out triple store allows concurrent writers, so each writer needs its own buffers for that scenario.

finalize

protected void finalize()
                 throws Throwable

Invoke close, which will be harmless if we are already closed.

Overrides:

finalize in class Object

Throws:

Throwable

flush

public void flush()

Flush the statement buffers. The BigdataSail.BigdataSailConnection heavily buffers assertions and retractions. Either a flush() or a commit() is required before executing any operations directly against the backing AbstractTripleStore so that the buffered assertions or retractions will be written onto the KB and become visible to other methods. This is not a transaction issue -- just a buffer issue. The public methods on the BigdataSail.BigdataSailConnection all flush the buffers before performing any queries against the underlying AbstractTripleStore.

flushStatementBuffers

protected void flushStatementBuffers(boolean flushAssertBuffer,
                                     boolean flushRetractBuffer)

Flush pending assertions and/or retractions to the database using efficient batch operations. If BigdataSail.getTruthMaintenance() returns true this method will also handle truth maintenance.

Note: This MUST be invoked within any method that will read on the database to ensure that any pending writes have been flushed (otherwise the read operation will not be able to see the pending writes). However, methods that assert or retract statements MUST only flush the buffer on which they will NOT write. E.g., if you are going to retract statements, then first flush the assertions buffer and visa versa.

assertOpenConn

protected void assertOpenConn()
                       throws SailException

Throws:

SailException

assertWritableConn

protected void assertWritableConn()
                           throws SailException

Throws:

SailException

getStatements

public CloseableIteration<? extends Statement,SailException> getStatements(Resource s,
                                                                           URI p,
                                                                           Value o,
                                                                           Resource context)
                                                                    throws SailException

Throws:

SailException

getStatements

public CloseableIteration<? extends Statement,SailException> getStatements(Resource s,
                                                                           URI p,
                                                                           Value o,
                                                                           boolean includeInferred,
                                                                           Resource... contexts)
                                                                    throws SailException

Note: if the context is null, then you will see data from each context in a quad store, including anything in the BigdataSail.NULL_GRAPH.

Specified by:

getStatements in interface SailConnection

Throws:

SailException

computeClosure

public void computeClosure()
                    throws SailException

Computes the closure of the triple store for RDF(S)+ entailments.

This computes the closure of the database. This can be used if you do NOT enable truth maintenance and choose instead to load up all of your data first and then compute the closure of the database. Note that some rules may be computed by eager closure while others are computed at query time.

Note: If there are already entailments in the database AND you have retracted statements since the last time the closure was computed then you MUST delete all entailments from the database before re-computing the closure.

Note: This method does NOT commit the database. See ITripleStore#commit() and getTripleStore().

Throws:

SailException

See Also:

removeAllEntailments()

removeAllEntailments

public void removeAllEntailments()
                          throws SailException

Removes all "inferred" statements from the database and the proof chains (if any) associated with those inferences (does NOT commit the database).

Throws:

SailException

executeUpdate

public void executeUpdate(UpdateExpr updateExpr,
                          Dataset dataset,
                          BindingSet bindingSet,
                          boolean includeInferred)
                   throws SailException

Bigdata now uses an internal query model which differs significantly from the Sesame query model. Support is not provided for UpdateExpr evaluation. SPARQL UPDATE requests must be prepared and evaluated using a BigdataSailRepositoryConnection.

Specified by:

executeUpdate in interface SailConnection

Throws:

SailException - always.

See Also:

SPARQL 1.1 Update

evaluate

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

Bigdata now uses an internal query model which differs significantly from the Sesame query model. Support is no longer provided for TupleExpr evaluation. SPARQL queries must be prepared and evaluated using a BigdataSailRepositoryConnection.

Specified by:

evaluate in interface SailConnection

Throws:

SailException - always.

evaluate

public CloseableIteration<? extends BindingSet,QueryEvaluationException> evaluate(QueryRoot queryRoot,
                                                                                  Dataset dataset,
                                                                                  BindingSet bindings,
                                                                                  boolean includeInferred)
                                                                           throws SailException

Deprecated. Consider removing this method from our public API. It is no longer in any code path for the bigdata code base. Embedded applications requiring high level evaluation should use BigdataSailRepositoryConnection. It does not call through here, but goes directly to the ASTEvalHelper.

Evaluate a bigdata query model.

Parameters:

queryRoot - The query model.

dataset - The data set (optional).

bindings - The initial bindings.

includeInferred - true iff inferences will be considered when reading on access paths.

Returns:

The CloseableIteration from which the solutions may be drained.

Throws:

SailException

addChangeLog

public void addChangeLog(IChangeLog changeLog)

Set the change log on the SAIL connection. See IChangeLog and IChangeRecord.

Parameters:

changeLog - the change log