Package org.jdbi.v3.core

Class Handle

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, Configurable<Handle>
    public class Handle
extends java.lang.Object
implements java.io.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.

    • Field Detail

      • LOG

        private static final org.slf4j.Logger LOG

      • jdbi

        private final Jdbi jdbi

      • connectionCleaner

        private final Cleanable connectionCleaner

      • connection

        private final java.sql.Connection connection

      • forceEndTransactions

        private final boolean forceEndTransactions

      • defaultExtensionContext

        private final ExtensionContext defaultExtensionContext

      • cleanables

        private final java.util.Set<Cleanable> cleanables

      • handleListeners

        private final java.util.Set<HandleListener> handleListeners

      • closed

        private final java.util.concurrent.atomic.AtomicBoolean closed

    • Constructor Detail

      • Handle

        private Handle​(Jdbi jdbi,
               Cleanable connectionCleaner,
               TransactionHandler transactionHandler,
               StatementBuilder statementBuilder,
               java.sql.Connection connection)
        throws java.sql.SQLException
        Throws:
        java.sql.SQLException

    • Method Detail

      • getJdbi

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

      • getConnection

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

      • 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

      • 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 java.lang.AutoCloseable
        Specified by:
        close in interface java.io.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​(java.lang.CharSequence sql,
                    java.lang.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​(java.lang.String sql,
                    java.lang.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:
        select(CharSequence, Object...)

      • execute

        public int execute​(java.lang.CharSequence sql,
                   java.lang.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​(java.lang.String sql,
                   java.lang.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:
        execute(CharSequence, Object...)

      • createBatch

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

      • prepareBatch

        public PreparedBatch prepareBatch​(java.lang.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​(java.lang.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:
        prepareBatch(CharSequence)

      • createCall

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

      • createCall

        public Call createCall​(java.lang.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:
        createCall(CharSequence)

      • createQuery

        public Query createQuery​(java.lang.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​(java.lang.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:
        createQuery(CharSequence)

      • createScript

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

      • createScript

        public Script createScript​(java.lang.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:
        createScript(CharSequence)

      • createUpdate

        public Update createUpdate​(java.lang.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​(java.lang.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(CharSequence)

      • 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​(java.lang.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​(java.lang.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​(java.lang.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.

      • msSince

        private static long msSince​(long start)

      • savepoint

        public Handle savepoint​(java.lang.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​(java.lang.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​(java.lang.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:
        Connection.isReadOnly()

      • 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:
        Connection.setReadOnly(boolean)

      • inTransaction

        public <R,​X extends java.lang.Exception> R inTransaction​(HandleCallback<R,​X> callback)
                                                        throws X extends java.lang.Exception
        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
        X extends java.lang.Exception

      • useTransaction

        public <X extends java.lang.Exception> void useTransaction​(HandleConsumer<X> consumer)
                                                    throws X extends java.lang.Exception
        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
        X extends java.lang.Exception

      • inTransaction

        public <R,​X extends java.lang.Exception> R inTransaction​(TransactionIsolationLevel level,
                                                               HandleCallback<R,​X> callback)
                                                        throws X extends java.lang.Exception
        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
        X extends java.lang.Exception

      • useTransaction

        public <X extends java.lang.Exception> void useTransaction​(TransactionIsolationLevel level,
                                                           HandleConsumer<X> consumer)
                                                    throws X extends java.lang.Exception
        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
        X extends java.lang.Exception

      • 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(TransactionIsolationLevel), Connection.TRANSACTION_NONE, Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, Connection.TRANSACTION_SERIALIZABLE

      • 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:
        setTransactionIsolationLevel(TransactionIsolationLevel), Connection.TRANSACTION_NONE, Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, Connection.TRANSACTION_SERIALIZABLE

      • getTransactionIsolationLevel

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

      • attach

        public <T> T attach​(java.lang.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

      • notifyHandleCreated

        private void notifyHandleCreated()

      • notifyHandleClosed

        private void notifyHandleClosed()

      • cleanConnection

        private void cleanConnection​(boolean doForceEndTransactions)

      • checkConnectionIsLive

        private boolean checkConnectionIsLive()

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object