com.blazegraph.gremlin.embedded

Class BlazeGraphEmbedded

java.lang.Object

com.blazegraph.gremlin.structure.BlazeGraph

com.blazegraph.gremlin.embedded.BlazeGraphEmbedded

All Implemented Interfaces:

AutoCloseable, org.apache.tinkerpop.gremlin.structure.Graph, org.apache.tinkerpop.gremlin.structure.util.Host

Direct Known Subclasses:

BlazeGraphReadOnly

public class BlazeGraphEmbedded
extends BlazeGraph

An implementation of the tinkerpop3 API that uses an embedded SAIL repository instance (same JVM).

Currently BlazeGraphEmbedded is the only concrete implementation of the Blazegraph Tinkerpop3 API. BlazeGraphEmbedded is backed by an embedded (same JVM) instance of Blazegraph. This puts the enterprise features of Blazegraph (high-availability, scale-out, etc.) out of reach for the 1.0 version of the TP3 integration, since those features are accessed via Blazegraph's client/server API. A TP3 integration with the client/server version of Blazegraph is reserved for a future blazegraph-tinkerpop release.

Blazegraph's concurrency model is MVCC, which more or less lines up with Tinkerpop's Transaction model. When you open a BlazeGraphEmbedded instance, you are working with the unisolated (writer) view of the database. This view supports Tinkerpop Transactions, and reads are done against the unisolated connection, so uncommitted changes will be visible. A BlazeGraphEmbedded can be shared across multiple threads, but only one thread can have a Tinkerpop Transaction open at a time (other threads will be blocked until the transaction is closed). A TP3 Transaction is automatically opened on any read or write operation, and automatically closed on any commit or rollback operation. The Transaction can also be closed manually, which you will need to do after read operations to unblock other waiting threads.

BlazegraphGraphEmbedded's database operations are thus single-threaded, but Blazegraph/MVCC allows for many concurrent readers in parallel with both the single writer and other readers. This is possible by opening a read-only view that will read against the last commit point on the database. The read-only view can be be accessed in parallel to the writer without any of the restrictions described above. To get a read-only snapshot, use the following pattern:

 final BlazeGraphEmbedded unisolated = ...; 
 final BlazeGraphReadOnly readOnly = unisolated.readOnlyConnection(); 
 try { 
     // read operations against readOnly
 } finally { 
     readOnly.close(); 
 }
 

BlazeGraphReadOnly extends BlazeGraphEmbedded and thus offers all the same operations, except write operations will not be permitted (BlazeGraphReadOnly.tx() will throw an exception). You can open as many read-only views as you like, but we recommend you use a connection pool so as not to overtax system resources. Applications should be written with the one-writer many-readers paradigm front of mind.

Important: Make sure to close the read-only view as soon as you are done with it.

Author:

mikepersonick

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	BlazeGraphEmbedded.BlazeTransaction Tinkerpop3 Transaction object.

Nested classes/interfaces inherited from class com.blazegraph.gremlin.structure.BlazeGraph

BlazeGraph.Exceptions, BlazeGraph.GraphStreamer<E>, BlazeGraph.Match, BlazeGraph.Options, BlazeGraph.Transforms

Nested classes/interfaces inherited from interface org.apache.tinkerpop.gremlin.structure.Graph

org.apache.tinkerpop.gremlin.structure.Graph.Features, org.apache.tinkerpop.gremlin.structure.Graph.Hidden, org.apache.tinkerpop.gremlin.structure.Graph.OptIn, org.apache.tinkerpop.gremlin.structure.Graph.OptIns, org.apache.tinkerpop.gremlin.structure.Graph.OptOut, org.apache.tinkerpop.gremlin.structure.Graph.OptOuts, org.apache.tinkerpop.gremlin.structure.Graph.Variables

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	closed Close the unisolated connection if open and close the repository.
protected com.blazegraph.gremlin.embedded.BlazeGraphEmbedded.ChangeLogTransformer	listener Listen for change events from the SAIL (RDF), convert to PG data (BlazeGraphEdits), forward notifications to BlazeGraphListeners.
protected List<BlazeGraphListener>	listeners Graph listeners.
protected com.bigdata.rdf.sail.BigdataSailRepository	repo Embedded SAIL repository.

Fields inherited from class com.blazegraph.gremlin.structure.BlazeGraph

config, sparqlLog, sparqlLogMax, transforms

Fields inherited from interface org.apache.tinkerpop.gremlin.structure.Graph

GRAPH

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BlazeGraphEmbedded(com.bigdata.rdf.sail.BigdataSailRepository repo, org.apache.commons.configuration.Configuration config) Hidden constructor - use open(BigdataSailRepository, Configuration).

Method Summary

