org.skife.jdbi
Class DBI

java.lang.Object
  org.skife.jdbi.DBI

All Implemented Interfaces:

IDBI

public class DBI

extends java.lang.Object

implements IDBI

Entry point for operations. May act as a configured bean, or provide handles via static functions.

Constructor Summary

DBI()
Attempt to auto-configure a DBi instance

DBI(ConnectionFactory factory)
Use a custom implementation of ConnectionFactory to obtain JDBC connections for handles created by this DBI

DBI(javax.sql.DataSource source)
Obtain a new DBI instance

DBI(javax.sql.DataSource source, java.lang.String name, java.lang.String pass)
Obtain a new DBI instance

DBI(java.lang.String wombat)
If wombat begins "jdbc:" the string will be treated as a jdbc driver otherwise it will be used as the key for a jndi lookup to findInternal a DataSrouce.

DBI(java.lang.String wombat, java.lang.String name, java.lang.String pass)
If wombat begins "jdbc:" the string will be treated as a jdbc driver otherwise it will be used as the key for a jndi lookup to findInternal a DataSrouce.

Method Summary

java.util.Map	getNamedStatements() Obtain an unmodifiable map of all the named statements known to this DBI instance.
void	load(java.lang.String name) Eagerly load a named query from the filesystem.
void	name(java.lang.String name, java.lang.String statement) Prepared a named sql statement
Handle	open() Obtain a new Handle instance
static Handle	open(javax.sql.DataSource source)
static void	open(javax.sql.DataSource source, HandleCallback callback) Execute callback with an opened handle, closing the handle, and cleaning up resources when the callback finishes.
static Handle	open(javax.sql.DataSource source, java.lang.String name, java.lang.String pass) Obtain a handle directly from a datasource
static void	open(javax.sql.DataSource source, java.lang.String name, java.lang.String pass, HandleCallback callback) Execute callback with an opened handle, closing the handle, and cleaning up resources when the callback finishes.
void	open(HandleCallback callback) Execute the callback with an open handle, closing, and cleaning up resources, after the callback exits or excepts
static Handle	open(java.lang.String connString) Obtain a handle directly from a datasource
static void	open(java.lang.String connString, HandleCallback callback) Execute callback with an opened handle, closing the handle, and cleaning up resources when the callback finishes.
static Handle	open(java.lang.String wombat, java.lang.String name, java.lang.String pass) Obtain a handle directly from a datasource
static void	open(java.lang.String wombat, java.lang.String name, java.lang.String pass, HandleCallback callback) Execute callback with an opened handle, closing the handle, and cleaning up resources when the callback finishes.
void	setHandleDecoratorBuilder(HandleDecoratorBuilder builder) Specify a decorator builder to decorate all handles created by this DBI instance

Methods inherited from class java.lang.Object

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

Constructor Detail

DBI

public DBI()
    throws java.io.IOException

Attempt to auto-configure a DBi instance

It first looks for an org.skife.jdbi.properties-file system property which represents a properties file to be loaded via the classpath. If that is not found, it looks for jdbi.properties, then jdbc.properties, then dbi.properties, then finally database.properties on the classpath. It will use the first it finds and stop looking for others once it finds one.

Once a suitable configuration properties file has been loaded, jDBI will look for various properties used to configure it. There are multiple possible values for each logical property, and the order of preference if it should find multiple is the order listed here:

jdbi.url jdbc.url connection.string	JDBC Connection URL, ie jdbc:derby:my_database, required
jdbi.driver jdbc.driver driver drive	JDBC Driver class name, ie org.apache.derby.jdbc.EmbeddedDriver, required
jdbi.username jdbi.user jdbc.username jdbc.user username user	Username to be used when obtaining connections from the database, optional
jdbi.password jdbi.pass jdbc.password jdbc.pass password pass	Password to be used when obtaining connections from the database, optional
jdbi.handle-decorator-builder jdbi.handle-decorator-builder handle-decorator-builder	Unstable Feature class name of a HandleDecoratorBuilder to be used to decorate Handle instances obtained from the DBI instance instantiated. This feature is functionally stable, but the specific api may change somewhat while it remains offically unstable. Please read the notes regarding the org.skife.jdbi.unstable package before using this. Optional.

Throws:

java.io.IOException - on error loading jdbi.properties

DBIError - if the properties file exists but is invalid

DBI

public DBI(java.lang.String wombat)

