Package org.apache.commons.dbutils

# Class QueryRunner

java.lang.Object
org.apache.commons.dbutils.AbstractQueryRunner
org.apache.commons.dbutils.QueryRunner

public class QueryRunner extends AbstractQueryRunner
Executes SQL queries with pluggable strategies for handling `ResultSet`s. This class is thread safe.

See Also:
  - `ResultSetHandler`

- ## Field Summary

  ### Fields inherited from class org.apache.commons.dbutils.AbstractQueryRunner

  `ds`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `QueryRunner()`
  Constructor for QueryRunner.
  `QueryRunner(boolean pmdKnownBroken)`
  Constructor for QueryRunner that controls the use of `ParameterMetaData`.
  `QueryRunner(DataSource ds)`
  Constructor for QueryRunner that takes a `DataSource` to use.
  `QueryRunner(DataSource ds, boolean pmdKnownBroken)`
  Constructor for QueryRunner that takes a `DataSource` and controls the use of `ParameterMetaData`.
  `QueryRunner(DataSource ds, boolean pmdKnownBroken, StatementConfiguration stmtConfig)`
  Constructor for QueryRunner that takes a `DataSource`, a `StatementConfiguration`, and controls the use of `ParameterMetaData`.
  `QueryRunner(DataSource ds, StatementConfiguration stmtConfig)`
  Constructor for QueryRunner that takes a `DataSource` to use and a `StatementConfiguration`.
  `QueryRunner(StatementConfiguration stmtConfig)`
  Constructor for QueryRunner that takes a `StatementConfiguration` to configure statements when preparing them.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int[]`
  `batch(String sql, Object[][] params)`
  Execute a batch of SQL INSERT, UPDATE, or DELETE queries.
  `int[]`
  `batch(Connection conn, String sql, Object[][] params)`
  Execute a batch of SQL INSERT, UPDATE, or DELETE queries.
  `int`
  `execute(String sql, Object... params)`
  Execute an SQL statement, including a stored procedure call, which does not return any result sets.
  `<T> List<T>`
  `execute(String sql, ResultSetHandler<T> rsh, Object... params)`
  Execute an SQL statement, including a stored procedure call, which returns one or more result sets.
  `int`
  `execute(Connection conn, String sql, Object... params)`
  Execute an SQL statement, including a stored procedure call, which does not return any result sets.
  `<T> List<T>`
  `execute(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params)`
  Execute an SQL statement, including a stored procedure call, which returns one or more result sets.
  `<T> T`
  `insert(String sql, ResultSetHandler<T> rsh)`
  Executes the given INSERT SQL without any replacement parameters.
  `<T> T`
  `insert(String sql, ResultSetHandler<T> rsh, Object... params)`
  Executes the given INSERT SQL statement.
  `<T> T`
  `insert(Connection conn, String sql, ResultSetHandler<T> rsh)`
  Execute an SQL INSERT query without replacement parameters.
  `<T> T`
  `insert(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params)`
  Execute an SQL INSERT query.
  `<T> T`
  `insertBatch(String sql, ResultSetHandler<T> rsh, Object[][] params)`
  Executes the given batch of INSERT SQL statements.
  `<T> T`
  `insertBatch(Connection conn, String sql, ResultSetHandler<T> rsh, Object[][] params)`
  Executes the given batch of INSERT SQL statements.
  `<T> T`
  `query(String sql, Object[] params, ResultSetHandler<T> rsh)`
  Deprecated.
  Use `query(String, ResultSetHandler, Object...)`
  `<T> T`
  `query(String sql, Object param, ResultSetHandler<T> rsh)`
  Deprecated.
  Use `query(String, ResultSetHandler, Object...)`
  `<T> T`
  `query(String sql, ResultSetHandler<T> rsh)`
  Executes the given SELECT SQL without any replacement parameters.
  `<T> T`
  `query(String sql, ResultSetHandler<T> rsh, Object... params)`
  Executes the given SELECT SQL query and returns a result object.
  `<T> T`
  `query(Connection conn, String sql, Object[] params, ResultSetHandler<T> rsh)`
  Deprecated.
  Use `query(Connection,String,ResultSetHandler,Object...)` instead
  `<T> T`
  `query(Connection conn, String sql, Object param, ResultSetHandler<T> rsh)`
  Deprecated.
  Use `query(Connection, String, ResultSetHandler, Object...)`
  `<T> T`
  `query(Connection conn, String sql, ResultSetHandler<T> rsh)`
  Execute an SQL SELECT query without any replacement parameters.
  `<T> T`
  `query(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params)`
  Execute an SQL SELECT query with replacement parameters.
  `int`
  `update(String sql)`
  Executes the given INSERT, UPDATE, or DELETE SQL statement without any replacement parameters.
  `int`
  `update(String sql, Object param)`
  Executes the given INSERT, UPDATE, or DELETE SQL statement with a single replacement parameter.
  `int`
  `update(String sql, Object... params)`
  Executes the given INSERT, UPDATE, or DELETE SQL statement.
  `int`
  `update(Connection conn, String sql)`
  Execute an SQL INSERT, UPDATE, or DELETE query without replacement parameters.
  `int`
  `update(Connection conn, String sql, Object param)`
  Execute an SQL INSERT, UPDATE, or DELETE query with a single replacement parameter.
  `int`
  `update(Connection conn, String sql, Object... params)`
  Execute an SQL INSERT, UPDATE, or DELETE query.

  ### Methods inherited from class org.apache.commons.dbutils.AbstractQueryRunner

  `close, close, close, closeQuietly, closeQuietly, closeQuietly, fillStatement, fillStatement, fillStatementWithBean, fillStatementWithBean, getDataSource, getParameterMetaData, isPmdKnownBroken, prepareCall, prepareConnection, prepareStatement, prepareStatement, rethrow, wrap`

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### QueryRunner

    public QueryRunner()
    Constructor for QueryRunner.

  - ### QueryRunner

    public QueryRunner(boolean pmdKnownBroken)
    Constructor for QueryRunner that controls the use of `ParameterMetaData`.
    Parameters:
      `pmdKnownBroken` - Some drivers don't support `ParameterMetaData.getParameterType(int)`; if `pmdKnownBroken` is set to true, we won't even try it; if false, we'll try it, and if it breaks, we'll remember not to use it again.

  - ### QueryRunner

    public QueryRunner(DataSource ds)
    Constructor for QueryRunner that takes a `DataSource` to use. Methods that do not take a `Connection` parameter will retrieve connections from this `DataSource`.
    Parameters:
      `ds` - The `DataSource` to retrieve connections from.

  - ### QueryRunner

    public QueryRunner(DataSource ds, boolean pmdKnownBroken)
    Constructor for QueryRunner that takes a `DataSource` and controls the use of `ParameterMetaData`. Methods that do not take a `Connection` parameter will retrieve connections from this `DataSource`.
    Parameters:
      `ds` - The `DataSource` to retrieve connections from.
      `pmdKnownBroken` - Some drivers don't support `ParameterMetaData.getParameterType(int)`; if `pmdKnownBroken` is set to true, we won't even try it; if false, we'll try it, and if it breaks, we'll remember not to use it again.

  - ### QueryRunner

    public QueryRunner(DataSource ds, boolean pmdKnownBroken, StatementConfiguration stmtConfig)
    Constructor for QueryRunner that takes a `DataSource`, a `StatementConfiguration`, and controls the use of `ParameterMetaData`. Methods that do not take a `Connection` parameter will retrieve connections from this `DataSource`.
    Parameters:
      `ds` - The `DataSource` to retrieve connections from.
      `pmdKnownBroken` - Some drivers don't support `ParameterMetaData.getParameterType(int)`; if `pmdKnownBroken` is set to true, we won't even try it; if false, we'll try it, and if it breaks, we'll remember not to use it again.
      `stmtConfig` - The configuration to apply to statements when they are prepared.

  - ### QueryRunner

    public QueryRunner(DataSource ds, StatementConfiguration stmtConfig)
    Constructor for QueryRunner that takes a `DataSource` to use and a `StatementConfiguration`. Methods that do not take a `Connection` parameter will retrieve connections from this `DataSource`.
    Parameters:
      `ds` - The `DataSource` to retrieve connections from.
      `stmtConfig` - The configuration to apply to statements when they are prepared.

  - ### QueryRunner

    public QueryRunner(StatementConfiguration stmtConfig)
    Constructor for QueryRunner that takes a `StatementConfiguration` to configure statements when preparing them.
    Parameters:
      `stmtConfig` - The configuration to apply to statements when they are prepared.

- ## Method Details

  - ### batch

    public int[] batch(Connection conn, String sql, Object[][] params) throws SQLException
    Execute a batch of SQL INSERT, UPDATE, or DELETE queries.
    Parameters:
      `conn` - The Connection to use to run the query. The caller is responsible for closing this Connection.
      `sql` - The SQL to execute.
      `params` - An array of query replacement parameters. Each row in this array is one set of batch replacement values.
    Returns:
      The number of rows updated per statement.
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.1

  - ### batch

    public int[] batch(String sql, Object[][] params) throws SQLException
    Execute a batch of SQL INSERT, UPDATE, or DELETE queries. The `Connection` is retrieved from the `DataSource` set in the constructor. This `Connection` must be in auto-commit mode or the update will not be saved.
    Parameters:
      `sql` - The SQL to execute.
      `params` - An array of query replacement parameters. Each row in this array is one set of batch replacement values.
    Returns:
      The number of rows updated per statement.
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.1

  - ### execute

    public int execute(Connection conn, String sql, Object... params) throws SQLException
    Execute an SQL statement, including a stored procedure call, which does not return any result sets. Any parameters which are instances of `OutParameter` will be registered as OUT parameters.

    Use this method when invoking a stored procedure with OUT parameters that does not return any result sets. If you are not invoking a stored procedure, or the stored procedure has no OUT parameters, consider using `update(java.sql.Connection, String, Object...)`. If the stored procedure returns result sets, use `execute(java.sql.Connection, String, org.apache.commons.dbutils.ResultSetHandler, Object...)`.

    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:
      `SQLException` - if a database access error occurs

  - ### execute

    public <T> List<T> execute(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params) throws SQLException
    Execute an SQL statement, including a stored procedure call, which returns one or more result sets. Any parameters which are instances of `OutParameter` will be registered as OUT parameters.

    Use this method when: a) running SQL statements that return multiple result sets; b) invoking a stored procedure that return result sets and OUT parameters. Otherwise you may wish to use `query(java.sql.Connection, String, org.apache.commons.dbutils.ResultSetHandler, Object...)` (if there are no OUT parameters) or `execute(java.sql.Connection, String, Object...)` (if there are no result sets).

    Type Parameters:
      `T` - The type of object that the handler returns
    Parameters:
      `conn` - The connection to use to run the query.
      `sql` - The SQL to execute.
      `rsh` - The result set handler
      `params` - The query replacement parameters.
    Returns:
      A list of objects generated by the handler
    Throws:
      `SQLException` - if a database access error occurs

  - ### execute

    public int execute(String sql, Object... params) throws SQLException
    Execute an SQL statement, including a stored procedure call, which does not return any result sets. Any parameters which are instances of `OutParameter` will be registered as OUT parameters.

    Use this method when invoking a stored procedure with OUT parameters that does not return any result sets. If you are not invoking a stored procedure, or the stored procedure has no OUT parameters, consider using `update(String, Object...)`. If the stored procedure returns result sets, use `execute(String, org.apache.commons.dbutils.ResultSetHandler, Object...)`.

    The `Connection` is retrieved from the `DataSource` set in the constructor. This `Connection` must be in auto-commit mode or the update will not be saved.

    Parameters:
      `sql` - The SQL statement to execute.
      `params` - Initializes the CallableStatement's parameters (i.e. '?').
    Returns:
      The number of rows updated.
    Throws:
      `SQLException` - if a database access error occurs

  - ### execute

    public <T> List<T> execute(String sql, ResultSetHandler<T> rsh, Object... params) throws SQLException
    Execute an SQL statement, including a stored procedure call, which returns one or more result sets. Any parameters which are instances of `OutParameter` will be registered as OUT parameters.

    Use this method when: a) running SQL statements that return multiple result sets; b) invoking a stored procedure that return result sets and OUT parameters. Otherwise you may wish to use `query(String, org.apache.commons.dbutils.ResultSetHandler, Object...)` (if there are no OUT parameters) or `execute(String, Object...)` (if there are no result sets).

    Type Parameters:
      `T` - The type of object that the handler returns
    Parameters:
      `sql` - The SQL to execute.
      `rsh` - The result set handler
      `params` - The query replacement parameters.
    Returns:
      A list of objects generated by the handler
    Throws:
      `SQLException` - if a database access error occurs

  - ### insert

    public <T> T insert(Connection conn, String sql, ResultSetHandler<T> rsh) throws SQLException
    Execute an SQL INSERT query without replacement parameters.
    Type Parameters:
      `T` - The type of object that the handler returns
    Parameters:
      `conn` - The connection to use to run the query.
      `sql` - The SQL to execute.
      `rsh` - The handler used to create the result object from the `ResultSet` of auto-generated keys.
    Returns:
      An object generated by the handler.
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6

  - ### insert

    public <T> T insert(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params) throws SQLException
    Execute an SQL INSERT query.
    Type Parameters:
      `T` - The type of object that the handler returns
    Parameters:
      `conn` - The connection to use to run the query.
      `sql` - The SQL to execute.
      `rsh` - The handler used to create the result object from the `ResultSet` of auto-generated keys.
      `params` - The query replacement parameters.
    Returns:
      An object generated by the handler.
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6

  - ### insert

    public <T> T insert(String sql, ResultSetHandler<T> rsh) throws SQLException
    Executes the given INSERT SQL without any replacement parameters. The `Connection` is retrieved from the `DataSource` set in the constructor.
    Type Parameters:
      `T` - The type of object that the handler returns
    Parameters:
      `sql` - The SQL statement to execute.
      `rsh` - The handler used to create the result object from the `ResultSet` of auto-generated keys.
    Returns:
      An object generated by the handler.
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6

  - ### insert

    public <T> T insert(String sql, ResultSetHandler<T> rsh, Object... params) throws SQLException
    Executes the given INSERT SQL statement. The `Connection` is retrieved from the `DataSource` set in the constructor. This `Connection` must be in auto-commit mode or the insert will not be saved.
    Type Parameters:
      `T` - The type of object that the handler returns
    Parameters:
      `sql` - The SQL statement to execute.
      `rsh` - The handler used to create the result object from the `ResultSet` of auto-generated keys.
      `params` - Initializes the PreparedStatement's IN (i.e. '?')
    Returns:
      An object generated by the handler.
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6

  - ### insertBatch

    public <T> T insertBatch(Connection conn, String sql, ResultSetHandler<T> rsh, Object[][] params) throws SQLException
    Executes the given batch of INSERT SQL statements.
    Type Parameters:
      `T` - The type of object that the handler returns
    Parameters:
      `conn` - The connection to use to run the query.
      `sql` - The SQL to execute.
      `rsh` - The handler used to create the result object from the `ResultSet` of auto-generated keys.
      `params` - The query replacement parameters.
    Returns:
      The result generated by the handler.
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6

  - ### insertBatch

    public <T> T insertBatch(String sql, ResultSetHandler<T> rsh, Object[][] params) throws SQLException
    Executes the given batch of INSERT SQL statements. The `Connection` is retrieved from the `DataSource` set in the constructor. This `Connection` must be in auto-commit mode or the insert will not be saved.
    Type Parameters:
      `T` - The type of object that the handler returns
    Parameters:
      `sql` - The SQL statement to execute.
      `rsh` - The handler used to create the result object from the `ResultSet` of auto-generated keys.
      `params` - Initializes the PreparedStatement's IN (i.e. '?')
    Returns:
      The result generated by the handler.
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6

  - ### query

    @Deprecated public <T> T query(Connection conn, String sql, Object param, ResultSetHandler<T> rsh) throws SQLException
    Deprecated.
    Use `query(Connection, String, ResultSetHandler, Object...)`
    Execute an SQL SELECT query with a single replacement parameter. The caller is responsible for closing the connection.
    Type Parameters:
      `T` - The type of object that the handler returns
    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:
      `SQLException` - if a database access error occurs

  - ### query

    @Deprecated public <T> T query(Connection conn, String sql, Object[] params, ResultSetHandler<T> rsh) throws SQLException
    Deprecated.
    Use `query(Connection,String,ResultSetHandler,Object...)` instead
    Execute an SQL SELECT query with replacement parameters. The caller is responsible for closing the connection.
    Type Parameters:
      `T` - The type of object that the handler returns
    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:
      `SQLException` - if a database access error occurs

  - ### query

    public <T> T query(Connection conn, String sql, ResultSetHandler<T> rsh) throws SQLException
    Execute an SQL SELECT query without any replacement parameters. The caller is responsible for closing the connection.
    Type Parameters:
      `T` - The type of object that the handler returns
    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:
      `SQLException` - if a database access error occurs

  - ### query

    public <T> T query(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params) throws SQLException
    Execute an SQL SELECT query with replacement parameters. The caller is responsible for closing the connection.
    Type Parameters:
      `T` - The type of object that the handler returns
    Parameters:
      `conn` - The connection to execute the query in.
      `sql` - The query to execute.
      `rsh` - The handler that converts the results into an object.
      `params` - The replacement parameters.
    Returns:
      The object returned by the handler.
    Throws:
      `SQLException` - if a database access error occurs

  - ### query

    @Deprecated public <T> T query(String sql, Object param, ResultSetHandler<T> rsh) throws SQLException
    Deprecated.
    Use `query(String, ResultSetHandler, Object...)`
    Executes the given SELECT SQL with a single replacement parameter. The `Connection` is retrieved from the `DataSource` set in the constructor.
    Type Parameters:
      `T` - The type of object that the handler returns
    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:
      `SQLException` - if a database access error occurs

  - ### query

    @Deprecated public <T> T query(String sql, Object[] params, ResultSetHandler<T> rsh) throws SQLException
    Deprecated.
    Use `query(String, ResultSetHandler, Object...)`
    Executes the given SELECT SQL query and returns a result object. The `Connection` is retrieved from the `DataSource` set in the constructor.
    Type Parameters:
      `T` - The type of object that the handler returns
    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:
      `SQLException` - if a database access error occurs

  - ### query

    public <T> T query(String sql, ResultSetHandler<T> rsh) throws SQLException
    Executes the given SELECT SQL without any replacement parameters. The `Connection` is retrieved from the `DataSource` set in the constructor.
    Type Parameters:
      `T` - The type of object that the handler returns
    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:
      `SQLException` - if a database access error occurs

  - ### query

    public <T> T query(String sql, ResultSetHandler<T> rsh, Object... params) throws SQLException
    Executes the given SELECT SQL query and returns a result object. The `Connection` is retrieved from the `DataSource` set in the constructor.
    Type Parameters:
      `T` - The type of object that the handler returns
    Parameters:
      `sql` - The SQL statement to execute.
      `rsh` - The handler used to create the result object from the `ResultSet`.
      `params` - Initialize the PreparedStatement's IN parameters with this array.
    Returns:
      An object generated by the handler.
    Throws:
      `SQLException` - if a database access error occurs

  - ### update

    public int update(Connection conn, String sql) throws 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:
      `SQLException` - if a database access error occurs

  - ### update

    public int update(Connection conn, String sql, Object param) throws 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:
      `SQLException` - if a database access error occurs

  - ### update

    public int update(Connection conn, String sql, Object... params) throws 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:
      `SQLException` - if a database access error occurs

  - ### update

    public int update(String sql) throws 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. This `Connection` must be in auto-commit mode or the update will not be saved.
    Parameters:
      `sql` - The SQL statement to execute.
    Returns:
      The number of rows updated.
    Throws:
      `SQLException` - if a database access error occurs

  - ### update

    public int update(String sql, Object param) throws 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. This `Connection` must be in auto-commit mode or the update will not be saved.
    Parameters:
      `sql` - The SQL statement to execute.
      `param` - The replacement parameter.
    Returns:
      The number of rows updated.
    Throws:
      `SQLException` - if a database access error occurs

  - ### update

    public int update(String sql, Object... params) throws SQLException
    Executes the given INSERT, UPDATE, or DELETE SQL statement. The `Connection` is retrieved from the `DataSource` set in the constructor. This `Connection` must be in auto-commit mode or the update will not be saved.
    Parameters:
      `sql` - The SQL statement to execute.
      `params` - Initializes the PreparedStatement's IN (i.e. '?') parameters.
    Returns:
      The number of rows updated.
    Throws:
      `SQLException` - if a database access error occurs