org.skife.jdbi.v2

Class DBI

java.lang.Object

org.skife.jdbi.v2.DBI

All Implemented Interfaces:

IDBI

public class DBI
extends Object
implements IDBI

This class provides the access point for jDBI. Use it to obtain Handle instances and provide "global" configuration for all handles obtained from it.

Constructor Summary

Constructors

Constructor and Description
DBI(ConnectionFactory connectionFactory) Constructor used to allow for obtaining a Connection in a customized manner.
DBI(DataSource dataSource) Constructor for use with a DataSource which will provide
DBI(String url) Create a DBI which directly uses the DriverManager
DBI(String url, Properties props) Create a DBI which directly uses the DriverManager
DBI(String url, String username, String password) Create a DBI which directly uses the DriverManager

Method Summary

Modifier and Type	Method and Description
void	close(Object sqlObject) Used to close a sql object which lacks a close() method.
void	define(String key, Object value) Define an attribute on every StatementContext for every statement created from a handle obtained from this DBI instance.
SQLLog	getSQLLog()
StatementBuilderFactory	getStatementBuilderFactory()
StatementLocator	getStatementLocator()
StatementRewriter	getStatementRewriter()
TimingCollector	getTimingCollector()
TransactionHandler	getTransactionHandler()
<ReturnType> ReturnType	inTransaction(TransactionCallback<ReturnType> callback) A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.
<ReturnType> ReturnType	inTransaction(TransactionIsolationLevel isolation, TransactionCallback<ReturnType> callback) A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.
<SqlObjectType> SqlObjectType	onDemand(Class<SqlObjectType> sqlObjectType) Create a new sql object which will obtain and release connections from this dbi instance, as it needs to, and can, respectively.
Handle	open() Obtain a Handle to the data source wrapped by this DBI instance
<SqlObjectType> SqlObjectType	open(Class<SqlObjectType> sqlObjectType) Open a handle and attach a new sql object of the specified type to that handle.
static Handle	open(Connection connection) Create a Handle wrapping a particular JDBC Connection
static Handle	open(DataSource dataSource) Convenience methd used to obtain a handle from a specific data source
static Handle	open(String url) Obtain a handle with just a JDBC URL
static Handle	open(String url, Properties props) Obtain a handle with just a JDBC URL
static Handle	open(String url, String username, String password) Obtain a handle with just a JDBC URL
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.
void	setSQLLog(SQLLog log) Specify the class used to log sql statements.
void	setStatementBuilderFactory(StatementBuilderFactory factory) Allows customization of how prepared statements are created.
void	setStatementLocator(StatementLocator locator) Use a non-standard StatementLocator to look up named statements for all handles created from this DBi instance.
void	setStatementRewriter(StatementRewriter rewriter) Use a non-standard StatementRewriter to transform SQL for all Handle instances created by this DBI.
void	setTimingCollector(TimingCollector timingCollector) Add a callback to accumulate timing information about the queries running from this data source.
void	setTransactionHandler(TransactionHandler handler) Specify the TransactionHandler instance to use.
void	useHandle(HandleConsumer callback) A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.
void	useTransaction(TransactionConsumer callback) A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.
void	useTransaction(TransactionIsolationLevel isolation, TransactionConsumer callback) A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.
<ReturnType> ReturnType	withHandle(HandleCallback<ReturnType> callback) A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.

Methods inherited from class java.lang.Object

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

Constructor Detail

DBI

public DBI(ConnectionFactory connectionFactory)

Constructor used to allow for obtaining a Connection in a customized manner.

The ConnectionFactory.openConnection() method will be invoked to obtain a connection instance whenever a Handle is opened.

Parameters:

connectionFactory - PrvidesJDBC connections to Handle instances

DBI

public DBI(DataSource dataSource)

Constructor for use with a DataSource which will provide

Parameters:

dataSource -

DBI

public DBI(String url)

Create a DBI which directly uses the DriverManager

Parameters:

url - JDBC URL for connections

DBI

public DBI(String url,
           Properties props)

Create a DBI which directly uses the DriverManager

Parameters:

