Package org.jdbi.v3.core

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()

    • getConfig

      public ConfigRegistry getConfig()
      Description copied from interface: Configurable
      Returns the configuration registry associated with this object.
      Specified by:
      getConfig in interface Configurable<Handle>
      Returns:
      the configuration registry associated with this object.

    • 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.
      Returns:
      the current StatementBuilder

    • setStatementBuilder

      public Handle setStatementBuilder(StatementBuilder builder)
      Specify the statement builder to use for this handle.
      Parameters:
      builder - StatementBuilder to be used
      Returns:
      this

    • 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.

    • 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)
      Deprecated delegate - please use CharSequence signature for future compatibility.

    • 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)
      Deprecated delegate - please use CharSequence signature for future compatibility.

    • 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)
      Deprecated delegate - please use CharSequence signature for future compatibility.

    • 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)
      Deprecated delegate - please use CharSequence signature for future compatibility.

    • 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)
      Deprecated delegate - please use CharSequence signature for future compatibility.

    • 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)
      Deprecated delegate - please use CharSequence signature for future compatibility.

    • 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)
      Deprecated delegate - please use CharSequence signature for future compatibility.

    • 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

      public Handle release(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 readOnly. 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

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

    • setTransactionIsolation

      public void setTransactionIsolation(int level)
      Set the transaction isolation level on the underlying connection.
      Parameters:
      level - the isolation level to use

    • 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