org.skife.jdbi
Interface Handle

All Known Implementing Classes:
BaseHandleDecorator

public interface Handle

Represents a connection to the RDBMS.


Method Summary
 Batch batch()
          Create a new Batch instance which can be used to queue up and execute statements in a single batch.
 void begin()
          start a transaction
 void clearStatementCache()
          Clear this handle's cache of prepared statements.
 void close()
          Close the connection
 void commit()
          Commit transaction in progress
 void execute(java.lang.String statement)
          Execute an sql statement which does not return any results.
 void execute(java.lang.String statement, java.util.Collection args)
          Execute an sql statement which does not return any results.
 void execute(java.lang.String statement, java.util.Map args)
          Execute an sql statement which does not return any results.
 void execute(java.lang.String statement, java.lang.Object bean)
          Execute a statement with named parameters pulling values from a JavaBean
 void execute(java.lang.String statement, java.lang.Object[] args)
          Execute an sql statement which does not return any results.
 java.util.Map first(java.lang.String statement)
          Returns the first row matched by the query
 java.util.Map first(java.lang.String statement, java.util.Collection params)
          Returns the first row matched by the query
 java.util.Map first(java.lang.String statement, java.util.Map args)
          Returns the first row matched by the query
 java.util.Map first(java.lang.String statement, java.lang.Object bean)
          Returns the first row matched by the query
 java.util.Map first(java.lang.String statement, java.lang.Object[] params)
          Returns the first row matched by the query
 java.sql.Connection getConnection()
          Obtain the JDBC connection used by this handle
 java.util.Map getGlobalParameters()
          Obtain a map containing globally set named parameter values.
 void inTransaction(TransactionCallback transactionCallback)
          Execute transactionCallback in a transaction, cleaning up as necesary around it
 boolean isInTransaction()
          Has a transaction been started?
 boolean isOpen()
          Checks to make sure the connection is live
 void load(java.lang.String name)
          Eagerly load a named query from the filesystem.
 void name(java.lang.String name, java.lang.String sql)
          Prepared a named sql statement
 PreparedBatch prepareBatch(java.lang.String statement)
          Create a new PreparedBatch instance from arbitrary SQL or a named statement
 java.util.List query(java.lang.String query)
          Retrieve a collection of map instances from a query.
 java.util.List query(java.lang.String statement, java.util.Collection args)
          Execute statement with positional arguments
 java.util.List query(java.lang.String statement, java.util.Map params)
          Execute query using name parameters of the form: select id, name from something where id = :something and the key to the params map is "something"
 void query(java.lang.String statement, java.util.Map args, RowCallback callback)
          Iterate (once) over a resultset in order calling the callback for each row processed
 java.util.List query(java.lang.String statement, java.lang.Object bean)
          Execute statement with JavaBean mapped named parameter
 java.util.List query(java.lang.String statement, java.lang.Object[] params)
          Execute statement with positional arguments
 void query(java.lang.String statement, java.lang.Object[] args, RowCallback callback)
          Iterate (once) over a resultset in order calling the callback for each row processed
 void query(java.lang.String select, RowCallback callback)
          Iterate (once) over a resultset in order calling the callback for each row processed
 void rollback()
          Rollback a transaction in progress
 void script(java.lang.String name)
          Find and execute the sql script name.
 int update(java.lang.String statement)
          Execute a statement of the form update foo set bar = foo_id
 int update(java.lang.String statement, java.util.Collection args)
          Execute a statement of the form update foo set bar = foo_id
 int update(java.lang.String statement, java.util.Map args)
          Execute a statement of the form update foo set bar = foo_id
 int update(java.lang.String statement, java.lang.Object bean)
          Execute an update with named parameters pulling values from a JavaBean
 int update(java.lang.String statement, java.lang.Object[] args)
          Execute a statement of the form update foo set bar = foo_id
 

Method Detail

getConnection

java.sql.Connection getConnection()
Obtain the JDBC connection used by this handle


close

void close()
Close the connection

Throws:
DBIError - if anything goes really wrong, otherwise just closes

execute

void execute(java.lang.String statement)
             throws DBIException
Execute an sql statement which does not return any results. This can also be used to execute stored procedures ("call foo()")

Parameters:
statement - insert/update/create/delete/call statement
Throws:
DBIException

execute

