com.clarkparsia.stardog.api
Interface Connection

All Known Subinterfaces:

ICVConnection, ReasoningConnection, SearchConnection

public interface Connection

Interface for a connection to a Stardog database. Connections should be obtained via a ConnectionConfiguration which is used to build the appropriate connection string to the database.

Connection objects are not meant to be shared between threads and simple synchronization on the object itself is usually insufficient due to the possible use of ancillary objects such as Adder or IO which can change the state of the Connection, possibly outside the bounds of the synchronization.

However, concurrent reads from different threads is safe when there is no open transaction.

Since:

0.3

Version:

1.2

Author:

Michael Grove

See Also:

Adder, Remover, IO, ConnectionConfiguration, Namespaces

Method Summary

Adder	add() Create an Adder for adding statements to the database
<T extends Connection> T	as(Class<T> theView) Return this connection viewed as a different type of connection.
void	begin() Start a new transaction
void	close() Close this connection
void	commit() Commit the current transaction.
Getter	get() Create a Getter for retrieving statements from the database
boolean	isAutoCommit() Deprecated. will be removed in the next major version of Stardog (1.3)
boolean	isOpen() Return whether or not this connection is open.
StardogDBMS	loginDBMS() Returns an instance of the StardogDBMS class that can be used to perform administrative functions.
Namespaces	namespaces() Returns a snapshot of namespaces stored in this database.
Query	query(String theQuery) Create a SPARQL query against the database
Query	query(String theQuery, String theBaseURI) Create a SPARQL query against the database
Remover	remove() Create a Remover for removing statements from the database
void	rollback() Rollback the current transaction.
void	setAutoCommit(boolean theAutoCommit) Deprecated. will be removed in the next major version of Stardog (1.3)
long	size() Return the size of the database.

Method Detail

as

<T extends Connection> T as(Class<T> theView)
                        throws StardogException

Return this connection viewed as a different type of connection.

Type Parameters:

T - the connection view to return

Parameters:

theView - the type of connection to view this object as

Returns:

the new view of the connection.

Throws:

StardogException - if the connection cannot be viewed as the provided type. This could be from the parent connection having been closed or it does not support the provided view.

add

Adder add()
          throws StardogException

Create an Adder for adding statements to the database

Returns:

an adder object

Throws:

StardogException - if there is an error obtaining the adder

remove

Remover remove()
               throws StardogException

Create a Remover for removing statements from the database

Returns:

a remover object

Throws:

StardogException - if there is an error obtaining the remover

get

Getter get()
           throws StardogException

Create a Getter for retrieving statements from the database

Returns:

a Getter object

Throws:

StardogException - if there is an error obtaining the getter

query

Query query(String theQuery)
            throws StardogException

Create a SPARQL query against the database

Parameters:

theQuery - the query string

Returns:

the query

Throws:

StardogException - if there was an error while creating the query

query

Query query(String theQuery,
            String theBaseURI)
            throws StardogException

Create a SPARQL query against the database

Parameters:

theQuery - the query string

theBaseURI - the base URI to use when parsing the query

Returns:

the query

Throws:

StardogException - if there was an error while creating the query

begin

void begin()
           throws StardogException

Start a new transaction

Throws:

StardogException - if there was an error while creating the transaction or if there is already an active transaction for this connection.

rollback

void rollback()
              throws StardogException

Rollback the current transaction.

Throws:

StardogException - if there was an error while rolling back the transaction or if a transaction is not active.

commit

void commit()
            throws StardogException

Commit the current transaction.

Throws:

StardogException - the transaction failed to commit. In this case, it is automatically rolled back and the error merely indicates the cause, no additional cleanup action is required.

close

void close()
           throws StardogException

Close this connection

Throws:

StardogException - if there was an error while closing

isOpen

boolean isOpen()
               throws StardogException

Return whether or not this connection is open.

Returns:

true if it is open, false otherwise

Throws:

StardogException - if there was an error with the connection

isAutoCommit

@Deprecated
boolean isAutoCommit()
                     throws StardogException

Deprecated. will be removed in the next major version of Stardog (1.3)

Return whether or not the connection is in autoCommit mode. The default is false.

Returns:

true if its in autocommit mode, false otherwise.

Throws:

StardogException - if there was an error with the connection

setAutoCommit

@Deprecated
void setAutoCommit(boolean theAutoCommit)
                   throws StardogException

Deprecated. will be removed in the next major version of Stardog (1.3)

Set whether or not the connection is in auto commit mode.

Parameters:

theAutoCommit - true to be in auto commit mode, false otherwise

Throws:

StardogException - if there was an error with the connection

namespaces

Namespaces namespaces()
                      throws StardogException

Returns a snapshot of namespaces stored in this database. The logged in user should have read access to database metadata for this function to return succesfully. If the logged in user also has write access to database metadata, returned namespaces can be modified through add and remove functions.

Changes done on the returned Namespaces instance will be applied to database metadata immediately. However, since this function returns a snapshot of stored namespaces and applies changes to the local copy before applying them to the database metadata, concurrent updates of namespaces might result in changes performed by one connection to be overridden by another connection.

A new snapshot is retrieved every time this function is called which will take into account any changes that have occurred before this call.

Throws:

StardogException - if there was an error with the connection

Since:

1.0.1

loginDBMS

StardogDBMS loginDBMS()
                      throws StardogException

Returns an instance of the StardogDBMS class that can be used to perform administrative functions. The server URL and the credentials used for the current connection will be used to login to the server. The StardogDBMS will be active unless the user logs out explicitly or closes this connection. The same StardogDBMS will be returned by this function as long as it stays active.

Throws:

StardogException - if there was an error creating the StardogDBMS instance

size

long size()
          throws StardogException

Return the size of the database.

Returns:

the size

Throws:

StardogException - if there is an error returning the size of the db.