Modifier and Type	Method and Description
void	__tearDownUnitTest() DO NOT INVOKE FROM APPLICATION CODE - this method deletes the KB instance and destroys the backing database instance.
protected boolean	_ask(String queryStr, String extQueryId) Internal Sparql ask method.
protected Stream<org.openrdf.model.Statement>	_project(String queryStr, String extQueryId) Internal Sparql project method.
protected Stream<org.openrdf.query.BindingSet>	_select(String queryStr, String extQueryId) Internal Sparql select method.
protected void	_update(String queryStr, String extQueryId) Internal Sparql update method.
void	addListener(BlazeGraphListener listener) Add a BlazeGraphListener.
void	cancel(com.bigdata.rdf.sail.model.RunningQuery rQuery) Cancel a running query.
void	cancel(UUID queryId) Cancel a running query by internal id.
void	close() Close the graph.
void	commit() Pass through to tx().commit().
com.bigdata.rdf.sail.BigdataSailRepositoryConnection	cxn() Return the unisolated SAIL connection.
String	dumpStore() Dump all the statements in the store to a String.
void	flush() Pass through to tx().flush().
Collection<com.bigdata.rdf.sail.model.RunningQuery>	getRunningQueries() Return a list of all running queries.
long	historicalStatementCount() Count all the statements in the store including deleted statements.
protected static long	lastCommitTime(com.bigdata.rdf.sail.BigdataSailRepository repo) Take a quick peek at the last commit time on the supplied journal file.
static BlazeGraphEmbedded	open(com.bigdata.rdf.sail.BigdataSailRepository repo) Open a BlazeGraphEmbedded (unisolated) instance wrapping the provided SAIL repository with no additional configuration options.
static BlazeGraphEmbedded	open(com.bigdata.rdf.sail.BigdataSailRepository repo, org.apache.commons.configuration.Configuration config) Open a BlazeGraphEmbedded (unisolated) instance wrapping the provided SAIL repository and using the supplied configuration.
com.bigdata.rdf.model.BigdataValueFactory	rdfValueFactory() Return the RDF value factory.
BlazeGraphReadOnly	readOnlyConnection() Open a read-only view of the data at the last commit point.
void	removeListener(BlazeGraphListener listener) Remove a BlazeGraphListener.
void	rollback() Pass through to tx().rollbakc().
String	runningQueriesToString() Return a list of all running queries in string form.
long	statementCount() Count all the statements in the store.
BlazeGraphEmbedded.BlazeTransaction	tx() Return the BlazeGraphEmbedded.BlazeTransaction instance.

Methods inherited from class com.blazegraph.gremlin.structure.BlazeGraph

addEdge, addVertex, ask, ask, bulkLoad, bulkLoad, bulkLoad, compute, compute, configuration, edge, edgeCount, edges, features, graphAtomTransform, history, history, isBulkLoad, project, project, search, select, select, setBulkLoad, setMaxQueryTime, toString, update, update, valueFactory, variables, vertex, vertexCount, vertices

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.tinkerpop.gremlin.structure.Graph

addVertex, io, traversal, traversal

Field Detail

repo

protected final com.bigdata.rdf.sail.BigdataSailRepository repo

Embedded SAIL repository.

listeners

protected final List<BlazeGraphListener> listeners

Graph listeners.

See Also:

BlazeGraphListener

listener

protected final com.blazegraph.gremlin.embedded.BlazeGraphEmbedded.ChangeLogTransformer listener

Listen for change events from the SAIL (RDF), convert to PG data (BlazeGraphEdits), forward notifications to BlazeGraphListeners.

closed

protected volatile boolean closed

Close the unisolated connection if open and close the repository. Default close behavior is to roll back any uncommitted changes.

See Also:

Transaction.CLOSE_BEHAVIOR

Constructor Detail

BlazeGraphEmbedded

protected BlazeGraphEmbedded(com.bigdata.rdf.sail.BigdataSailRepository repo,
                             org.apache.commons.configuration.Configuration config)

Hidden constructor - use open(BigdataSailRepository, Configuration).

Parameters:

repo - an open and initialized repository

config - additional configuration

Method Detail

open

public static BlazeGraphEmbedded open(com.bigdata.rdf.sail.BigdataSailRepository repo)

Open a BlazeGraphEmbedded (unisolated) instance wrapping the provided SAIL repository with no additional configuration options.

Parameters:

repo - an open and initialized repository

Returns:

BlazeGraphEmbedded instance

open

public static BlazeGraphEmbedded open(com.bigdata.rdf.sail.BigdataSailRepository repo,
                                      org.apache.commons.configuration.Configuration config)

Open a BlazeGraphEmbedded (unisolated) instance wrapping the provided SAIL repository and using the supplied configuration.

Parameters:

config - additional configuration

Returns:

an open and initialized repository

lastCommitTime

protected static long lastCommitTime(com.bigdata.rdf.sail.BigdataSailRepository repo)