If wombat begins "jdbc:" the string will be treated as a jdbc driver otherwise it will be used as the key for a jndi lookup to findInternal a DataSrouce. If neither works, will throw a DBIError

Parameters:

wombat - jdbc connection string or jndi lookup

Throws:

DBIError - if anything untoward happens.

DBI

public DBI(java.lang.String wombat,
           java.lang.String name,
           java.lang.String pass)

If wombat begins "jdbc:" the string will be treated as a jdbc driver otherwise it will be used as the key for a jndi lookup to findInternal a DataSrouce. If neither works, will throw a DBIError

Parameters:

wombat - jdbc connection string or jndi lookup

name - username for grabbing connections

pass - password for grabbing connections

Throws:

DBIError - if anything untoward happens.

DBI

public DBI(javax.sql.DataSource source)

Obtain a new DBI instance

Parameters:

source - DataSource provided by client

DBI

public DBI(javax.sql.DataSource source,
           java.lang.String name,
           java.lang.String pass)

Obtain a new DBI instance

Parameters:

source - DataSource provided by client

name - jdbc username

pass - jdbc user password

DBI

public DBI(ConnectionFactory factory)

Use a custom implementation of ConnectionFactory to obtain JDBC connections for handles created by this DBI

Method Detail

open

public Handle open()
            throws DBIException

Obtain a new Handle instance

Specified by:

open in interface IDBI

Returns:

an open Handle

Throws:

DBIException

open

public void open(HandleCallback callback)
          throws DBIException

Execute the callback with an open handle, closing, and cleaning up resources, after the callback exits or excepts

Specified by:

open in interface IDBI

Throws:

DBIException - if exception is thrown from the callback, or an exception occurs with the database

DBIError - if an Error is thrown from the callback

getNamedStatements

public java.util.Map getNamedStatements()

Obtain an unmodifiable map of all the named statements known to this DBI instance.

Specified by:

getNamedStatements in interface IDBI

name

public void name(java.lang.String name,
                 java.lang.String statement)
          throws DBIException

Prepared a named sql statement

Specified by:

name in interface IDBI

Parameters:

name - name to issue query under

statement - sql string to use as query

Throws:

DBIException - if there is a problem preparing the statement

load

public void load(java.lang.String name)
          throws DBIException,
                 java.io.IOException

Eagerly load a named query from the filesystem. The name will be name and it will look for a file named [name].sql in the classpath which contains a single sql statement.

Specified by:

load in interface IDBI

Parameters:

name - name of query to load, such as "foo" which will be store din foo.sql

Throws:

java.io.IOException

DBIException

setHandleDecoratorBuilder

public void setHandleDecoratorBuilder(HandleDecoratorBuilder builder)

Specify a decorator builder to decorate all handles created by this DBI instance

open

public static Handle open(java.lang.String connString)
                   throws DBIException

Obtain a handle directly from a datasource

Throws:

DBIException

open

public static Handle open(java.lang.String wombat,
                          java.lang.String name,
                          java.lang.String pass)
                   throws DBIException

Obtain a handle directly from a datasource

Throws:

DBIException

open

public static Handle open(javax.sql.DataSource source)
                   throws DBIException

Throws:

DBIException

open

public static Handle open(javax.sql.DataSource source,
                          java.lang.String name,
                          java.lang.String pass)
                   throws DBIException

Obtain a handle directly from a datasource

Throws:

DBIException

open

public static void open(java.lang.String connString,
                        HandleCallback callback)
                 throws DBIException

Execute callback with an opened handle, closing the handle, and cleaning up resources when the callback finishes.

Throws:

DBIException

open

public static void open(java.lang.String wombat,
                        java.lang.String name,
                        java.lang.String pass,
                        HandleCallback callback)
                 throws DBIException

Execute callback with an opened handle, closing the handle, and cleaning up resources when the callback finishes.

Throws:

DBIException

open

public static void open(javax.sql.DataSource source,
                        HandleCallback callback)
                 throws DBIException

Execute callback with an opened handle, closing the handle, and cleaning up resources when the callback finishes.

Throws:

DBIException

open

public static void open(javax.sql.DataSource source,
                        java.lang.String name,
                        java.lang.String pass,
                        HandleCallback callback)
                 throws DBIException

Execute callback with an opened handle, closing the handle, and cleaning up resources when the callback finishes.

Throws:

DBIException