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.
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.
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.
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.
JDBI uses the Apache APR versioning guidelines.
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!