Take a quick peek at the last commit time on the supplied journal file. If it's ahead of our system time, then use that last commit time as a lower bound on blaze's transaction timestamps. Otherwise just use the system time as usual. Guards against clock skew (sharing journals between machines with different clock times).

readOnlyConnection

public BlazeGraphReadOnly readOnlyConnection()

Open a read-only view of the data at the last commit point. The read view can be used for read operations in parallel with the write view (this view) and other read views. Read views do not supports Tinkerpop Transactions or write operations.

These should be bounded in number by your application and always closed when done using them.

Returns:

a read-only view on the last commit point

tx

public BlazeGraphEmbedded.BlazeTransaction tx()

Return the BlazeGraphEmbedded.BlazeTransaction instance.

Specified by:

tx in interface org.apache.tinkerpop.gremlin.structure.Graph

Specified by:

tx in class BlazeGraph

See Also:

BlazeGraphEmbedded.BlazeTransaction

cxn

public com.bigdata.rdf.sail.BigdataSailRepositoryConnection cxn()

Return the unisolated SAIL connection. Automatically opens the Tinkerpop3 Transaction if not already open.

Specified by:

cxn in class BlazeGraph

commit

public void commit()

Pass through to tx().commit().

See Also:

AbstractTransaction.commit()

rollback

public void rollback()

Pass through to tx().rollbakc().

See Also:

AbstractTransaction.rollback()

flush

public void flush()

Pass through to tx().flush().

See Also:

BlazeGraphEmbedded.BlazeTransaction.flush()

close

public void close()

Description copied from class: BlazeGraph

Close the graph. Implementation-specific.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface org.apache.tinkerpop.gremlin.structure.Graph

Specified by:

close in class BlazeGraph

See Also:

close()

addListener

public void addListener(BlazeGraphListener listener)

Add a BlazeGraphListener.

Parameters:

listener - the listener

removeListener

public void removeListener(BlazeGraphListener listener)

Remove a BlazeGraphListener.

Parameters:

listener - the listener

rdfValueFactory

public com.bigdata.rdf.model.BigdataValueFactory rdfValueFactory()

Return the RDF value factory.

Specified by:

rdfValueFactory in class BlazeGraph

See Also:

BigdataValueFactory

_select

protected Stream<org.openrdf.query.BindingSet> _select(String queryStr,
                                                       String extQueryId)

Internal Sparql select method. Prepare a Sparql select query, turn Sesame iteration into a stream of binding sets using BlazeGraph.GraphStreamer. Callers MUST close this stream when finished. Logs the query at INFO and logs the optimized AST at TRACE.

Specified by:

_select in class BlazeGraph

_project

protected Stream<org.openrdf.model.Statement> _project(String queryStr,
                                                       String extQueryId)

Internal Sparql project method. Prepare a Sparql graph query, turn Sesame iteration into a stream of statements using BlazeGraph.GraphStreamer. Callers MUST close this stream when finished. Logs the query at INFO and logs the optimized AST at TRACE.

Specified by:

_project in class BlazeGraph

_ask

protected boolean _ask(String queryStr,
                       String extQueryId)

Internal Sparql ask method. Prepare a Sparql ask query and return result. Logs the query at INFO.

Specified by:

_ask in class BlazeGraph

_update

protected void _update(String queryStr,
                       String extQueryId)

Internal Sparql update method. Prepare a Sparql Update and execute. Logs the query at INFO.

Specified by:

_update in class BlazeGraph

dumpStore

public String dumpStore()
                 throws Exception

Dump all the statements in the store to a String. Bypasses the SAIL, so you must call flush() to get an accurate picture.

Throws:

Exception

statementCount

public long statementCount()
                    throws Exception

Count all the statements in the store. Bypasses the SAIL, so you must call flush() to get an accurate picture.

Throws:

Exception

historicalStatementCount

public long historicalStatementCount()
                              throws Exception

Count all the statements in the store including deleted statements. Bypasses the SAIL, so you must call flush() to get an accurate picture.

Throws:

Exception

runningQueriesToString

public String runningQueriesToString()

Return a list of all running queries in string form.

getRunningQueries

public Collection<com.bigdata.rdf.sail.model.RunningQuery> getRunningQueries()

Return a list of all running queries.

Specified by:

getRunningQueries in class BlazeGraph

cancel

public void cancel(UUID queryId)

Cancel a running query by internal id.

Specified by:

cancel in class BlazeGraph

cancel

public void cancel(com.bigdata.rdf.sail.model.RunningQuery rQuery)

Cancel a running query.

Specified by:

cancel in class BlazeGraph

__tearDownUnitTest

public void __tearDownUnitTest()

DO NOT INVOKE FROM APPLICATION CODE - this method deletes the KB instance and destroys the backing database instance. It is used to help tear down unit tests.