org.apache.commons.dbutils
Class QueryRunner

java.lang.Object
  extended byorg.apache.commons.dbutils.QueryRunner

public class QueryRunner
extends java.lang.Object

Executes SQL queries with pluggable strategies for handling ResultSets. This class is thread safe.

Author:
Henri Yandell, Juozas Baliuka, Steven Caswell, David Graham
See Also:
ResultSetHandler

Field Summary
protected  javax.sql.DataSource ds
          The DataSource to retrieve connections from.
 
Constructor Summary
QueryRunner()
          Constructor for QueryRunner.
QueryRunner(javax.sql.DataSource ds)
          Constructor for QueryRunner.
 
Method Summary
protected  void fillStatement(java.sql.PreparedStatement stmt, java.lang.Object[] params)
          Fill the PreparedStatement replacement parameters with the given objects.
 javax.sql.DataSource getDataSource()
          Returns the DataSource this runner is using.
protected  java.sql.PreparedStatement prepareStatement(java.sql.Connection conn, java.lang.String sql)
          Factory method that creates and initializes a PreparedStatement object for the given SQL.
 java.lang.Object query(java.sql.Connection conn, java.lang.String sql, java.lang.Object[] params, ResultSetHandler rsh)
          Execute an SQL SELECT query with replacement parameters.
 java.lang.Object query(java.sql.Connection conn, java.lang.String sql, java.lang.Object param, ResultSetHandler rsh)
          Execute an SQL SELECT query with a single replacement parameter.
 java.lang.Object query(java.sql.Connection conn, java.lang.String sql, ResultSetHandler rsh)
          Execute an SQL SELECT query without any replacement parameters.
 java.lang.Object query(java.lang.String sql, java.lang.Object[] params, ResultSetHandler rsh)
          Executes the given SELECT SQL query and returns a result object.
 java.lang.Object query(java.lang.String sql, java.lang.Object param, ResultSetHandler rsh)
          Executes the given SELECT SQL with a single replacement parameter.
 java.lang.Object query(java.lang.String sql, ResultSetHandler rsh)
          Executes the given SELECT SQL without any replacement parameters.
protected  void rethrow(java.sql.SQLException cause, java.lang.String sql, java.lang.Object[] params)
          Throws a new exception with a more informative error message.
 void setDataSource(javax.sql.DataSource dataSource)
          Sets the DataSource this runner will use to get database connections from.
 int update(java.sql.Connection conn, java.lang.String sql)
          Execute an SQL INSERT, UPDATE, or DELETE query without replacement parameters.
 int update(java.sql.Connection conn, java.lang.String sql, java.lang.Object param)
          Execute an SQL INSERT, UPDATE, or DELETE query with a single replacement parameter.
 int update(java.sql.Connection conn, java.lang.String sql, java.lang.Object[] params)
          Execute an SQL INSERT, UPDATE, or DELETE query.
 int update(java.lang.String sql)
          Executes the given INSERT, UPDATE, or DELETE SQL statement without any replacement parameters.
 int update(java.lang.String sql, java.lang.Object param)
          Executes the given INSERT, UPDATE, or DELETE SQL statement with a single replacement parameter.
 int update(java.lang.String sql, java.lang.Object[] params)
          Executes the given INSERT, UPDATE, or DELETE SQL statement.
protected  java.sql.ResultSet wrap(java.sql.ResultSet rs)
          Wrap the ResultSet in a decorator before processing it.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ds

protected javax.sql.DataSource ds
The DataSource to retrieve connections from.

Constructor Detail

QueryRunner

public QueryRunner()
Constructor for QueryRunner.


QueryRunner

public QueryRunner(javax.sql.DataSource ds)
Constructor for QueryRunner. Methods that do not take a Connection parameter will retrieve connections from this DataSource.

Parameters:
ds - The DataSource to retrieve connections from.
Method Detail

fillStatement

protected void fillStatement(java.sql.PreparedStatement stmt,
                             java.lang.Object[] params)
                      throws java.sql.SQLException
Fill the PreparedStatement replacement parameters with the given objects.

Parameters:
stmt -
params - Query replacement parameters; null is a valid value to pass in.
Throws:
java.sql.SQLException

getDataSource

public javax.sql.DataSource getDataSource()
Returns the DataSource this runner is using.


prepareStatement

protected java.sql.PreparedStatement prepareStatement(java.sql.Connection conn,
                                                      java.lang.String sql)
                                               throws java.sql.SQLException
Factory method that creates and initializes a PreparedStatement object for the given SQL. QueryRunner methods always call this method to prepare statements for them. Subclasses can override this method to provide special PreparedStatement configuration if needed. This implementation simply calls conn.prepareStatement(sql).

Parameters:
conn - The Connection used to create the PreparedStatement
sql - The SQL statement to prepare.
Returns:
An initialized PreparedStatement.
Throws:
java.sql.SQLException

query

public java.lang.Object query(java.sql.Connection conn,
                              java.lang.String sql,
                              java.lang.Object param,
                              ResultSetHandler rsh)
                       throws java.sql.SQLException
Execute an SQL SELECT query with a single replacement parameter. The caller is responsible for connection cleanup.

Parameters:
conn - The connection to execute the query in.
sql - The query to execute.
param - The replacement parameter.
rsh - The handler that converts the results into an object.
Returns:
The object returned by the handler.
Throws:
java.sql.SQLException

query

public java.lang.Object query(java.sql.Connection conn,
                              java.lang.String sql,
                              java.lang.Object[] params,
                              ResultSetHandler rsh)
                       throws java.sql.SQLException
Execute an SQL SELECT query with replacement parameters. The caller is responsible for connection cleanup.

