Package com.complexible.stardog.api

Interface Connection

All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
GraphQLConnection, ICVConnection, ReasoningConnection, SearchConnection
All Known Implementing Classes:
AbstractICVConnection, AbstractReasoningConnection, com.complexible.stardog.api.impl.DelegatingConnection
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:

  • Method Details

    • 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