Package org.skife.jdbi.v2

Start with DBI and Handle

See:
Description

Interface Summary

CallableStatementMapper
Folder2<AccumulatorType>
Handle	This represents a connection to the database system.
IDBI	An interface for DBI instances for systems which like to work with interfaces.
ResultIterator<Type>	Represents a forward-only iterator over a result set, which will lazily iterate the results.
ResultSetMapperFactory	Factory interface used to produce result set mappers.
StatementContext	The statement context provides a means for passing client specific information through the evaluation of a statement.
TimingCollector	This class collects timing information for every database operation.
Transaction<ReturnType,ConnectionType>
TransactionCallback<ReturnType>	Used as a callback which guarantees that the inTransaction method is invoked in a transaction, and will be committed or rolled back as specified.
TransactionStatus	Allows rolling back a transaction in a TransactionCallback

Class Summary

BaseResultSetMapper<ResultType>	Convenience class which allows definition of result set mappers which getAttribute the row as a map instead of a result set.
Batch	Represents a group of non-prepared statements to be sent to the RDMBS in one "request"
BeanMapper<T>	A result set mapper which maps the fields in a statement into a JavaBean.
Binding	Represents the arguments bound to a particular statement
CachingStatementBuilder	A StatementBuilder which decorates another StatementBuilder and caches
CachingStatementBuilderFactory	The default StatementBuilderFactory.
Call	Used for invoking stored procedures.
ClasspathStatementLocator	looks for [name], then [name].sql on the classpath
ColonPrefixNamedParamStatementRewriter	Statement rewriter which replaces named parameter tokens of the form :tokenName This is the default statement rewriter
ConcreteStatementContext
DBI	This class provides the access point for jDBI.
DefaultMapper
DefaultStatementBuilder	A StatementBuilder which will always create a new PreparedStatement
DefaultStatementBuilderFactory
GeneratedKeys<Type>	Wrapper object for generated keys as returned by the Statement.getGeneratedKeys()
HashPrefixStatementRewriter	Statement rewriter which replaces named parameter tokens of the form #tokenName
NoOpStatementRewriter	A statement rewriter which does not, in fact, rewrite anything.
OutParameters	Represents output from a Call (CallableStatement)
PreparedBatch	Represents a prepared batch statement.
PreparedBatchPart	Represents a single statement in a prepared batch
Query<ResultType>	Statement prviding convenience result handling for SQL queries.
Script	Represents a number of SQL statements which will be executed in a batch statement.
SQLStatement<SelfType extends SQLStatement<SelfType>>	This class provides the common functions between Query and Update.
TimingCollector.NopTimingCollector
Update	Used for INSERT, UPDATE, and DELETE statements

Enum Summary

TransactionIsolationLevel

Package org.skife.jdbi.v2 Description

Start with DBI and Handle

The main entry point to functionailty is the DBI class. This class provides access to Handle instances, which are the primary means of interacting with database connections.

The Handle is, generally, used to wrap a JDBC Connection instance. This connection will be used for all database operations by the handle, and will be closed when the handle is closed.

Idioms and Practices

JDBI tries to use common Java practices, and standard interfaces as much as possible. This means that results are returned as java.util.List and java.util.Iterator instances, that working with JavaBeans (tm) is favored, etc.

Named Parameters

You can use named parameters in SQL executed through JDBI. That means that statements such as select id, name from profiles where age > :age is valid. When executed it will be transformed to the traditional form, select id, name from profiles where age > ?. When binding arguments to a statement you may bind them either positionally or via the name, age in the example here. You may also mix positional and named argument binding and it should do the right thing.

Externalized SQL

JDBI supports externalizing SQL via named queries. The default named query resolver looks for files on the classpath. The exact lookup rules for this locator can be found on the javadocs for ClasspathStatementLocator, but the gist is that you can do things like handle.createQuery("queries/profile-by-id"); to fetch the SQL from the file queries/profile-by-id.sql. The locator can be replaced to find named statements by other means, and can be cached if desired.

Version Numbering

JDBI uses the Apache APR versioning guidelines.

Caveats and Random Bits

Most SQL in JDBI uses prepared statements. Non-prepared batch operations and scripts are the only places where regular statements are used. Prepared Statements are cached for the duration of an open handle, and will be reused on that handle. They are not cached on the Connection, but rather on the actual Handle, so if connection pooling is in use and you want to cache prepared statements between handle instances on the same connection you should do this at the data source level.

The unit system tests are most often run against Apache Derby. If you encounter any issue against a different database, please consider running the tests against that database. Please contact the dev mailing list about these, or for help running the tests in a given environment. Thank you!

Design Principles

1. Do the right thing for clients
2. Do the right thing for extenders
3. No configuration required
4. Optimize the common cases