com.complexible.stardog.api

Interface Connection

All Superinterfaces:

AutoCloseable

All Known Subinterfaces:

BitesConnection, GraphQLConnection, ICVConnection, ReasoningConnection, SearchConnection, StardocsConnection

All Known Implementing Classes:

com.complexible.stardog.api.impl.AbstractConnection, AbstractICVConnection, AbstractReasoningConnection, com.complexible.stardog.api.impl.DelegatingConnection, EmbeddedGraphQLConnection, EmbeddedICVConnection, EmbeddedReasoningConnection, KernelDatabaseConnection

public interface Connection
extends AutoCloseable

Interface for a connection to a Stardog database. Connections should be obtained via a LoginConnectionConfiguration 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:

6.0

Author:

Michael Grove

See Also:

Adder, Remover, IO, LoginConnectionConfiguration, Namespaces

Method Summary

Modifier and Type	Method and Description
Adder	add() Create an Adder for adding statements to the database
AdminConnection	admin() Returns an instance of the AdminConnection class that can be used to perform administrative functions.
<T extends Connection> T	as(Class<T> theView) Return this connection viewed as a different type of connection.
BooleanQuery	ask(String theQuery) Create a SPARQL ask query against the database
BooleanQuery	ask(String theQuery, String theBase) Create a SPARQL ask query against the database
UUID	begin() Start a new transaction.
void	close() Close this connection.
CommitResult	commit() Commit the current transaction.
Map<String,Object>	currentStatus() Return the current status of the database
Exporter	export() Create an Exporter to export RDF from the database
com.stardog.model.DataModel	generateModel(com.stardog.model.DataModelFormat theInputFormat, Options theOptions) Generates n data model from the database.
Getter	get() Create a Getter for retrieving statements from the database
default <T> T	getOption(MetaProperty<T> theOption) Gets the value of the specified option for the current database.
String	getSchema() Returns the schema name that will be used if reasoning is enabled or null if reasoning is not enabled.
GraphQuery	graph(String theQuery) Create a SPARQL graph query against the database
GraphQuery	graph(String theQuery, String theBase) Create a SPARQL graph query against the database
com.complexible.stardog.query.GraphAliases	graphAliases() Get graph aliases for this database.
boolean	isOpen() Return whether or not this connection is open.
boolean	isReasoningEnabled() Return whether reasoning is enabled for this connection.
String	name() Return the name of the database this object is connected to
NamespacesInfo	namespaces()
PathQuery	paths(String theQuery) Create a path query against the database
PathQuery	paths(String theQuery, String theBase) Create a path query against the database
Remover	remove() Create a Remover for removing statements from the database
void	rollback() Rollback the current transaction.
SelectQuery	select(String theQuery) Create a SPARQL select query against the database
SelectQuery	select(String theQuery, String theBase) Create a SPARQL select query against the database
SelectPlanQuery	selectPlan(String theQuery) Create a plan query against the database
SelectPlanQuery	selectPlan(String theQuery, String theBase) Create a plan query against the database
long	size() Return size of the database.
Collection<TxInfo>	transactions() Returns an immutable collection of info objects for the open transactions in this database on the server-side.
UpdateQuery	update(String theQuery) Create a SPARQL update query against the database
UpdateQuery	update(String theQuery, String theBase) Create a SPARQL update query against 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

select

SelectQuery select(String theQuery)
            throws StardogException

Create a SPARQL select query against the database

Parameters:

theQuery - the query string

Throws:

StardogException - if there was an error while creating the query

select

SelectQuery select(String theQuery,
                   String theBase)
            throws StardogException

Create a SPARQL select query against the database

Parameters:

theQuery - the query string

theBase - the base URI to use when parsing the query

Throws:

StardogException - if there was an error while creating the query

selectPlan

SelectPlanQuery selectPlan(String theQuery)
                    throws StardogException

Create a plan query against the database

Parameters:

theQuery - the plan string

Throws:

StardogException - if there was an error while creating the query

selectPlan

SelectPlanQuery selectPlan(String theQuery,
                           String theBase)
                    throws StardogException

Create a plan query against the database

Parameters:

theQuery - the plan string

theBase - the base URI to use when parsing the query

Throws:

StardogException - if there was an error while creating the query

graph

GraphQuery graph(String theQuery)
          throws StardogException

Create a SPARQL graph query against the database

Parameters:

theQuery - the query string

Throws:

StardogException - if there was an error while creating the query

graph

GraphQuery graph(String theQuery,
                 String theBase)
          throws StardogException

Create a SPARQL graph query against the database

Parameters:

theQuery - the query string

theBase - the base URI to use when parsing the query

Throws:

StardogException - if there was an error while creating the query

paths

PathQuery paths(String theQuery)
         throws StardogException

Create a path query against the database

Parameters:

theQuery - the query string

Throws:

StardogException - if there was an error while creating the query

paths

PathQuery paths(String theQuery,
                String theBase)
         throws StardogException

Create a path query against the database

Parameters:

theQuery - the query string

theBase - the base URI to use when parsing the query

Throws:

StardogException - if there was an error while creating the query

ask

BooleanQuery ask(String theQuery)
          throws StardogException

Create a SPARQL ask query against the database

Parameters:

theQuery - the query string

Throws:

StardogException - if there was an error while creating the query

ask

BooleanQuery ask(String theQuery,
                 String theBase)
          throws StardogException

