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 and Description
<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	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(String sql) Create a call to a stored procedure.
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(String sql) Creates a Script from the given SQL script.
Update	createUpdate(String sql) Create an Insert or Update statement which returns the number of rows modified.
int	execute(String sql, Object... args) Execute a SQL statement, and return the number of rows affected by the statement.
ConfigRegistry	getConfig() Returns the configuration registry associated with this object.
Connection	getConnection() Get the JDBC Connection this Handle uses.
ExtensionMethod	getExtensionMethod()
StatementBuilder	getStatementBuilder()
TransactionIsolationLevel	getTransactionIsolationLevel() Obtain the current transaction isolation level.
<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	isClosed()
boolean	isInTransaction()
boolean	isReadOnly()
PreparedBatch	prepareBatch(String sql) Prepare a batch to execute.
Handle	release(String savepointName) Release a previously created savepoint.
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(String sql, Object... args) Convenience method which creates a query with the given positional arguments
Handle	setReadOnly(boolean readOnly) Set the Handle readOnly.
Handle	setStatementBuilder(StatementBuilder builder) Specify the statement builder to use for this handle.
void	setTransactionIsolation(int level) Set the transaction isolation level on the underlying connection.
void	setTransactionIsolation(TransactionIsolationLevel level) Set the transaction isolation level on the underlying connection.
<X extends Exception> void	useTransaction(HandleConsumer<X> callback) Executes callback in a transaction.
<X extends Exception> void	useTransaction(TransactionIsolationLevel level, HandleConsumer<X> callback) Executes callback in a transaction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

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

Method Detail

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

begin

public Handle begin()

Start a transaction.

Returns:

the same handle

close

public void close()

Closes the handle, its connection, and any other database resources it is holding.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

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.

commit

public Handle commit()

Commit a transaction.

Returns:

the same handle

createBatch

public Batch createBatch()

Create a non-prepared (no bound parameters, but different SQL) batch statement.

Returns:

empty batch

See Also:

prepareBatch(String)

createCall

public Call createCall(String sql)

Create a call to a stored procedure.

Parameters:

sql - the stored procedure sql

Returns:

the Call

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.

Parameters:

sql - SQL that may return results

Returns:

a Query builder

createScript

public Script createScript(String sql)

Creates a Script from the given SQL script.

Parameters:

sql - the SQL script

Returns:

the created Script

createUpdate

public Update createUpdate(String sql)

Create an Insert or Update statement which returns the number of rows modified.

Parameters:

sql - the statement sql

Returns:

the Update builder

execute

public int execute(String 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

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

getExtensionMethod

public ExtensionMethod getExtensionMethod()

Returns:

the extension method currently bound to the handle's context

getStatementBuilder

public StatementBuilder getStatementBuilder()

Returns:

the current StatementBuilder

getTransactionIsolationLevel

public TransactionIsolationLevel getTransactionIsolationLevel()

Obtain the current transaction isolation level.

Returns:

the current isolation level on the underlying connection

inTransaction

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

inTransaction

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

isClosed

public boolean isClosed()

Returns:

whether the Handle is closed

isInTransaction

public boolean isInTransaction()

Returns:

whether the handle is in a transaction. Delegates to the underlying TransactionHandler.

isReadOnly

public boolean isReadOnly()

Returns:

whether the connection is in read-only mode

See Also:

Connection.isReadOnly()

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.

Parameters:

sql - the batch SQL

Returns:

a batch which can have "statements" added

release

public Handle release(String savepointName)

Release a previously created savepoint.

Parameters:

savepointName - the name of the savepoint to release

Returns:

the same handle

rollback

public Handle rollback()

Rollback a transaction.

Returns:

the same 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

select

public Query select(String 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

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:

Connection.setReadOnly(boolean)

setStatementBuilder

public Handle setStatementBuilder(StatementBuilder builder)

Specify the statement builder to use for this handle.

Parameters:

builder - StatementBuilder to be used

Returns:

this

setTransactionIsolation

public void setTransactionIsolation(int level)

Set the transaction isolation level on the underlying connection.

Parameters:

level - the isolation level to use

setTransactionIsolation

public void setTransactionIsolation(TransactionIsolationLevel level)

Set the transaction isolation level on the underlying connection.

Parameters:

level - the isolation level to use

useTransaction

public <X extends Exception> void useTransaction(HandleConsumer<X> callback)
                                          throws X extends Exception

Executes callback in a transaction.

Type Parameters:

X - exception type thrown by the callback, if any

Parameters:

callback - a callback which will receive an open handle, in a transaction.

Throws:

X - any exception thrown by the callback

X extends Exception

useTransaction

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

callback - a callback which will receive an open handle, in a transaction.

Throws:

X - any exception thrown by the callback

X extends Exception