void execute(java.lang.String statement,
             java.lang.Object[] args)
             throws DBIException
Execute an sql statement which does not return any results. This can also be used to execute stored procedures ("call foo()")

Parameters:
statement - insert/update/create/delete/call statement
args - positional arguments to be bound to statement
Throws:
DBIException

execute

void execute(java.lang.String statement,
             java.util.Collection args)
             throws DBIException
Execute an sql statement which does not return any results. This can also be used to execute stored procedures ("call foo()")

Parameters:
statement - insert/update/create/delete/call statement
args - positional arguments to be bound to statement
Throws:
DBIException

execute

void execute(java.lang.String statement,
             java.util.Map args)
             throws DBIException
Execute an sql statement which does not return any results. This can also be used to execute stored procedures ("call foo()")

Parameters:
statement - insert/update/create/delete/call statement
args - named arguments to be bound to statement
Throws:
DBIException

execute

void execute(java.lang.String statement,
             java.lang.Object bean)
             throws DBIException
Execute a statement with named parameters pulling values from a JavaBean

Parameters:
statement - SQL statement with named parameters
bean - JavaBean with properties to be de-referenced for named parameter substitution
Throws:
DBIException

update

int update(java.lang.String statement)
           throws DBIException
Execute a statement of the form update foo set bar = foo_id

Parameters:
statement - sql statement or named statement
Returns:
number of modified rows
Throws:
DBIException - if anything goes wrong

update

int update(java.lang.String statement,
           java.lang.Object[] args)
           throws DBIException
Execute a statement of the form update foo set bar = foo_id

Parameters:
statement - sql statement or named statement
args - positional args to bind to statement
Returns:
number of modified rows
Throws:
DBIException - if anything goes wrong

update

int update(java.lang.String statement,
           java.util.Collection args)
           throws DBIException
Execute a statement of the form update foo set bar = foo_id

Parameters:
statement - sql statement or named statement
args - positional args to bind to statement
Returns:
number of modified rows
Throws:
DBIException - if anything goes wrong

update

int update(java.lang.String statement,
           java.util.Map args)
           throws DBIException
Execute a statement of the form update foo set bar = foo_id

Parameters:
statement - sql statement or named statement
args - named args to bind to statement
Returns:
number of modified rows
Throws:
DBIException - if anything goes wrong

update

int update(java.lang.String statement,
           java.lang.Object bean)
           throws DBIException
Execute an update with named parameters pulling values from a JavaBean

Parameters:
statement - sql named statement or direct sql
bean - JavaBean whose properties
Returns:
number of rows modified
Throws:
DBIException

query

java.util.List query(java.lang.String query)
                     throws DBIException
Retrieve a collection of map instances from a query. This is an eagerly loaded collection.

Parameters:
query - select statement
Returns:
collection of Map instances
Throws:
DBIException

query

void query(java.lang.String select,
           RowCallback callback)
           throws DBIException
Iterate (once) over a resultset in order calling the callback for each row processed

Parameters:
select - sql select statement
callback - receive callbacks for each row in result
Throws:
DBIException

query

void query(java.lang.String statement,
           java.lang.Object[] args,
           RowCallback callback)
           throws DBIException
Iterate (once) over a resultset in order calling the callback for each row processed

Parameters:
statement - sql select statement
args - position arguments to the statement
callback - receive callbacks for each row in result
Throws:
DBIException

query

void query(java.lang.String statement,
           java.util.Map args,
           RowCallback callback)
           throws DBIException
Iterate (once) over a resultset in order calling the callback for each row processed

Named parameters are matched via \s+(:\w+) outside of quotes, so basically :id, :foo_id, or :id1 type constructions.

Parameters:
statement - sql select statement
args - named arguments to the statement
callback - receive callbacks for each row in result
Throws:
DBIException

query

java.util.List query(java.lang.String statement,
                     java.util.Map params)
                     throws DBIException
Execute query using name parameters of the form: select id, name from something where id = :something and the key to the params map is "something"

Named parameters are matched via \s+(:\w+) outside of quotes, so basically :id, :foo_id, or :id1 type constructions.

Parameters:
statement - sql statement
params - map of named parameters
Returns:
collection of Map instances with results
Throws:
DBIException

query

java.util.List query(java.lang.String statement,
                     java.lang.Object bean)
                     throws DBIException
