org.skife.jdbi.v2
Interface Handle

public interface Handle

This represents a connection to the database system. It ususally is a wrapper around a JDBC Connection object.

Method Summary

<SqlObjectType> SqlObjectType	attach(Class<SqlObjectType> sqlObjectType) Create a a sql object of the specified type bound to this handle.
Handle	begin() Start a transaction
Handle	checkpoint(String name) Create a transaction checkpoint (savepoint in JDBC terminology) with the name provided.
void	close()
Handle	commit() Commit a transaction
Batch	createBatch() Create a non-prepared (no bound parameters, but different SQL, batch statement
Call	createCall(String callableSql) Create a call to a stored procedure
Query<Map<String,Object>>	createQuery(String sql) Return a default Query instance which can be executed later, as long as this handle remains open.
Script	createScript(String name) Creates an SQL script, looking for the source of the script using the current statement locator (which defaults to searching the classpath)
Update	createStatement(String sql) Create an Insert or Update statement which returns the number of rows modified.
void	define(String key, Object value) Define a statement attribute which will be applied to all StatementContext instances for statements created from this handle
void	execute(String sql, Object... args) Execute some SQL with no return value
Connection	getConnection() Get the JDBC Connection this Handle uses
TransactionIsolationLevel	getTransactionIsolationLevel() Obtain the current transaction isolation level
int	insert(String sql, Object... args) Execute a simple insert statement
<ReturnType> ReturnType	inTransaction(TransactionCallback<ReturnType> callback) Executes callback in a transaction.
<ReturnType> ReturnType	inTransaction(TransactionIsolationLevel level, TransactionCallback<ReturnType> callback) Executes callback in a transaction.
boolean	isInTransaction() Is the handle in a transaction? It defers to the underlying TransactionHandler
PreparedBatch	prepareBatch(String sql) Prepare a batch to execute.
void	registerMapper(ResultSetMapper mapper) Register a result set mapper which will have its parameterized type inspected to determine what it maps to Will be used with Query.mapTo(Class) for registered mappings.
void	registerMapper(ResultSetMapperFactory factory) Register a result set mapper factory.
Handle	release(String checkpointName) Release a previously created checkpoint
Handle	rollback() Rollback a transaction
Handle	rollback(String checkpointName) Rollback a transaction to a named checkpoint
List<Map<String,Object>>	select(String sql, Object... args) Convenience method which executes a select with purely positional arguments
void	setSQLLog(SQLLog log) Specify the class used to log sql statements.
void	setStatementBuilder(StatementBuilder builder) Specify the statement builder to use for this handle
void	setStatementLocator(StatementLocator locator) Allows for overiding the default statement locator.
void	setStatementRewriter(StatementRewriter rewriter) Allows for overiding the default statement rewriter.
void	setTimingCollector(TimingCollector timingCollector) Specify the class used to collect timing information.
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
int	update(String sql, Object... args) Execute a simple update statement

Method Detail

attach

<SqlObjectType> SqlObjectType attach(Class<SqlObjectType> sqlObjectType)

Create a a sql object of the specified type bound to this handle. Any state changes to the handle, or the sql object, such as transaction status, closing it, etc, will apply to both the object and the handle.

Type Parameters:

SqlObjectType -

Parameters:

sqlObjectType -

Returns:

the new sql object bound to this handle

begin

Handle begin()

Start a transaction

checkpoint

Handle checkpoint(String name)

Create a transaction checkpoint (savepoint in JDBC terminology) with the name provided.

Parameters:

name - The name of the checkpoint

Returns:

The same handle

close

void close()

Throws:

UnableToCloseResourceException - if any resources throw exception while closing

commit

Handle commit()

Commit a transaction

createBatch

Batch createBatch()

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

Returns:

empty batch

See Also:

prepareBatch(String)

createCall

Call createCall(String callableSql)

Create a call to a stored procedure

Parameters:

callableSql -

Returns:

the Call

createQuery

Query<Map<String,Object>> createQuery(String sql)

Return a default Query instance which can be executed later, as long as this handle remains open.

Parameters:

sql - the select sql

createScript

Script createScript(String name)

Creates an SQL script, looking for the source of the script using the current statement locator (which defaults to searching the classpath)

createStatement

Update createStatement(String sql)

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

Parameters:

sql - The statement sql

define

void define(String key,
            Object value)

Define a statement attribute which will be applied to all StatementContext instances for statements created from this handle

Parameters:

key - Attribute name

value - Attribute value

execute

void execute(String sql,
             Object... args)

Execute some SQL with no return value

Parameters:

sql - the sql to execute

args - arguments to bind to the sql

getConnection

Connection getConnection()

Get the JDBC Connection this Handle uses

Returns:

the JDBC Connection this Handle uses

getTransactionIsolationLevel

TransactionIsolationLevel getTransactionIsolationLevel()

Obtain the current transaction isolation level

Returns:

the current isolation level on the underlying connection

insert

int insert(String sql,
           Object... args)

Execute a simple insert statement

Parameters:

sql - the insert SQL

Returns:

the number of rows inserted

inTransaction

<ReturnType> ReturnType inTransaction(TransactionCallback<ReturnType> callback)
                         throws TransactionFailedException

Executes callback in a transaction. If the transaction succeeds, the result of the callback will be returned. If it fails a TransactionFailedException will be thrown.

Returns:

value returned from the callback

Throws:

TransactionFailedException - if the transaction failed in the callback

inTransaction

<ReturnType> ReturnType inTransaction(TransactionIsolationLevel level,
                                      TransactionCallback<ReturnType> callback)
                         throws TransactionFailedException

Executes callback in a transaction. If the transaction succeeds, the result of the callback will be returned. If it fails a TransactionFailedException will be thrown.

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.

Returns:

value returned from the callback

Throws:

TransactionFailedException - if the transaction failed in the callback

isInTransaction

boolean isInTransaction()

Is the handle in a transaction? It defers to the underlying TransactionHandler

prepareBatch

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

registerMapper

void registerMapper(ResultSetMapper mapper)

Register a result set mapper which will have its parameterized type inspected to determine what it maps to Will be used with Query.mapTo(Class) for registered mappings.

registerMapper

void registerMapper(ResultSetMapperFactory factory)

Register a result set mapper factory. Will be used with Query.mapTo(Class) for registerd mappings.

release

Handle release(String checkpointName)

Release a previously created checkpoint

Parameters:

checkpointName - the name of the checkpoint to release

rollback

Handle rollback()

Rollback a transaction

rollback

Handle rollback(String checkpointName)

Rollback a transaction to a named checkpoint

Parameters:

checkpointName - the name of the checkpoint, previously declared with checkpoint(java.lang.String)

select

List<Map<String,Object>> select(String sql,
                                Object... args)

Convenience method which executes a select with purely positional arguments

Parameters:

sql - SQL or named statement

args - arguments to bind positionally

Returns:

results of the query

setSQLLog

void setSQLLog(SQLLog log)

Specify the class used to log sql statements. The default is inherited from the DBI used to create this Handle.

setStatementBuilder

void setStatementBuilder(StatementBuilder builder)

Specify the statement builder to use for this handle

Parameters:

builder - StatementBuilder to be used

setStatementLocator

void setStatementLocator(StatementLocator locator)

Allows for overiding the default statement locator. The default searches the classpath for named statements

setStatementRewriter

void setStatementRewriter(StatementRewriter rewriter)

Allows for overiding the default statement rewriter. The default handles named parameter interpolation.

setTimingCollector

void setTimingCollector(TimingCollector timingCollector)

Specify the class used to collect timing information. The default is inherited from the DBI used to create this Handle.

setTransactionIsolation

void setTransactionIsolation(int level)

Set the transaction isolation level on the underlying connection

Parameters:

level - the isolation level to use

setTransactionIsolation

void setTransactionIsolation(TransactionIsolationLevel level)

Set the transaction isolation level on the underlying connection

Parameters:

level - the isolation level to use

update

int update(String sql,
           Object... args)

Execute a simple update statement

Parameters:

sql - the update SQL

args - positional arguments

Returns:

the number of updated inserted