url - JDBC URL for connections

props - Properties to pass to DriverManager.getConnection(url, props) for each new handle

DBI

public DBI(String url,
           String username,
           String password)

Create a DBI which directly uses the DriverManager

Parameters:

url - JDBC URL for connections

username - User name for connection authentication

password - Password for connection authentication

Method Detail

close

public void close(Object sqlObject)

Used to close a sql object which lacks a close() method.

Specified by:

close in interface IDBI

Parameters:

sqlObject - the sql object to close

define

public void define(String key,
                   Object value)

Define an attribute on every StatementContext for every statement created from a handle obtained from this DBI instance.

Specified by:

define in interface IDBI

Parameters:

key - The key for the attribute

value - the value for the attribute

getSQLLog

public SQLLog getSQLLog()

getStatementBuilderFactory

public StatementBuilderFactory getStatementBuilderFactory()

getStatementLocator

public StatementLocator getStatementLocator()

getStatementRewriter

public StatementRewriter getStatementRewriter()

getTimingCollector

public TimingCollector getTimingCollector()

getTransactionHandler

public TransactionHandler getTransactionHandler()

inTransaction

public <ReturnType> ReturnType inTransaction(TransactionCallback<ReturnType> callback)
                                      throws CallbackFailedException

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients. The handle will be in a transaction when the callback is invoked, and that transaction will be committed if the callback finishes normally, or rolled back if the callback raises an exception.

Specified by:

inTransaction in interface IDBI

Parameters:

callback - A callback which will receive an open Handle, in a transaction

Returns:

the value returned by callback

Throws:

CallbackFailedException - Will be thrown if callback raises an exception. This exception will wrap the exception thrown by the callback.

inTransaction

public <ReturnType> ReturnType inTransaction(TransactionIsolationLevel isolation,
                                             TransactionCallback<ReturnType> callback)
                                      throws CallbackFailedException

Description copied from interface: IDBI

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients. The handle will be in a transaction when the callback is invoked, and that transaction will be committed if the callback finishes normally, or rolled back if the callback raises an exception.

Specified by:

inTransaction in interface IDBI

Parameters:

isolation - The transaction isolation level to set

callback - A callback which will receive an open Handle, in a transaction

Returns:

the value returned by callback

Throws:

CallbackFailedException - Will be thrown if callback raises an exception. This exception will wrap the exception thrown by the callback.

onDemand

public <SqlObjectType> SqlObjectType onDemand(Class<SqlObjectType> sqlObjectType)

Create a new sql object which will obtain and release connections from this dbi instance, as it needs to, and can, respectively. You should not explicitly close this sql object

Specified by:

onDemand in interface IDBI

Type Parameters:

SqlObjectType -

Parameters:

sqlObjectType - an interface with annotations declaring desired behavior

Returns:

a new sql object of the specified type, with a dedicated handle

open

public Handle open()

Obtain a Handle to the data source wrapped by this DBI instance

Specified by:

open in interface IDBI

Returns:

an open Handle instance

See Also:

open()

open

public <SqlObjectType> SqlObjectType open(Class<SqlObjectType> sqlObjectType)