Parameters:
conn - The connection to execute the query in.
sql - The query to execute.
params - The replacement parameters.
rsh - The handler that converts the results into an object.
Returns:
The object returned by the handler.
Throws:
java.sql.SQLException

query

public java.lang.Object query(java.sql.Connection conn,
                              java.lang.String sql,
                              ResultSetHandler rsh)
                       throws java.sql.SQLException
Execute an SQL SELECT query without any replacement parameters. The caller is responsible for connection cleanup.

Parameters:
conn - The connection to execute the query in.
sql - The query to execute.
rsh - The handler that converts the results into an object.
Returns:
The object returned by the handler.
Throws:
java.sql.SQLException

query

public java.lang.Object query(java.lang.String sql,
                              java.lang.Object param,
                              ResultSetHandler rsh)
                       throws java.sql.SQLException
Executes the given SELECT SQL with a single replacement parameter. The Connection is retrieved from the DataSource set in the constructor.

Parameters:
sql - The SQL statement to execute.
param - The replacement parameter.
rsh - The handler used to create the result object from the ResultSet.
Returns:
An object generated by the handler.
Throws:
java.sql.SQLException

query

public java.lang.Object query(java.lang.String sql,
                              java.lang.Object[] params,
                              ResultSetHandler rsh)
                       throws java.sql.SQLException
Executes the given SELECT SQL query and returns a result object. The Connection is retrieved from the DataSource set in the constructor.

Parameters:
sql - The SQL statement to execute.
params - Initialize the PreparedStatement's IN parameters with this array.
rsh - The handler used to create the result object from the ResultSet.
Returns:
An object generated by the handler.
Throws:
java.sql.SQLException

query

public java.lang.Object query(java.lang.String sql,
                              ResultSetHandler rsh)
                       throws java.sql.SQLException
Executes the given SELECT SQL without any replacement parameters. The Connection is retrieved from the DataSource set in the constructor.

Parameters:
sql - The SQL statement to execute.
rsh - The handler used to create the result object from the ResultSet.
Returns:
An object generated by the handler.
Throws:
java.sql.SQLException

rethrow

protected void rethrow(java.sql.SQLException cause,
                       java.lang.String sql,
                       java.lang.Object[] params)
                throws java.sql.SQLException
Throws a new exception with a more informative error message.

Parameters:
cause - The original exception that will be chained to the new exception when it's rethrown.
sql - The query that was executing when the exception happened.
params - The query replacement paramaters; null is a valid value to pass in.
Throws:
java.sql.SQLException

setDataSource

public void setDataSource(javax.sql.DataSource dataSource)
Sets the DataSource this runner will use to get database connections from. This should be called after creating a runner with the default constructor if you intend to use the execute methods without passing in a Connection.

Parameters:
dataSource - The DataSource to use.

update

public int update(java.sql.Connection conn,
                  java.lang.String sql)
           throws java.sql.SQLException
Execute an SQL INSERT, UPDATE, or DELETE query without replacement parameters.

Parameters:
conn - The connection to use to run the query.
sql - The SQL to execute.
Returns:
The number of rows updated.
Throws:
java.sql.SQLException

update

public int update(java.sql.Connection conn,
                  java.lang.String sql,
                  java.lang.Object param)
           throws java.sql.SQLException
Execute an SQL INSERT, UPDATE, or DELETE query with a single replacement parameter.

Parameters:
conn - The connection to use to run the query.
sql - The SQL to execute.
param - The replacement parameter.
Returns:
The number of rows updated.
Throws:
java.sql.SQLException

update

public int update(java.sql.Connection conn,
                  java.lang.String sql,
                  java.lang.Object[] params)
           throws java.sql.SQLException
Execute an SQL INSERT, UPDATE, or DELETE query.

Parameters:
conn - The connection to use to run the query.
sql - The SQL to execute.
params - The query replacement parameters.
Returns:
The number of rows updated.
Throws:
java.sql.SQLException

update

public int update(java.lang.String sql)
           throws java.sql.SQLException
Executes the given INSERT, UPDATE, or DELETE SQL statement without any replacement parameters. The Connection is retrieved from the DataSource set in the constructor.

Parameters:
sql - The SQL statement to execute.
Returns:
The number of rows updated.
Throws:
java.sql.SQLException

update

public int update(java.lang.String sql,
                  java.lang.Object param)
           throws java.sql.SQLException
Executes the given INSERT, UPDATE, or DELETE SQL statement with a single replacement parameter. The Connection is retrieved from the DataSource set in the constructor.

Parameters:
sql - The SQL statement to execute.
param - The replacement parameter.
Returns:
The number of rows updated.
Throws:
java.sql.SQLException

update

public int update(java.lang.String sql,
                  java.lang.Object[] params)
           throws java.sql.SQLException
Executes the given INSERT, UPDATE, or DELETE SQL statement. The Connection is retrieved from the DataSource set in the constructor.

Parameters:
sql - The SQL statement to execute.
params - Initializes the PreparedStatement's IN (i.e. '?') parameters.
Returns:
The number of rows updated.
Throws:
java.sql.SQLException

wrap

protected java.sql.ResultSet wrap(java.sql.ResultSet rs)
Wrap the ResultSet in a decorator before processing it. This implementation returns the ResultSet it is given without any decoration.

Often, the implementation of this method can be done in an anonymous inner class like this:

 
 QueryRunner run = new QueryRunner() {
     protected ResultSet wrap(ResultSet rs) {
         return StringTrimmedResultSet.wrap(rs);
     }
 };
 

Parameters:
rs - The ResultSet to decorate; never null.
Returns:
The ResultSet wrapped in some decorator.