Package org.eclipse.rdf4j.sail

## Interface SailConnection

- All Superinterfaces:
    `AutoCloseable`
  All Known Subinterfaces:
    `InferencerConnection`, `NotifyingSailConnection`
  All Known Implementing Classes:
    `AbstractForwardChainingInferencerConnection`, `AbstractNotifyingSailConnection`, `AbstractSailConnection`, `DedupingInferencerConnection`, `ElasticsearchStoreConnection`, `ExtensibleStoreConnection`, `FedXConnection`, `InferencerConnectionWrapper`, `LimitedSizeNativeStoreConnection`, `LuceneSailConnection`, `MemoryStoreConnection`, `NativeStoreConnection`, `NotifyingSailConnectionBase`, `NotifyingSailConnectionWrapper`, `SailConnectionWrapper`, `SailSourceConnection`, `SchemaCachingRDFSInferencerConnection`, `ShaclSailConnection`, `VerySimpleRdfsBackwardsChainingConnection`

      public interface SailConnection
      extends AutoCloseable

  A connection to an RDF Sail object. A SailConnection is active from the moment it is created until it is closed. Care should be taken to properly close SailConnections as they might block concurrent queries and/or updates on the Sail while active, depending on the Sail-implementation that is being used.
  Author:
    jeen, Arjohn Kampman

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addStatement​(Resource subj, IRI pred, Value obj, Resource... contexts)` | Adds a statement to the store.
    `void` | `addStatement​(UpdateContext op, Resource subj, IRI pred, Value obj, Resource... contexts)` | Adds a statement to the store.
    `void` | `begin()` | Begins a transaction requiring `commit()` or `rollback()` to be called to close the transaction.
    `void` | `begin​(IsolationLevel level)` | Begins a transaction with the specified `IsolationLevel` level, requiring `commit()` or `rollback()` to be called to close the transaction.
    `void` | `clear​(Resource... contexts)` | Removes all statements from the specified/all contexts.
    `void` | `clearNamespaces()` | Removes all namespace declarations from the repository.
    `void` | `close()` | Closes the connection.
    `void` | `commit()` | Commits any updates that have been performed since the last time `commit()` or `rollback()` was called.
    `void` | `endUpdate​(UpdateContext op)` | Indicates that the given `op` will not be used in any call again.
    `CloseableIteration<? extends BindingSet,​QueryEvaluationException>` | `evaluate​(TupleExpr tupleExpr, Dataset dataset, BindingSet bindings, boolean includeInferred)` | Evaluates the supplied TupleExpr on the data contained in this Sail object, using the (optional) dataset and supplied bindings as input parameters.
    `default Explanation` | `explain​(Explanation.Level level, TupleExpr tupleExpr, Dataset dataset, BindingSet bindings, boolean includeInferred, int timeoutSeconds)` | Explain how the TupleExpr will be (or has been) executed/evaluated by returning a TupleExpr (which may or may not be the provided TupleExpr) that has gone through zero or more of the stages prior to and also including execution as specified by the provided level.
    `void` | `flush()` | Flushes any pending updates and notify changes to listeners as appropriate.
    `CloseableIteration<? extends Resource,​SailException>` | `getContextIDs()` | Returns the set of all unique context identifiers that are used to store statements.
    `String` | `getNamespace​(String prefix)` | Gets the namespace that is associated with the specified prefix, if any.
    `CloseableIteration<? extends Namespace,​SailException>` | `getNamespaces()` | Gets the namespaces relevant to the data contained in this Sail object.
    `CloseableIteration<? extends Statement,​SailException>` | `getStatements​(Resource subj, IRI pred, Value obj, boolean includeInferred, Resource... contexts)` | Gets all statements from the specified contexts that have a specific subject, predicate and/or object.
    `default boolean` | `hasStatement​(Resource subj, IRI pred, Value obj, boolean includeInferred, Resource... contexts)` | Determines if the store contains any statements from the specified contexts that have a specific subject, predicate and/or object.
    `boolean` | `isActive()` | Indicates if a transaction is currently active on the connection.
    `boolean` | `isOpen()` | Checks whether this SailConnection is open.
    `boolean` | `pendingRemovals()` | Deprecated.
    `void` | `prepare()` | Checks for an error state in the active transaction that would force the transaction to be rolled back.
    `default Optional<TupleExpr>` | `prepareQuery​(QueryLanguage ql, Query.QueryType type, String query, String baseURI)` | Allows the SailConnection to bypass the standard query parser and provide its own internal `TupleExpr` implementation.
    `void` | `removeNamespace​(String prefix)` | Removes a namespace declaration by removing the association between a prefix and a namespace name.
    `void` | `removeStatement​(UpdateContext op, Resource subj, IRI pred, Value obj, Resource... contexts)` | Removes all statements matching the specified subject, predicate and object from the repository.
    `void` | `removeStatements​(Resource subj, IRI pred, Value obj, Resource... contexts)` | Removes all statements matching the specified subject, predicate and object from the repository.
    `void` | `rollback()` | Rolls back the transaction, discarding any uncommitted changes that have been made in this SailConnection.
    `void` | `setNamespace​(String prefix, String name)` | Sets the prefix for a namespace.
    `default void` | `setTransactionSettings​(TransactionSetting... settings)` | Pass any transaction-specific settings to the SailConnection.
    `long` | `size​(Resource... contexts)` | Returns the number of (explicit) statements in the store, or in specific contexts.
    `void` | `startUpdate​(UpdateContext op)` | Signals the start of an update operation.

- - ### Method Detail

    - #### isOpen

          boolean isOpen()
                  throws SailException

      Checks whether this SailConnection is open. A SailConnection is open from the moment it is created until it is closed.
      Throws:
        `SailException`
      See Also:
        `close()`

    - #### close

          void close()
              throws SailException

      Closes the connection. Any updates that haven't been committed yet will be rolled back. The connection can no longer be used once it is closed.
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `SailException`

    - #### prepareQuery

          default Optional<TupleExpr> prepareQuery​(QueryLanguage ql,
                                                   Query.QueryType type,
                                                   String query,
                                                   String baseURI)

      Allows the SailConnection to bypass the standard query parser and provide its own internal `TupleExpr` implementation. By default this method returns an empty result, signaling that it will rely on the RDF4J query parser.
      Parameters:
        `ql` - the query language.
        `type` - indicates if the supplied query is a graph, tuple, or boolean query
        `query` - the unparsed query string
        `baseURI` - the provided base URI. May be null or empty.
      Returns:
        an optional TupleExpr that represents a sail-specific version of the query, which `evaluate(org.eclipse.rdf4j.query.algebra.TupleExpr, org.eclipse.rdf4j.query.Dataset, org.eclipse.rdf4j.query.BindingSet, boolean)` can process. Returns `Optional.empty()` if the Sail does not provide its own query processing.
      Since:
        3.2.0

    - #### evaluate

          CloseableIteration<? extends BindingSet,​QueryEvaluationException> evaluate​(TupleExpr tupleExpr,
                                                                                           Dataset dataset,
                                                                                           BindingSet bindings,
                                                                                           boolean includeInferred)
                                                                                    throws SailException

      Evaluates the supplied TupleExpr on the data contained in this Sail object, using the (optional) dataset and supplied bindings as input parameters.
      Parameters:
        `tupleExpr` - The tuple expression to evaluate.
        `dataset` - The dataset to use for evaluating the query, null to use the Sail's default dataset.
        `bindings` - A set of input parameters for the query evaluation. The keys reference variable names that should be bound to the value they map to.
        `includeInferred` - Indicates whether inferred triples are to be considered in the query result. If false, no inferred statements are returned; if true, inferred statements are returned if available
      Returns:
        The TupleQueryResult.
      Throws:
        `SailException` - If the Sail object encountered an error or unexpected situation internally.
        `IllegalStateException` - If the connection has been closed.

    - #### getContextIDs

          CloseableIteration<? extends Resource,​SailException> getContextIDs()
                                                                            throws SailException

      Returns the set of all unique context identifiers that are used to store statements.
      Returns:
        An iterator over the context identifiers, should not contain any duplicates.
      Throws:
        `IllegalStateException` - If the connection has been closed.
        `SailException`

    - #### getStatements

          CloseableIteration<? extends Statement,​SailException> getStatements​(Resource subj,
                                                                                    IRI pred,
                                                                                    Value obj,
                                                                                    boolean includeInferred,
                                                                                    Resource... contexts)
                                                                             throws SailException

      Gets all statements from the specified contexts that have a specific subject, predicate and/or object. All three parameters may be null to indicate wildcards. The includeInferred parameter can be used to control which statements are fetched: all statements or only the statements that have been added explicitly.
      Parameters:
        `subj` - A Resource specifying the subject, or null for a wildcard.
        `pred` - A URI specifying the predicate, or null for a wildcard.
        `obj` - A Value specifying the object, or null for a wildcard.
        `includeInferred` - if false, no inferred statements are returned; if true, inferred statements are returned if available
        `contexts` - The context(s) to get the data from. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.
      Returns:
        The statements matching the specified pattern.
      Throws:
        `SailException` - If the Sail object encountered an error or unexpected situation internally.
        `IllegalStateException` - If the connection has been closed.

    - #### hasStatement

          default boolean hasStatement​(Resource subj,
                                       IRI pred,
                                       Value obj,
                                       boolean includeInferred,
                                       Resource... contexts)
                                throws SailException

      Determines if the store contains any statements from the specified contexts that have a specific subject, predicate and/or object. All three parameters may be null to indicate wildcards. The includeInferred parameter can be used to control which statements are checked: all statements or only the statements that have been added explicitly.
      Parameters:
        `subj` - A Resource specifying the subject, or null for a wildcard.
        `pred` - An IRI specifying the predicate, or null for a wildcard.
        `obj` - A Value specifying the object, or null for a wildcard.
        `includeInferred` - if false, no inferred statements are returned; if true, inferred statements are returned if available
        `contexts` - The context(s) to get the data from. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.
      Returns:
        `true` iff the store contains any statements matching the supplied criteria, `false` otherwise.
      Throws:
        `SailException` - If the Sail object encountered an error or unexpected situation internally.
        `IllegalStateException` - If the connection has been closed.

    - #### size

          long size​(Resource... contexts)
             throws SailException

      Returns the number of (explicit) statements in the store, or in specific contexts.
      Parameters:
        `contexts` - The context(s) to determine the size of. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.
      Returns:
        The number of explicit statements in this store, or in the specified context(s).
      Throws:
        `IllegalStateException` - If the connection has been closed.
        `SailException`

    - #### begin

          void begin()
              throws SailException

      Begins a transaction requiring `commit()` or `rollback()` to be called to close the transaction. The transaction will use the default `IsolationLevel` level for the SAIL, as returned by `Sail.getDefaultIsolationLevel()`.
      Throws:
        `SailException` - If the connection could not start a transaction or if a transaction is already active on this connection.

    - #### begin

          void begin​(IsolationLevel level)
              throws UnknownSailTransactionStateException,
                     SailException

      Begins a transaction with the specified `IsolationLevel` level, requiring `commit()` or `rollback()` to be called to close the transaction.
      Parameters:
        `level` - the transaction isolation level on which this transaction operates.
      Throws:
        `UnknownSailTransactionStateException` - If the IsolationLevel is not supported by this implementation
        `SailException` - If the connection could not start a transaction, if the supplied transaction isolation level is not supported, or if a transaction is already active on this connection.

    - #### setTransactionSettings

          default void setTransactionSettings​(TransactionSetting... settings)

      Pass any transaction-specific settings to the SailConnection. This method needs to be called before the transaction is `started` .

      Sail implementations can override this method to receive the transaction settings (to inspect and/or pass them along to any wrapped sail objects). Remember to call `super.setTransactionSettings(settings)` if you override this method.

      Parameters:
        `settings` - the transaction settings on which the next transaction operates. It may or may not contain the isolation level.
      Since:
        3.3.0

    - #### flush

          void flush()
              throws SailException

      Flushes any pending updates and notify changes to listeners as appropriate. This is an optional call; calling or not calling this method should have no effect on the outcome of other calls. This method exists to give the caller more control over the efficiency when calling `prepare()`. This method may be called multiple times within the same transaction.
      Throws:
        `SailException` - If the updates could not be processed, for example because no transaction is active.
        `IllegalStateException` - If the connection has been closed.

    - #### prepare

          void prepare()
                throws SailException

      Checks for an error state in the active transaction that would force the transaction to be rolled back. This is an optional call; calling or not calling this method should have no effect on the outcome of `commit()` or `rollback()`. A call to this method must be followed by (in the same thread) with a call to `prepare()` , `commit()`, `rollback()`, or `close()` . This method may be called multiple times within the same transaction by the same thread. If this method returns normally, the caller can reasonably expect that a subsequent call to `commit()` will also return normally. If this method returns with an exception the caller should treat the exception as if it came from a call to `commit()`.
      Throws:
        `UnknownSailTransactionStateException` - If the transaction state can not be determined (this can happen for instance when communication between client and server fails or times-out). It does not indicate a problem with the integrity of the store.
        `SailException` - If there is an active transaction and it cannot be committed.
        `IllegalStateException` - If the connection has been closed or prepare was already called by another thread.

    - #### commit

          void commit()
               throws SailException

      Commits any updates that have been performed since the last time `commit()` or `rollback()` was called.
      Throws:
        `UnknownSailTransactionStateException` - If the transaction state can not be determined (this can happen for instance when communication between client and server fails or times-out). It does not indicate a problem with the integrity of the store.
        `SailException` - If the SailConnection could not be committed.
        `IllegalStateException` - If the connection has been closed.

    - #### rollback

          void rollback()
                 throws SailException

      Rolls back the transaction, discarding any uncommitted changes that have been made in this SailConnection.
      Throws:
        `UnknownSailTransactionStateException` - If the transaction state can not be determined (this can happen for instance when communication between client and server fails or times-out). It does not indicate a problem with the integrity of the store.
        `SailException` - If the SailConnection could not be rolled back.
        `IllegalStateException` - If the connection has been closed.

    - #### isActive

          boolean isActive()
                    throws UnknownSailTransactionStateException

      Indicates if a transaction is currently active on the connection. A transaction is active if `begin()` has been called, and becomes inactive after `commit()` or `rollback()` has been called.
      Returns:
        `true` iff a transaction is active, `false` iff no transaction is active.
      Throws:
        `UnknownSailTransactionStateException` - if the transaction state can not be determined (this can happen for instance when communication between client and server fails or times out).

    - #### addStatement

          void addStatement​(Resource subj,
                            IRI pred,
                            Value obj,
                            Resource... contexts)
                     throws SailException

      Adds a statement to the store.
      Parameters:
        `subj` - The subject of the statement to add.
        `pred` - The predicate of the statement to add.
        `obj` - The object of the statement to add.
        `contexts` - The context(s) to add the statement to. Note that this parameter is a vararg and as such is optional. If no contexts are specified, a context-less statement will be added.
      Throws:
        `SailException` - If the statement could not be added, for example because no transaction is active.
        `IllegalStateException` - If the connection has been closed.

    - #### removeStatements

          void removeStatements​(Resource subj,
                                IRI pred,
                                Value obj,
                                Resource... contexts)
                         throws SailException

      Removes all statements matching the specified subject, predicate and object from the repository. All three parameters may be null to indicate wildcards.
      Parameters:
        `subj` - The subject of the statement that should be removed, or null to indicate a wildcard.
        `pred` - The predicate of the statement that should be removed, or null to indicate a wildcard.
        `obj` - The object of the statement that should be removed , or null to indicate a wildcard. *
        `contexts` - The context(s) from which to remove the statement. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.
      Throws:
        `SailException` - If the statement could not be removed, for example because no transaction is active.
        `IllegalStateException` - If the connection has been closed.

    - #### startUpdate

          void startUpdate​(UpdateContext op)
                    throws SailException

      Signals the start of an update operation. The given `op` maybe passed to subsequent `addStatement(UpdateContext, Resource, IRI, Value, Resource...)` or `removeStatement(UpdateContext, Resource, IRI, Value, Resource...)` calls before `endUpdate(UpdateContext)` is called.
      Throws:
        `SailException`

    - #### addStatement

          void addStatement​(UpdateContext op,
                            Resource subj,
                            IRI pred,
                            Value obj,
                            Resource... contexts)
                     throws SailException

      Adds a statement to the store. Called when adding statements through a `UpdateExpr` operation.
      Parameters:
        `op` - operation properties of the `UpdateExpr` operation producing these statements.
        `subj` - The subject of the statement to add.
        `pred` - The predicate of the statement to add.
        `obj` - The object of the statement to add.
        `contexts` - The context(s) to add the statement to. Note that this parameter is a vararg and as such is optional. If no contexts are specified, a context-less statement will be added.
      Throws:
        `SailException` - If the statement could not be added, for example because no transaction is active.
        `IllegalStateException` - If the connection has been closed.

    - #### removeStatement

          void removeStatement​(UpdateContext op,
                               Resource subj,
                               IRI pred,
                               Value obj,
                               Resource... contexts)
                        throws SailException

      Removes all statements matching the specified subject, predicate and object from the repository. All three parameters may be null to indicate wildcards. Called when removing statements through a `UpdateExpr` operation.
      Parameters:
        `op` - operation properties of the `UpdateExpr` operation removing these statements.
        `subj` - The subject of the statement that should be removed.
        `pred` - The predicate of the statement that should be removed.
        `obj` - The object of the statement that should be removed.
        `contexts` - The context(s) from which to remove the statement. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.
      Throws:
        `SailException` - If the statement could not be removed, for example because no transaction is active.
        `IllegalStateException` - If the connection has been closed.

    - #### endUpdate

          void endUpdate​(UpdateContext op)
                  throws SailException

      Indicates that the given `op` will not be used in any call again. Implementations should use this to flush of any temporary operation states that may have occurred.
      Parameters:
        `op` -
      Throws:
        `SailException`

    - #### clear

          void clear​(Resource... contexts)
              throws SailException

      Removes all statements from the specified/all contexts. If no contexts are specified the method operates on the entire repository.
      Parameters:
        `contexts` - The context(s) from which to remove the statements. Note that this parameter is a vararg and as such is optional. If no contexts are specified the method operates on the entire repository. A null value can be used to match context-less statements.
      Throws:
        `SailException` - If the statements could not be removed.
        `IllegalStateException` - If the connection has been closed.

    - #### getNamespaces

          CloseableIteration<? extends Namespace,​SailException> getNamespaces()
                                                                             throws SailException

      Gets the namespaces relevant to the data contained in this Sail object.
      Returns:
        An iterator over the relevant namespaces, should not contain any duplicates.
      Throws:
        `SailException` - If the Sail object encountered an error or unexpected situation internally.
        `IllegalStateException` - If the connection has been closed.

    - #### getNamespace

          String getNamespace​(String prefix)
                       throws SailException

      Gets the namespace that is associated with the specified prefix, if any.
      Parameters:
        `prefix` - A namespace prefix, or an empty string in case of the default namespace.
      Returns:
        The namespace name that is associated with the specified prefix, or null if there is no such namespace.
      Throws:
        `SailException` - If the Sail object encountered an error or unexpected situation internally.
        `NullPointerException` - In case prefix is null.
        `IllegalStateException` - If the connection has been closed.

    - #### setNamespace

          void setNamespace​(String prefix,
                            String name)
                     throws SailException

      Sets the prefix for a namespace.
      Parameters:
        `prefix` - The new prefix, or an empty string in case of the default namespace.
        `name` - The namespace name that the prefix maps to.
      Throws:
        `SailException` - If the Sail object encountered an error or unexpected situation internally.
        `NullPointerException` - In case prefix or name is null.
        `IllegalStateException` - If the connection has been closed.

    - #### removeNamespace

          void removeNamespace​(String prefix)
                        throws SailException

      Removes a namespace declaration by removing the association between a prefix and a namespace name.
      Parameters:
        `prefix` - The namespace prefix, or an empty string in case of the default namespace.
      Throws:
        `SailException` - If the Sail object encountered an error or unexpected situation internally.
        `NullPointerException` - In case prefix is null.
        `IllegalStateException` - If the connection has been closed.

    - #### clearNamespaces

          void clearNamespaces()
                        throws SailException

      Removes all namespace declarations from the repository.
      Throws:
        `SailException` - If the Sail object encountered an error or unexpected situation internally.
        `IllegalStateException` - If the connection has been closed.

    - #### pendingRemovals

          @Deprecated
          boolean pendingRemovals()

      Deprecated.
      Indicates if the Sail has any statement removal operations pending (not yet `flushed`) for the current transaction.
      Returns:
        true if any statement removal operations have not yet been flushed, false otherwise.
      See Also:
        `flush()`

    - #### explain

          @Experimental
          default Explanation explain​(Explanation.Level level,
                                      TupleExpr tupleExpr,
                                      Dataset dataset,
                                      BindingSet bindings,
                                      boolean includeInferred,
                                      int timeoutSeconds)

      Explain how the TupleExpr will be (or has been) executed/evaluated by returning a TupleExpr (which may or may not be the provided TupleExpr) that has gone through zero or more of the stages prior to and also including execution as specified by the provided level.

      This method is used by the Query interface.

      WARNING: This method is experimental and is subject to change or removal without warning. There is currently only partial support for this method in RDF4J and and UnsupportedOperationException where support is lacking.

      Parameters:
        `level` - the explanation level, eg. OPTIMIZED
        `tupleExpr` - The tuple expression to evaluate. Mutable.
        `dataset` - The dataset to use for evaluating the query, null to use the Sail's default dataset.
        `bindings` - A set of input parameters for the query evaluation. The keys reference variable names that should be bound to the value they map to.
        `includeInferred` - Indicates whether inferred triples are to be considered in the query result. If false, no inferred statements are returned; if true, inferred statements are returned if available
        `timeoutSeconds` - for explanations that require execution a timeout can be provided in seconds
      Returns:
        The resulting tuple expression after being run through the specified level