com.bigdata.rdf.sail
Class BigdataSail

java.lang.Object
  org.openrdf.sail.helpers.SailBase
      com.bigdata.rdf.sail.BigdataSail

All Implemented Interfaces:

org.openrdf.sail.Sail

public class BigdataSail
extends org.openrdf.sail.helpers.SailBase
implements org.openrdf.sail.Sail

Sesame 2.x integration.

Read-write operations use getConnection() to obtain a mutable view. getConnection() uses a Semaphore to enforce the constraint that there is only one writable BigdataSail.BigdataSailConnection at a time. SAIL transactions will be serialized (at most one will run at a time).

Concurrent readers are possible, and can be very efficient. However, readers MUST use a database commit point corresponding to a desired state of the store, e.g., after loading some data set and (optionally) after computing the closure of that data set. Use getDatabase() . AbstractResource.getIndexManager() . IIndexStore.getLastCommitTime() to obtain the commit time and then getReadHistoricalView(long) to obtain a read-only view as of that commit time. In you are loading data incrementally, then you can use asReadCommittedView() instead.

The BigdataSail may be configured as as to provide a triple store with statement-level provenance using statement identifiers. A statement identifier is unique identifier for a triple in the database. Statement identifiers may be used to make statements about statements without using RDF style reification. The statement identifier is bound to the context position during high-level query so you can use high-level query (SPARQL) to obtain statements about statements. See AbstractTripleStore.Options#STATEMENT_IDENTIFIERS.

Quads may be enabled using AbstractTripleStore.Options#QUADS. However, note that BigdataSail.Options.TRUTH_MAINTENANCE is not supported for AbstractTripleStore.Options#QUADS at this time. This may change in the future once we decide how to handle eager materialization of entailments with multiple named graphs. The basic problem is that:

 merge(closure(graphA), closure(graphB))
 

IS NOT EQUALS TO

 closure(merge(graphA, graphB))
 

There are two ways to handle this. One is to compute all inferences at query time, in which case we are not doing eager materialization and therefore we are not using Truth Maintenance. The other is to punt and use the merge of their individual closures.

Version:

$Id: BigdataSail.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

TODO:

Is there anything to be done with SailBase.setDataDir(java.io.File)? With SailBase.getDataDir()?, write custom initialization class (Instead of the generic setParameter method, most Sail implementation now have specific methods for each parameter. This is much more convenient when creating Sail instances programmatically. You are free to add whatever initialization method to your Sail class.)

Nested Class Summary

class	BigdataSail.BigdataSailConnection Inner class implements the SailConnection.
static interface	BigdataSail.Options Additional parameters understood by the Sesame 2.x SAIL implementation.

Field Summary

protected AbstractTripleStore	database
protected static org.apache.log4j.Logger	log Logger.
protected static long	NULL The equivalent of a null identifier for an internal RDF Value.
static URI	NULL_GRAPH Sesame has the notion of a "null" graph which we use for the quad store mode.
protected Properties	properties

Fields inherited from class org.openrdf.sail.helpers.SailBase

connectionTimeOut, DEFAULT_CONNECTION_TIMEOUT, logger

Constructor Summary

BigdataSail()
Create or re-open a database instance configured using defaults.

BigdataSail(AbstractTripleStore database)
Core ctor.

BigdataSail(Properties properties)
Create or open a database instance configured using the specified properties.

Method Summary

BigdataSail.BigdataSailConnection	asReadCommittedView() A factory returning the singleton read-committed view of the database.
protected void	assertOpen()
protected void	finalize() Invokes shutDown().
BigdataSail.BigdataSailConnection	getConnection() Strengthens the return type.
protected org.openrdf.sail.NotifyingSailConnection	getConnectionInternal() Return a read-write SailConnection.
AbstractTripleStore	getDatabase() The implementation object.
InferenceEngine	getInferenceEngine() The inference engine if the SAIL is using one.
BigdataSail.BigdataSailConnection	getQueryConnection() Return a query connection based on a the last commit point.
BigdataSail.BigdataSailConnection	getReadHistoricalView(long commitTime) Obtain a read-historical view that reads from the specified commit point.
boolean	getTruthMaintenance() When true, the RDFS closure will be maintained by the SAIL implementation (but not by methods that go around the SAIL).
ValueFactory	getValueFactory() A BigdataValueFactory
void	initialize()
boolean	isOpen() Return true if the BigdataSail has been initialize()d and has not been shutDown().
boolean	isQuads() Return true if the SAIL is using a "quads" mode database.
boolean	isWritable()
void	shutDown()
protected void	shutDownInternal() If the backing database was created/opened by the BigdataSail then it is closed.

Methods inherited from class org.openrdf.sail.helpers.SailBase

connectionClosed, debugEnabled, getDataDir, setDataDir

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.openrdf.sail.Sail

getDataDir, setDataDir

Field Detail

log

protected static final org.apache.log4j.Logger log

Logger.

NULL_GRAPH

public static final transient URI NULL_GRAPH

Sesame has the notion of a "null" graph which we use for the quad store mode. Any time you insert a statement into a quad store and the context position is not specified, it is actually inserted into this "null" graph. If SPARQL DATASET is not specified, then all contexts are queried and you will see statements from the "null" graph as well as from any other context. BigdataSail.BigdataSailConnection.getStatements(Resource, URI, Value, boolean, Resource...) will return statements from the "null" graph if the context is either unbound or is an array whose sole element is null.

See Also:

BigdataSail.BigdataSailConnection.addStatement(Resource, URI, Value, Resource...), BigdataSail.BigdataSailConnection.getStatements(Resource, URI, Value, boolean, Resource...)