Create a SPARQL ask query against the database

Parameters:

theQuery - the query string

theBase - the base URI to use when parsing the query

Throws:

StardogException - if there was an error while creating the query

update

UpdateQuery update(String theQuery)
            throws StardogException

Create a SPARQL update query against the database

Parameters:

theQuery - the query string

Throws:

StardogException - if there was an error while creating the query

update

UpdateQuery update(String theQuery,
                   String theBase)
            throws StardogException

Create a SPARQL update query against the database

Parameters:

theQuery - the query string

theBase - the base URI to use when parsing the query

Throws:

StardogException - if there was an error while creating the query

begin

UUID begin()
    throws StardogException

Start a new transaction. This is the required step before making any updates through this connection.

Note that, the transaction on the server might not be started immediately when this function is called. The client connection may delay beginning the actual transaction on the server until a later time when a read or write operation is done.

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

CommitResult commit()
             throws StardogException

Commit the current transaction.

Returns:

the result of the commit showing number of triples added and removed

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. If a transaction is active when the Connection is closed, it is automatically rolled back.

Specified by:

close in interface AutoCloseable

Throws:

StardogException - if there was an error while closing

isOpen

boolean isOpen()
        throws IllegalStateException

Return whether or not this connection is open.

Returns:

true if it is open, false otherwise

Throws:

IllegalStateException - if there was an error with the connection

namespaces

NamespacesInfo namespaces()
                   throws StardogException

Throws:

StardogException - if there was an error with the connection

Since:

1.0.1

Implementation Notes:

The logged in user should have read access to database metadata for this function to return successfully.

transactions

Collection<TxInfo> transactions()
                         throws StardogException

Returns an immutable collection of info objects for the open transactions in this database on the server-side. The transactions open on the client-side but not yet sent to the server will not be included in the results even if the transaction is started by this connection.

The logged in user can see only the transactions he/she started. The superusers can see all open transactions.

Returns:

an immutable collection of info objects for the open transactions in this database

Throws:

StardogException - if there was an error with the connection

Since:

5.1

admin

AdminConnection admin()
               throws StardogException

Returns an instance of the AdminConnection 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 AdminConnection will be active unless the user AdminConnection.close() logs out} explicitly or closes this connection. The same AdminConnection will be returned by this function as long as it stays active.

Throws:

StardogException - if there was an error creating the AdminConnection instance

getOption

default <T> T getOption(MetaProperty<T> theOption)
                 throws StardogException

Gets the value of the specified option for the current database. Shortcut for AdminConnection.get(String, MetaProperty)

Type Parameters:

T - type of the option value

Parameters:

theOption - the option to get

Returns:

current value of the option in the database or null

Throws:

StardogException - if there was an error while getting the value

size

long size()
   throws StardogException

Return size of the database. Behavior of this call depends on whether the connection was created with ConnectionConfiguration.EXACT_SIZE parameter or not. By default it is not and then the result will be an approximation of the current number of statements in the database. Quality of that approximation is generally not guaranteed and it depends on past transactional history such as adding statements which already existed at that point or removing statements which did not. If ConnectionConfiguration.EXACT_SIZE is enabled for the connection, the result of this method will be equal to the result of a query which would count all statements in all named graphs of the database (in particular, it will also account for uncommitted changes made through this connection). Warning: this could be expensive for large databases which is the main reason why this is not the default behavior.

Returns:

the size

Throws:

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

export

Exporter export()
         throws StardogException

Create an Exporter to export RDF from the database

Returns:

an Exporter

Throws:

StardogException - if the Exporter could not be created.

generateModel

com.stardog.model.DataModel generateModel(com.stardog.model.DataModelFormat theInputFormat,
                                          Options theOptions)
                                   throws StardogException

Generates n data model from the database. The model can be generated from a variety of different input sources and the resulting model can be significantly different based on the input source used.

• OWL: The RDFS and OWL definitions in the database are used to generate the model. Requires reasoning to be enabled. A reasoning schema name can be specified in the reasoning connection. Every class in the schema becomes a Class and every property with a domain becomes a Property.
• SHACL: The SHACL constraints in the database are used to generate the model. Every shape with a targetClass becomes a Class and the property shapes defined on those shapes are turned into a Property.

Parameters:

theInputFormat -

theOptions -

Returns:

the data model

Throws:

StardogException - if the model could not be created.

isReasoningEnabled

boolean isReasoningEnabled()
                    throws StardogException

Return whether reasoning is enabled for this connection.

Returns:

the reasoning flag

Throws:

StardogException - if the reasoning flag could not be obtained

getSchema

String getSchema()

Returns the schema name that will be used if reasoning is enabled or null if reasoning is not enabled.

Returns:

the schema name that will be used if reasoning is enabled or null if reasoning is not enabled

currentStatus

Map<String,Object> currentStatus()
                          throws StardogException

Return the current status of the database

Returns:

the status

Throws:

StardogException - if the status information could not be retrieved

name

String name()

Return the name of the database this object is connected to

Returns:

the name of the database

graphAliases

com.complexible.stardog.query.GraphAliases graphAliases()

Get graph aliases for this database. Queries executed through this connection are only guaranteed to see graph alias changes if those are made through the GraphAliases object returned from this method. Uncommitted changes made through the same connection but directly in the data (e.g. using the Adder object) may not be visible.

Returns:

graph aliases