Open a handle and attach a new sql object of the specified type to that handle. Be sure to close the sql object (via a close() method, or calling IDBI.close(Object)

Specified by:

open in interface IDBI

Type Parameters:

SqlObjectType -

Parameters:

sqlObjectType - an interface with annotations declaring desired behavior

Returns:

a new sql object of the specified type, with a dedicated handle

open

public static Handle open(Connection connection)

Create a Handle wrapping a particular JDBC Connection

Parameters:

connection -

Returns:

Handle bound to connection

open

public static Handle open(DataSource dataSource)

Convenience methd used to obtain a handle from a specific data source

Parameters:

dataSource -

Returns:

Handle using a Connection obtained from the provided DataSource

open

public static Handle open(String url)

Obtain a handle with just a JDBC URL

Parameters:

url - JDBC Url

Returns:

newly opened Handle

open

public static Handle open(String url,
                          Properties props)

Obtain a handle with just a JDBC URL

Parameters:

url - JDBC Url

props - JDBC properties

Returns:

newly opened Handle

open

public static Handle open(String url,
                          String username,
                          String password)

Obtain a handle with just a JDBC URL

Parameters:

url - JDBC Url

username - JDBC username for authentication

password - JDBC password for authentication

Returns:

newly opened Handle

registerArgumentFactory

public void registerArgumentFactory(ArgumentFactory<?> argumentFactory)

registerColumnMapper

public 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

public void registerColumnMapper(ResultColumnMapperFactory factory)

Register a result column mapper factory. Column mappers may be reused by ResultSetMapper to map individual columns.

registerContainerFactory

public void registerContainerFactory(ContainerFactory<?> factory)

registerMapper

public 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

public void registerMapper(ResultSetMapperFactory factory)

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

setSQLLog

public void setSQLLog(SQLLog log)

Specify the class used to log sql statements. Will be passed to all handles created from this instance

setStatementBuilderFactory

public void setStatementBuilderFactory(StatementBuilderFactory factory)

Allows customization of how prepared statements are created. When a Handle is created against this DBI instance the factory will be used to create a StatementBuilder for that specific handle. When the handle is closed, the StatementBuilder's close method will be invoked.

setStatementLocator

public void setStatementLocator(StatementLocator locator)

Use a non-standard StatementLocator to look up named statements for all handles created from this DBi instance.

Parameters:

locator - StatementLocator which will be used by all Handle instances created from this DBI

setStatementRewriter

public void setStatementRewriter(StatementRewriter rewriter)

Use a non-standard StatementRewriter to transform SQL for all Handle instances created by this DBI.

Parameters:

rewriter - StatementRewriter to use on all Handle instances

setTimingCollector

public void setTimingCollector(TimingCollector timingCollector)

Add a callback to accumulate timing information about the queries running from this data source.

setTransactionHandler

public void setTransactionHandler(TransactionHandler handler)

Specify the TransactionHandler instance to use. This allows overriding transaction semantics, or mapping into different transaction management systems.

The default version uses local transactions on the database Connection instances obtained.

Parameters:

handler - The TransactionHandler to use for all Handle instances obtained from this DBI

useHandle

public void useHandle(HandleConsumer callback)
               throws CallbackFailedException

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.

Specified by:

useHandle in interface IDBI

Parameters:

callback - A callback which will receive an open Handle

Throws:

CallbackFailedException - Will be thrown if callback raises an exception. This exception will wrap the exception thrown by the callback.

useTransaction

public void useTransaction(TransactionConsumer callback)
                    throws CallbackFailedException

Description copied from interface: IDBI

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients. The handle will be in a transaction when the callback is invoked, and that transaction will be committed if the callback finishes normally, or rolled back if the callback raises an exception.

Specified by:

useTransaction in interface IDBI

Parameters:

callback - A callback which will receive an open Handle, in a transaction

Throws:

CallbackFailedException - Will be thrown if callback raises an exception. This exception will wrap the exception thrown by the callback.

useTransaction

public void useTransaction(TransactionIsolationLevel isolation,
                           TransactionConsumer callback)
                    throws CallbackFailedException

Description copied from interface: IDBI

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients. The handle will be in a transaction when the callback is invoked, and that transaction will be committed if the callback finishes normally, or rolled back if the callback raises an exception.

Specified by:

useTransaction in interface IDBI

Parameters:

isolation - The transaction isolation level to set

callback - A callback which will receive an open Handle, in a transaction

Throws:

CallbackFailedException - Will be thrown if callback raises an exception. This exception will wrap the exception thrown by the callback.

withHandle

public <ReturnType> ReturnType withHandle(HandleCallback<ReturnType> callback)
                                   throws CallbackFailedException

A convenience function which manages the lifecycle of a handle and yields it to a callback for use by clients.

Specified by:

withHandle in interface IDBI

Parameters:

callback - A callback which will receive an open Handle

Returns:

the value returned by callback

Throws:

CallbackFailedException - Will be thrown if callback raises an exception. This exception will wrap the exception thrown by the callback.