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 Summary

Modifier and Type	Method	Description
final void	addCleanable(Cleanable cleanable)	Registers a Cleanable to be invoked when the handle is closed.
Handle	addHandleListener(HandleListener handleListener)	Add a specific HandleListener which is called for specific events for this Handle.
Handle	afterCommit(Runnable afterCommit)	Execute an action the next time this Handle commits, unless it is rolled back first.
Handle	afterRollback(Runnable afterRollback)	Execute an action the next time this Handle rolls back, unless it is committed first.
<T> T	attach(Class<T> extensionType)	Create a Jdbi extension object of the specified type bound to this handle.
Handle	begin()	Start a transaction.
void	clean()	Release any database resource that may be held by the handle.
void	close()	Closes the handle, its connection, and any other database resources it is holding.
Handle	commit()	Commit a transaction.
Batch	createBatch()	Create a non-prepared (no bound parameters, but different SQL) batch statement.
Call	createCall(CharSequence sql)	Create a call to a stored procedure.
Call	createCall(String sql)	Create a call to a stored procedure.
Query	createQuery(CharSequence sql)	Return a Query instance that executes a statement with bound parameters and maps the result set into Java types.
Query	createQuery(String sql)	Return a Query instance that executes a statement with bound parameters and maps the result set into Java types.
Script	createScript(CharSequence sql)	Creates a Script from the given SQL script.
Script	createScript(String sql)	Create an Insert or Update statement which returns the number of rows modified.
Update	createUpdate(CharSequence sql)	Create an Insert or Update statement which returns the number of rows modified.
Update	createUpdate(String sql)	Create an Insert or Update statement which returns the number of rows modified.
boolean	equals(Object o)
int	execute(CharSequence sql, Object... args)	Execute a SQL statement, and return the number of rows affected by the statement.
int	execute(String sql, Object... args)	Execute a SQL statement, and return the number of rows affected by the statement.
ConfigRegistry	getConfig()	The current configuration object associated with this handle.
Connection	getConnection()	Get the JDBC Connection this Handle uses.
ExtensionMethod	getExtensionMethod()	Returns the extension method currently bound to the handle's context.
Jdbi	getJdbi()	Returns the Jdbi object used to create this handle.
StatementBuilder	getStatementBuilder()	Returns the current StatementBuilder which is used to create new JDBC Statement objects.
TransactionIsolationLevel	getTransactionIsolationLevel()	Obtain the current transaction isolation level.
int	hashCode()
<R, X extends Exception> R	inTransaction(HandleCallback<R,X> callback)	Executes callback in a transaction, and returns the result of the callback.
<R, X extends Exception> R	inTransaction(TransactionIsolationLevel level, HandleCallback<R,X> callback)	Executes callback in a transaction, and returns the result of the callback.
boolean	isClean()	Returns true if the Handle currently holds no database resources.
boolean	isClosed()	Returns true if the Handle has been closed.
boolean	isInTransaction()	Returns whether the handle is in a transaction.
boolean	isReadOnly()	Whether the connection is in read-only mode.
PreparedBatch	prepareBatch(CharSequence sql)	Prepare a batch to execute.
PreparedBatch	prepareBatch(String sql)	Prepare a batch to execute.
ResultBearing	queryMetadata(MetaData.MetaDataResultSetProvider metadataFunction)	Access database metadata that returns a ResultSet.
<T> T	queryMetadata(MetaData.MetaDataValueProvider<T> metadataFunction)	Access all database metadata that returns simple values.
Handle	release(String savepointName)	Deprecated. Use releaseSavepoint(String)
Handle	releaseSavepoint(String savepointName)	Release a previously created savepoint.
final void	removeCleanable(Cleanable cleanable)	Unregister a Cleanable from the Handle.
Handle	removeHandleListener(HandleListener handleListener)	Remove a HandleListener from this handle.
Handle	rollback()	Rollback a transaction.
Handle	rollbackToSavepoint(String savepointName)	Rollback a transaction to a named savepoint.
Handle	savepoint(String name)	Create a transaction savepoint with the name provided.
Query	select(CharSequence sql, Object... args)	Convenience method which creates a query with the given positional arguments.
Query	select(String sql, Object... args)	Convenience method which creates a query with the given positional arguments.
Handle	setReadOnly(boolean readOnly)	Set the Handle read-only.
Handle	setStatementBuilder(StatementBuilder builder)	Set the statement builder for this handle.
void	setTransactionIsolation(int level)	Deprecated. Use setTransactionIsolationLevel(TransactionIsolationLevel)
void	setTransactionIsolation(TransactionIsolationLevel level)	Deprecated. Use setTransactionIsolationLevel(int)
void	setTransactionIsolationLevel(int level)	Set the transaction isolation level on the underlying connection if it is different from the current isolation level.
void	setTransactionIsolationLevel(TransactionIsolationLevel level)	Set the transaction isolation level on the underlying connection if it is different from the current isolation level.
<X extends Exception> void	useTransaction(HandleConsumer<X> consumer)	Executes callback in a transaction.
<X extends Exception> void	useTransaction(TransactionIsolationLevel level, HandleConsumer<X> consumer)	Executes callback in a transaction.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.jdbi.v3.core.config.Configurable

addCustomizer, configure, define, getConfig, registerArgument, registerArgument, registerArrayType, registerArrayType, registerArrayType, registerArrayType, registerCodecFactory, registerCollector, registerCollector, registerColumnMapper, registerColumnMapper, registerColumnMapper, registerColumnMapper, registerColumnMapper, registerColumnMapper, registerExtension, registerRowMapper, registerRowMapper, registerRowMapper, registerRowMapper, setMapKeyColumn, setMapValueColumn, setSqlArrayArgumentStrategy, setSqlLogger, setSqlParser, setTemplateEngine, setTimingCollector

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:

• select(CharSequence, Object...)

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:

• 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(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:

• prepareBatch(CharSequence)

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:

• createCall(CharSequence)

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:

• createQuery(CharSequence)

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:

• createScript(CharSequence)

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:

• 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(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:

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