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:
  - `Adder`
  - `Remover`
  - `IO`
  - `LoginConnectionConfiguration`
  - `Namespaces`

- ## Method Summary

  Modifier and Type
  Method
  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 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