Class Handle

java.lang.Object
org.jdbi.v3.core.Handle
All Implemented Interfaces:
Closeable, AutoCloseable, Configurable<Handle>
public class Handle extends Object implements Closeable, Configurable<Handle>
This represents a connection to the database system. It is a wrapper around a JDBC Connection object. Handle provides essential methods for transaction management, statement creation, and other operations tied to the database session.

  • Method Details

    • getJdbi

      public Jdbi getJdbi()
      Returns the Jdbi object used to create this handle.
      Returns:
      The Jdbi object used to create this handle.

    • getConfig

      public ConfigRegistry getConfig()
      The current configuration object associated with this handle.
      Specified by:
      getConfig in interface Configurable<Handle>
      Returns:
      A ConfigRegistry object that is associated with the handle.

    • getConnection

      public Connection getConnection()
      Get the JDBC Connection this Handle uses.
      Returns:
      the JDBC Connection this Handle uses.

    • getStatementBuilder

      public StatementBuilder getStatementBuilder()
      Returns the current StatementBuilder which is used to create new JDBC Statement objects.
      Returns:
      the current StatementBuilder.

    • setStatementBuilder

      public Handle setStatementBuilder(StatementBuilder builder)
      Set the statement builder for this handle.
      Parameters:
      builder - StatementBuilder to be used. Must not be null.
      Returns:
      this

    • addHandleListener

      public Handle addHandleListener(HandleListener handleListener)
      Add a specific HandleListener which is called for specific events for this Handle. Note that it is not possible to add a listener that wants to implement HandleListener.handleCreated(org.jdbi.v3.core.Handle) this way as the handle has already been created. Use Handles.addListener(org.jdbi.v3.core.HandleListener) in this case.
      A listener added through this call is specific to the handle and not shared with other handles.
      Parameters:
      handleListener - A HandleListener object.
      Returns:
      The handle itself.

    • removeHandleListener

      public Handle removeHandleListener(HandleListener handleListener)
      Remove a HandleListener from this handle.
      Removing the listener only affects the current handle. To remove a listener for all future handles, use Handles.removeListener(org.jdbi.v3.core.HandleListener).
      Parameters:
      handleListener - A HandleListener object.
      Returns:
      The handle itself.

    • addCleanable

      public final void addCleanable(Cleanable cleanable)
      Registers a Cleanable to be invoked when the handle is closed. Any cleanable registered here will only be cleaned once.

      Resources cleaned up by Jdbi include ResultSet, Statement, Array, and StatementBuilder.

      Parameters:
      cleanable - the Cleanable to clean on close

    • removeCleanable

      public final void removeCleanable(Cleanable cleanable)
      Unregister a Cleanable from the Handle.
      Parameters:
      cleanable - the Cleanable to be unregistered.

    • close

      public void close()
      Closes the handle, its connection, and any other database resources it is holding.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      CloseException - if any resources throw exception while closing
      TransactionException - if called while the handle has a transaction open. The open transaction will be rolled back.

    • clean

      public void clean()
      Release any database resource that may be held by the handle. This affects any statement that was created from the Handle.

    • isClean

      public boolean isClean()
      Returns true if the Handle currently holds no database resources.
      Note that this method will return false right after statement creation as every statement registers its statement context with the handle. Once
      Returns:
      True if the handle holds no database resources.

    • isClosed

      public boolean isClosed()
      Returns true if the Handle has been closed.
      Returns:
      True if the Handle is closed.

    • select

      public Query select(CharSequence sql, Object... args)
      Convenience method which creates a query with the given positional arguments.
      Parameters:
      sql - SQL or named statement
      args - arguments to bind positionally
      Returns:
      query object

    • select

      public Query select(String sql, Object... args)
      Convenience method which creates a query with the given positional arguments. Takes a string argument for backwards compatibility reasons.
      Parameters:
      sql - SQL or named statement
      args - arguments to bind positionally
      Returns:
      query object
      See Also:

    • execute

      public int execute(CharSequence sql, Object... args)
      Execute a SQL statement, and return the number of rows affected by the statement.
      Parameters:
      sql - the SQL statement to execute, using positional parameters (if any).
      args - positional arguments.
      Returns:
      the number of rows affected.

    • execute

      public int execute(String sql, Object... args)
      Execute a SQL statement, and return the number of rows affected by the statement. Takes a string argument for backwards compatibility reasons.
      Parameters:
      sql - the SQL statement to execute, using positional parameters (if any).
      args - positional arguments.
      Returns:
      the number of rows affected.
      See Also:

    • createBatch

      public Batch createBatch()
      Create a non-prepared (no bound parameters, but different SQL) batch statement.
      Returns:
      empty batch
      See Also:

    • prepareBatch

      public PreparedBatch prepareBatch(CharSequence sql)
      Prepare a batch to execute. This is for efficiently executing more than one of the same statements with different parameters bound.
      Parameters:
      sql - the batch SQL.
      Returns:
      a batch which can have "statements" added.

    • prepareBatch

      public PreparedBatch prepareBatch(String sql)
      Prepare a batch to execute. This is for efficiently executing more than one of the same statements with different parameters bound. Takes a string argument for backwards compatibility reasons.
      Parameters:
      sql - the batch SQL.
      Returns:
      a batch which can have "statements" added.
      See Also:

    • createCall

      public Call createCall(CharSequence sql)
      Create a call to a stored procedure.
      Parameters:
      sql - the stored procedure sql.
      Returns:
      the Call.

    • createCall

      public Call createCall(String sql)
      Create a call to a stored procedure. Takes a string argument for backwards compatibility reasons.
      Parameters:
      sql - the stored procedure sql.
      Returns:
      the Call.
      See Also:

    • createQuery

      public Query createQuery(CharSequence sql)
      Return a Query instance that executes a statement with bound parameters and maps the result set into Java types.
      Parameters:
      sql - SQL that may return results.
      Returns:
      a Query builder.

    • createQuery

      public Query createQuery(String sql)
      Return a Query instance that executes a statement with bound parameters and maps the result set into Java types. Takes a string argument for backwards compatibility reasons.
      Parameters:
      sql - SQL that may return results.
      Returns:
      a Query builder.
      See Also:

    • createScript

      public Script createScript(CharSequence sql)
      Creates a Script from the given SQL script.
      Parameters:
      sql - the SQL script.
      Returns:
      the created Script.

    • createScript

      public Script createScript(String sql)
      Create an Insert or Update statement which returns the number of rows modified. Takes a string argument for backwards compatibility reasons.
      Parameters:
      sql - the statement sql.
      Returns:
      the Update builder.
      See Also:

    • createUpdate

      public Update createUpdate(CharSequence sql)
      Create an Insert or Update statement which returns the number of rows modified.
      Parameters:
      sql - the statement sql.
      Returns:
      the Update builder.

    • createUpdate

      public Update createUpdate(String sql)
      Create an Insert or Update statement which returns the number of rows modified. Takes a string argument for backwards compatibility reasons.
      Parameters:
      sql - the statement sql.
      Returns:
      the Update builder.
      See Also:

    • queryMetadata

      public ResultBearing queryMetadata(MetaData.MetaDataResultSetProvider metadataFunction)
      Access database metadata that returns a ResultSet. All methods of ResultBearing can be used to format and map the returned results. 
           List<String> catalogs = h.queryMetadata(DatabaseMetaData::getCatalogs)
                                      .mapTo(String.class)
                                      .list();

      returns the list of catalogs from the current database.

      Parameters:
      metadataFunction - Maps the provided DatabaseMetaData object onto a ResultSet object.
      Returns:
      The metadata builder.

    • queryMetadata

      public <T> T queryMetadata(MetaData.MetaDataValueProvider<T> metadataFunction)
      Access all database metadata that returns simple values. 
           boolean supportsTransactions = handle.queryMetadata(DatabaseMetaData::supportsTransactions);
      Parameters:
      metadataFunction - Maps the provided DatabaseMetaData object to a response object.
      Returns:
      The response object.

    • isInTransaction

      public boolean isInTransaction()
      Returns whether the handle is in a transaction. Delegates to the underlying TransactionHandler.
      Returns:
      True if the handle is in a transaction.

    • begin

      public Handle begin()
      Start a transaction.
      Returns:
      the same handle.

    • commit

      public Handle commit()
      Commit a transaction.
      Returns:
      the same handle.

    • rollback

      public Handle rollback()
      Rollback a transaction.
      Returns:
      the same handle.

    • afterCommit

      @Beta public Handle afterCommit(Runnable afterCommit)
      Execute an action the next time this Handle commits, unless it is rolled back first.
      Parameters:
      afterCommit - the action to execute after commit.
      Returns:
      this Handle.

    • afterRollback

      @Beta public Handle afterRollback(Runnable afterRollback)
      Execute an action the next time this Handle rolls back, unless it is committed first.
      Parameters:
      afterRollback - the action to execute after rollback.
      Returns:
      this Handle.

    • rollbackToSavepoint

      public Handle rollbackToSavepoint(String savepointName)
      Rollback a transaction to a named savepoint.
      Parameters:
      savepointName - the name of the savepoint, previously declared with savepoint(java.lang.String).
      Returns:
      the same handle.

    • savepoint

      public Handle savepoint(String name)
      Create a transaction savepoint with the name provided.
      Parameters:
      name - The name of the savepoint.
      Returns:
      The same handle.

    • release

      @Deprecated public Handle release(String savepointName)
      Deprecated.
      Use releaseSavepoint(String)
      Release a previously created savepoint.
      Parameters:
      savepointName - the name of the savepoint to release.
      Returns:
      the same handle.

    • releaseSavepoint

      public Handle releaseSavepoint(String savepointName)
      Release a previously created savepoint.
      Parameters:
      savepointName - the name of the savepoint to release.
      Returns:
      the same handle.

    • isReadOnly

      public boolean isReadOnly()
      Whether the connection is in read-only mode.
      Returns:
      True if the connection is in read-only mode.
      See Also:

    • setReadOnly

      public Handle setReadOnly(boolean readOnly)
      Set the Handle read-only. This acts as a hint to the database to improve performance or concurrency.
      May not be called in an active transaction!
      Parameters:
      readOnly - whether the Handle is readOnly.
      Returns:
      this Handle.
      See Also:

    • inTransaction

      public <R, X extends Exception> R inTransaction(HandleCallback<R,X> callback) throws X
      Executes callback in a transaction, and returns the result of the callback.
      Type Parameters:
      R - type returned by callback
      X - exception type thrown by the callback, if any
      Parameters:
      callback - a callback which will receive an open handle, in a transaction.
      Returns:
      value returned from the callback
      Throws:
      X - any exception thrown by the callback

    • useTransaction

      public <X extends Exception> void useTransaction(HandleConsumer<X> consumer) throws X
      Executes callback in a transaction.
      Type Parameters:
      X - exception type thrown by the callback, if any
      Parameters:
      consumer - a callback which will receive an open handle, in a transaction.
      Throws:
      X - any exception thrown by the callback

    • inTransaction

      public <R, X extends Exception> R inTransaction(TransactionIsolationLevel level, HandleCallback<R,X> callback) throws X
      Executes callback in a transaction, and returns the result of the callback.

      This form accepts a transaction isolation level which will be applied to the connection for the scope of this transaction, after which the original isolation level will be restored.

      Type Parameters:
      R - type returned by callback
      X - exception type thrown by the callback, if any
      Parameters:
      level - the transaction isolation level which will be applied to the connection for the scope of this transaction, after which the original isolation level will be restored.
      callback - a callback which will receive an open handle, in a transaction.
      Returns:
      value returned from the callback
      Throws:
      X - any exception thrown by the callback

    • useTransaction

      public <X extends Exception> void useTransaction(TransactionIsolationLevel level, HandleConsumer<X> consumer) throws X
      Executes callback in a transaction.

      This form accepts a transaction isolation level which will be applied to the connection for the scope of this transaction, after which the original isolation level will be restored.

      Type Parameters:
      X - exception type thrown by the callback, if any
      Parameters:
      level - the transaction isolation level which will be applied to the connection for the scope of this transaction, after which the original isolation level will be restored.
      consumer - a callback which will receive an open handle, in a transaction.
      Throws:
      X - any exception thrown by the callback

    • setTransactionIsolation

      @Deprecated public void setTransactionIsolation(TransactionIsolationLevel level)
      Deprecated.
      Use setTransactionIsolationLevel(int)
      Set the transaction isolation level on the underlying connection if it is different from the current isolation level.
      Parameters:
      level - the TransactionIsolationLevel to use.
      Throws:
      UnableToManipulateTransactionIsolationLevelException - if isolation level is not supported by the underlying connection or JDBC driver.

    • setTransactionIsolationLevel

      public void setTransactionIsolationLevel(TransactionIsolationLevel level)
      Set the transaction isolation level on the underlying connection if it is different from the current isolation level.
      Parameters:
      level - the TransactionIsolationLevel to use.
      Throws:
      UnableToManipulateTransactionIsolationLevelException - if isolation level is not supported by the underlying connection or JDBC driver.

    • setTransactionIsolation

      @Deprecated public void setTransactionIsolation(int level)
      Deprecated.
      Use setTransactionIsolationLevel(TransactionIsolationLevel)
      Set the transaction isolation level on the underlying connection if it is different from the current isolation level.
      Parameters:
      level - the isolation level to use.
      See Also:

    • setTransactionIsolationLevel

      public void setTransactionIsolationLevel(int level)
      Set the transaction isolation level on the underlying connection if it is different from the current isolation level.
      Parameters:
      level - the isolation level to use.
      See Also:

    • getTransactionIsolationLevel

      public TransactionIsolationLevel getTransactionIsolationLevel()
      Obtain the current transaction isolation level.
      Returns:
      the current isolation level on the underlying connection.

    • attach

      public <T> T attach(Class<T> extensionType)
      Create a Jdbi extension object of the specified type bound to this handle. The returned extension's lifecycle is coupled to the lifecycle of this handle. Closing the handle will render the extension unusable.
      Type Parameters:
      T - the extension type
      Parameters:
      extensionType - the extension class
      Returns:
      the new extension object bound to this handle

    • getExtensionMethod

      public ExtensionMethod getExtensionMethod()
      Returns the extension method currently bound to the handle's context.
      Returns:
      the extension method currently bound to the handle's context

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object