Handle (jDBI 2.79-SNAPSHOT API)

All Superinterfaces:

AutoCloseable, Closeable
```
public interface Handle
extends Closeable
```
This represents a connection to the database system. It usually is a wrapper around a JDBC Connection object.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`<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
`SqlObjectContext`	`getSqlObjectContext()`
`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`	`isClosed()`
`boolean`	`isInTransaction()` Is the handle in a transaction? It defers to the underlying `TransactionHandler`
`PreparedBatch`	`prepareBatch(String sql)` Prepare a batch to execute.
`void`	`registerArgumentFactory(ArgumentFactory argumentFactory)`
`void`	`registerColumnMapper(ResultColumnMapper mapper)` Register a result column mapper which will have its parameterized type inspected to determine what it maps to Column mappers may be reused by `ResultSetMapper` to map individual columns.
`void`	`registerColumnMapper(ResultColumnMapperFactory factory)` Register a result column mapper factory.
`void`	`registerContainerFactory(ContainerFactory<?> factory)`
`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`	`setSqlObjectContext(SqlObjectContext context)`
`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
`void`	`useTransaction(TransactionConsumer callback)` Executes `callback` in a transaction.
`void`	`useTransaction(TransactionIsolationLevel level, TransactionConsumer callback)` Executes `callback` in a transaction.

- 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()
```
    Specified by:
    
    close in interface AutoCloseable
    
    Specified by:
    
    close in interface Closeable
  - 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
  - getSqlObjectContext
```
SqlObjectContext getSqlObjectContext()
```
  - 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
  - isClosed
```
boolean isClosed()
```
    Returns:
    
    true if this handle is closed
  - 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
  - registerArgumentFactory
```
void registerArgumentFactory(ArgumentFactory argumentFactory)
```
  - registerColumnMapper
```
void registerColumnMapper(ResultColumnMapper mapper)
```
    Register a result column mapper which will have its parameterized type inspected to determine what it maps to Column mappers may be reused by ResultSetMapper to map individual columns.
  - registerColumnMapper
```
void registerColumnMapper(ResultColumnMapperFactory factory)
```
    Register a result column mapper factory. Column mappers may be reused by ResultSetMapper to map individual columns.
  - registerContainerFactory
```
void registerContainerFactory(ContainerFactory<?> factory)
```
  - 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.
  - setSqlObjectContext
```
void setSqlObjectContext(SqlObjectContext context)
```
  - 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
  - useTransaction
```
void useTransaction(TransactionConsumer 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.
    
    Throws:
    
    TransactionFailedException - if the transaction failed in the callback
  - useTransaction
```
void useTransaction(TransactionIsolationLevel level,
                    TransactionConsumer 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.
    
    Throws:
    
    TransactionFailedException - if the transaction failed in the callback

Interface Handle

Method Summary

Method Detail

attach

begin

checkpoint

close

commit

createBatch

createCall

createQuery

createScript

createStatement

define

execute

getConnection

getSqlObjectContext

getTransactionIsolationLevel

insert

inTransaction

inTransaction

isClosed

isInTransaction

prepareBatch

registerArgumentFactory

registerColumnMapper

registerColumnMapper

registerContainerFactory

registerMapper

registerMapper

release

rollback

rollback

select

setSQLLog

setSqlObjectContext

setStatementBuilder

setStatementLocator

setStatementRewriter

setTimingCollector

setTransactionIsolation

setTransactionIsolation

update

useTransaction

useTransaction