NULL

protected static final long NULL

The equivalent of a null identifier for an internal RDF Value.

See Also:

Constant Field Values

database

protected final AbstractTripleStore database

properties

protected final Properties properties

Constructor Detail

BigdataSail

public BigdataSail()

Create or re-open a database instance configured using defaults.

BigdataSail

public BigdataSail(Properties properties)

Create or open a database instance configured using the specified properties.

See Also:

BigdataSail.Options

BigdataSail

public BigdataSail(AbstractTripleStore database)

Core ctor. You must use this variant for a scale-out triple store.

To create a BigdataSail backed by an IBigdataFederation use the ScaleOutTripleStore ctor and then AbstractTripleStore.create() the triple store if it does not exist.

Parameters:

database - An existing AbstractTripleStore.

Method Detail

getInferenceEngine

public InferenceEngine getInferenceEngine()

The inference engine if the SAIL is using one.

Note: Requesting this object will cause the axioms to be written onto the database if they are not already present. If this is a read-only view and the mutable view does not already have the axioms defined then this will cause an exception to be thrown since the indices are not writable by the read-only view.

isQuads

public boolean isQuads()

Return true if the SAIL is using a "quads" mode database.

See Also:

AbstractTripleStore.Options#QUADS

getTruthMaintenance

public boolean getTruthMaintenance()

When true, the RDFS closure will be maintained by the SAIL implementation (but not by methods that go around the SAIL).

getDatabase

public AbstractTripleStore getDatabase()

The implementation object.

assertOpen

protected void assertOpen()

Throws:

IllegalStateException - if the BigdataSail has not been initialize()d or has been shutDown().

isOpen

public boolean isOpen()

Return true if the BigdataSail has been initialize()d and has not been shutDown().

initialize

public void initialize()
                throws org.openrdf.sail.SailException

Specified by:

initialize in interface org.openrdf.sail.Sail

Throws:

IllegalStateException - if the sail is already open.

org.openrdf.sail.SailException

finalize

protected void finalize()
                 throws Throwable

Invokes shutDown().

Overrides:

finalize in class Object

Throws:

Throwable

shutDown

public void shutDown()
              throws org.openrdf.sail.SailException

Specified by:

shutDown in interface org.openrdf.sail.Sail

Overrides:

shutDown in class org.openrdf.sail.helpers.SailBase

Throws:

org.openrdf.sail.SailException

shutDownInternal

protected void shutDownInternal()
                         throws org.openrdf.sail.SailException

If the backing database was created/opened by the BigdataSail then it is closed. Otherwise this is a NOP.

Specified by:

shutDownInternal in class org.openrdf.sail.helpers.SailBase

Throws:

org.openrdf.sail.SailException

asReadCommittedView

public BigdataSail.BigdataSailConnection asReadCommittedView()

A factory returning the singleton read-committed view of the database. This view is safe for concurrent query operations.

Note: The returned object is thread-safe and the same instance is used by concurrent readers. Therefore SailConnection.close() is a NOP for the returned object and SailConnection.isOpen() will always return true for the returned object. A weak reference is maintained to the read-committed view and the view will be reclaimed by the garbage collector once the application no longer holds a hard reference to the returned object.

getReadHistoricalView

public BigdataSail.BigdataSailConnection getReadHistoricalView(long commitTime)

Obtain a read-historical view that reads from the specified commit point. This view is safe for concurrent readers and will not update if there are concurrent writes.

Parameters:

commitTime - The commit point.

Returns:

The view.

TODO:

both asReadCommittedView() and getReadHistoricalView(long) do not register the connection with the SailBase which leads to the following message.

      SailBase.connectionClosed(SailBase.java:204): tried to remove unknown connection object from store.
 

This message (probably) can be ignored since these are read-only views. However, since the SailBase wants to "close" the connections, the read-committed view should not be a singleton - it needs to be a distinct BigdataSail.BigdataSailConnection instance. Also, both views need to get registered for this message to go away.

One way to handle this is to obtain a BigdataSail subclass that operates as a factory for those views.

getValueFactory

public final ValueFactory getValueFactory()

A BigdataValueFactory

Specified by:

getValueFactory in interface org.openrdf.sail.Sail

isWritable

public final boolean isWritable()
                         throws org.openrdf.sail.SailException

Specified by:

isWritable in interface org.openrdf.sail.Sail

Throws:

org.openrdf.sail.SailException

getConnectionInternal

protected org.openrdf.sail.NotifyingSailConnection getConnectionInternal()
                                                                  throws org.openrdf.sail.SailException

Return a read-write SailConnection. There is only one writable connection and this method will block until the connection is available.

Specified by:

getConnectionInternal in class org.openrdf.sail.helpers.SailBase

Throws:

org.openrdf.sail.SailException

See Also:

for a read-only connection.

TODO:

many of the stores can support concurrent writers, but there is a requirement to serialize writers when truth maintenance is enabled.

getConnection

public BigdataSail.BigdataSailConnection getConnection()
                                                throws org.openrdf.sail.SailException

Strengthens the return type.

Specified by:

getConnection in interface org.openrdf.sail.Sail

Overrides:

getConnection in class org.openrdf.sail.helpers.SailBase

Throws:

org.openrdf.sail.SailException

getQueryConnection

public BigdataSail.BigdataSailConnection getQueryConnection()
                                                     throws org.openrdf.sail.SailException

Return a query connection based on a the last commit point.

Throws:

org.openrdf.sail.SailException