Execute statement with JavaBean mapped named parameter

Parameters:
statement - sql or named statement with named paramaters
bean - JavaBean whose properties will be used to populate named parameters
Returns:
results
Throws:
DBIException

query

java.util.List query(java.lang.String statement,
                     java.lang.Object[] params)
                     throws DBIException
Execute statement with positional arguments

Parameters:
statement - sql or named statement
params - positional parameters
Returns:
results
Throws:
DBIException

query

java.util.List query(java.lang.String statement,
                     java.util.Collection args)
                     throws DBIException
Execute statement with positional arguments

Parameters:
statement - sql or named statement
args - positional parameters, bound in iteration order
Returns:
results
Throws:
DBIException

first

java.util.Map first(java.lang.String statement)
                    throws DBIException
Returns the first row matched by the query

Parameters:
statement - select statement or named query
Returns:
first row
Throws:
DBIException

first

java.util.Map first(java.lang.String statement,
                    java.lang.Object bean)
                    throws DBIException
Returns the first row matched by the query

Parameters:
statement - select statement or named query
bean - JavaBean whose properties will be used to populate named parameters
Returns:
first row
Throws:
DBIException

first

java.util.Map first(java.lang.String statement,
                    java.util.Map args)
                    throws DBIException
Returns the first row matched by the query

Parameters:
statement - select statement or named query
args - map of named parameters
Returns:
first row
Throws:
DBIException

first

java.util.Map first(java.lang.String statement,
                    java.lang.Object[] params)
                    throws DBIException
Returns the first row matched by the query

Parameters:
statement - select statement or named query
params - positional parameters
Returns:
first row
Throws:
DBIException

first

java.util.Map first(java.lang.String statement,
                    java.util.Collection params)
                    throws DBIException
Returns the first row matched by the query

Parameters:
statement - select statement or named query
params - positional parameters
Returns:
first row
Throws:
DBIException

begin

void begin()
           throws DBIException
start a transaction

Throws:
DBIException

commit

void commit()
            throws DBIException
Commit transaction in progress

Throws:
DBIException

name

void name(java.lang.String name,
          java.lang.String sql)
          throws DBIException
Prepared a named sql statement

Parameters:
name - name to issue query under
sql - sql string to use as query
Throws:
DBIException - if there is a problem preparing the statement

load

void load(java.lang.String name)
          throws java.io.IOException,
                 DBIException
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.

Parameters:
name - name of query to load, such as "foo" which will be store din foo.sql
Throws:
java.io.IOException
DBIException

inTransaction

void inTransaction(TransactionCallback transactionCallback)
                   throws DBIException
Execute transactionCallback in a transaction, cleaning up as necesary around it

Throws:
DBIException

isInTransaction

boolean isInTransaction()
Has a transaction been started?


isOpen

boolean isOpen()
               throws DBIException
Checks to make sure the connection is live

Throws:
DBIException

script

void script(java.lang.String name)
            throws DBIException,
                   java.io.IOException
Find and execute the sql script name. First it will be search for name.sql, or, if that is not found, name will be loaded directly.

Scripts should seperate statements with a semicolon, for example:


 create table wombats (
  wombat_id integer primary key,
  name varchar(50)
 );

 insert into wombats (wombat_id, name) values (1, 'Muggie');

 call wiggles(1, 2, 3);
 

Parameters:
name -
Throws:
DBIException
java.io.IOException

rollback

void rollback()
              throws DBIException
Rollback a transaction in progress

Throws:
DBIException - if the rollback fails

clearStatementCache

void clearStatementCache()
Clear this handle's cache of prepared statements. Will be called automatically prior to closing the handle, or can be cleared manually at any point.


batch

Batch batch()
Create a new Batch instance which can be used to queue up and execute statements in a single batch.


prepareBatch

PreparedBatch prepareBatch(java.lang.String statement)
Create a new PreparedBatch instance from arbitrary SQL or a named statement


getGlobalParameters

java.util.Map getGlobalParameters()
Obtain a map containing globally set named parameter values. All statements with named parameters will be able to make use of the global named params. Parameters passed in will overlay global params.

Handles create a local copy of global parameters specified on the DBI instance used to create the handle. Global parameters added to the Handle will not be added to the DBI instance's globals, however.