Package org.apache.commons.dbutils

# Class AbstractQueryRunner

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

Direct Known Subclasses:
  `AsyncQueryRunner`, `QueryRunner`

public abstract class AbstractQueryRunner extends Object
The base class for QueryRunner & AsyncQueryRunner. This class is thread safe.

Since:
  1.4 (mostly extracted from QueryRunner)

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final DataSource`
  `ds`
  Deprecated.
  Access to this field should be through `getDataSource()`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractQueryRunner()`
  Default constructor, sets pmdKnownBroken to false, ds to null and stmtConfig to null.
  `AbstractQueryRunner(boolean pmdKnownBroken)`
  Constructor to control the use of `ParameterMetaData`.
  `AbstractQueryRunner(DataSource ds)`
  Constructor to provide a `DataSource`.
  `AbstractQueryRunner(DataSource ds, boolean pmdKnownBroken)`
  Constructor to provide a `DataSource` and control the use of `ParameterMetaData`.
  `AbstractQueryRunner(DataSource ds, boolean pmdKnownBroken, StatementConfiguration stmtConfig)`
  Constructor for QueryRunner that takes a `DataSource`, a `StatementConfiguration`, and controls the use of `ParameterMetaData`.
  `AbstractQueryRunner(DataSource ds, StatementConfiguration stmtConfig)`
  Constructor for QueryRunner that takes a `DataSource` to use and a `StatementConfiguration`.
  `AbstractQueryRunner(StatementConfiguration stmtConfig)`
  Constructor for QueryRunner that takes a `StatementConfiguration` to configure statements when preparing them.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `close(Connection conn)`
  Close a `Connection`.
  `protected void`
  `close(ResultSet resultSet)`
  Close a `ResultSet`.
  `protected void`
  `close(Statement stmt)`
  Close a `Statement`.
  `protected void`
  `closeQuietly(Connection conn)`
  Calls `DbUtils.closeQuietly(Connection)`.
  `protected void`
  `closeQuietly(ResultSet resultSet)`
  Calls `DbUtils.closeQuietly(ResultSet)`.
  `protected void`
  `closeQuietly(Statement statement)`
  Calls `DbUtils.closeQuietly(Statement)`.
  `void`
  `fillStatement(PreparedStatement stmt, Object... params)`
  Fill the `PreparedStatement` replacement parameters with the given objects.
  `void`
  `fillStatement(PreparedStatement stmt, ParameterMetaData pmd, Object... params)`
  Fill the `PreparedStatement` replacement parameters with the given objects, and prefetched parameter metadata.
  `void`
  `fillStatementWithBean(PreparedStatement stmt, Object bean, PropertyDescriptor[] properties)`
  Fill the `PreparedStatement` replacement parameters with the given object's bean property values.
  `void`
  `fillStatementWithBean(PreparedStatement stmt, Object bean, String... propertyNames)`
  Fill the `PreparedStatement` replacement parameters with the given object's bean property values.
  `DataSource`
  `getDataSource()`
  Returns the `DataSource` this runner is using.
  `ParameterMetaData`
  `getParameterMetaData(PreparedStatement stmt)`
  Get the `ParameterMetaData` of the prepared statement, if the `pmdKnownBroken` is set to false.
  `boolean`
  `isPmdKnownBroken()`
  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.
  `protected CallableStatement`
  `prepareCall(Connection conn, String sql)`
  Factory method that creates and initializes a `CallableStatement` object for the given SQL.
  `protected Connection`
  `prepareConnection()`
  Factory method that creates and initializes a `Connection` object.
  `protected PreparedStatement`
  `prepareStatement(Connection conn, String sql)`
  Factory method that creates and initializes a `PreparedStatement` object for the given SQL.
  `protected PreparedStatement`
  `prepareStatement(Connection conn, String sql, int returnedKeys)`
  Factory method that creates and initializes a `PreparedStatement` object for the given SQL.
  `protected void`
  `rethrow(SQLException cause, String sql, Object... params)`
  Throws a new exception with a more informative error message.
  `protected ResultSet`
  `wrap(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 Details

  - ### ds

    @Deprecated protected final DataSource ds
    Deprecated.
    Access to this field should be through `getDataSource()`.
    The DataSource to retrieve connections from.

- ## Constructor Details

  - ### AbstractQueryRunner

    public AbstractQueryRunner()
    Default constructor, sets pmdKnownBroken to false, ds to null and stmtConfig to null.

  - ### AbstractQueryRunner

    public AbstractQueryRunner(boolean pmdKnownBroken)
    Constructor to control 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.

  - ### AbstractQueryRunner

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

  - ### AbstractQueryRunner

    public AbstractQueryRunner(DataSource ds, boolean pmdKnownBroken)
    Constructor to provide a `DataSource` and control 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.

  - ### AbstractQueryRunner

    public AbstractQueryRunner(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.

  - ### AbstractQueryRunner

    public AbstractQueryRunner(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.

  - ### AbstractQueryRunner

    public AbstractQueryRunner(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

  - ### close

    protected void close(Connection conn) throws SQLException
    Close a `Connection`. This implementation avoids closing if null and does not suppress any exceptions. Subclasses can override to provide special handling like logging.
    Parameters:
      `conn` - Connection to close
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.1

  - ### close

    protected void close(ResultSet resultSet) throws SQLException
    Close a `ResultSet`. This implementation avoids closing if null and does not suppress any exceptions. Subclasses can override to provide special handling like logging.
    Parameters:
      `resultSet` - ResultSet to close
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.1

  - ### close

    protected void close(Statement stmt) throws SQLException
    Close a `Statement`. This implementation avoids closing if null and does not suppress any exceptions. Subclasses can override to provide special handling like logging.
    Parameters:
      `stmt` - Statement to close
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.1

  - ### closeQuietly

    protected void closeQuietly(Connection conn)
    Calls `DbUtils.closeQuietly(Connection)`.
    Parameters:
      `conn` - Connection to close.
    Since:
      1.8.0

  - ### closeQuietly

    protected void closeQuietly(ResultSet resultSet)
    Calls `DbUtils.closeQuietly(ResultSet)`.
    Parameters:
      `resultSet` - ResultSet to close.
    Since:
      1.8.0

  - ### closeQuietly

    protected void closeQuietly(Statement statement)
    Calls `DbUtils.closeQuietly(Statement)`.
    Parameters:
      `statement` - ResultSet to close.
    Since:
      1.8.0

  - ### fillStatement

    public void fillStatement(PreparedStatement stmt, Object... params) throws SQLException
    Fill the `PreparedStatement` replacement parameters with the given objects.
    Parameters:
      `stmt` - PreparedStatement to fill
      `params` - Query replacement parameters; `null` is a valid value to pass in.
    Throws:
      `SQLException` - if a database access error occurs

  - ### fillStatement

    public void fillStatement(PreparedStatement stmt, ParameterMetaData pmd, Object... params) throws SQLException
    Fill the `PreparedStatement` replacement parameters with the given objects, and prefetched parameter metadata.
    Parameters:
      `stmt` - PreparedStatement to fill
      `pmd` - Prefetched parameter metadata
      `params` - Query replacement parameters; `null` is a valid value to pass in.
    Throws:
      `SQLException` - if a database access error occurs

  - ### fillStatementWithBean

    public void fillStatementWithBean(PreparedStatement stmt, Object bean, PropertyDescriptor[] properties) throws SQLException
    Fill the `PreparedStatement` replacement parameters with the given object's bean property values.
    Parameters:
      `stmt` - PreparedStatement to fill
      `bean` - a JavaBean object
      `properties` - an ordered array of properties; this gives the order to insert values in the statement
    Throws:
      `SQLException` - if a database access error occurs

  - ### fillStatementWithBean

    public void fillStatementWithBean(PreparedStatement stmt, Object bean, String... propertyNames) throws SQLException
    Fill the `PreparedStatement` replacement parameters with the given object's bean property values.
    Parameters:
      `stmt` - PreparedStatement to fill
      `bean` - A JavaBean object
      `propertyNames` - An ordered array of property names (these should match the getters/setters); this gives the order to insert values in the statement
    Throws:
      `SQLException` - If a database access error occurs

  - ### getDataSource

    public DataSource getDataSource()
    Returns the `DataSource` this runner is using. `QueryRunner` methods always call this method to get the `DataSource` so subclasses can provide specialized behavior.
    Returns:
      DataSource the runner is using

  - ### getParameterMetaData

    public ParameterMetaData getParameterMetaData(PreparedStatement stmt) throws SQLException
    Get the `ParameterMetaData` of the prepared statement, if the `pmdKnownBroken` is set to false.
    Parameters:
      `stmt` - PreparedStatement of which to query the metadata of parameters
    Returns:
      the metadata of parameters
    Throws:
      `SQLException` - if a database access error occurs

  - ### isPmdKnownBroken

    public boolean isPmdKnownBroken()
    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.
    Returns:
      the flag to skip (or not) `ParameterMetaData.getParameterType(int)`
    Since:
      1.4

  - ### prepareCall

    protected CallableStatement prepareCall(Connection conn, String sql) throws SQLException
    Factory method that creates and initializes a `CallableStatement` object for the given SQL. `QueryRunner` methods always call this method to prepare callable statements for them. Subclasses can override this method to provide special CallableStatement configuration if needed. This implementation simply calls `conn.prepareCall(sql)`.
    Parameters:
      `conn` - The `Connection` used to create the `CallableStatement`
      `sql` - The SQL statement to prepare.
    Returns:
      An initialized `CallableStatement`.
    Throws:
      `SQLException` - if a database access error occurs

  - ### prepareConnection

    protected Connection prepareConnection() throws SQLException
    Factory method that creates and initializes a `Connection` object. `QueryRunner` methods always call this method to retrieve connections from its DataSource. Subclasses can override this method to provide special `Connection` configuration if needed. This implementation simply calls `ds.getConnection()`.
    Returns:
      An initialized `Connection`.
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.1

  - ### prepareStatement

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

  - ### prepareStatement

    protected PreparedStatement prepareStatement(Connection conn, String sql, int returnedKeys) throws 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, returnedKeys)` which will result in the ability to retrieve the automatically-generated keys from an auto_increment column.
    Parameters:
      `conn` - The `Connection` used to create the `PreparedStatement`
      `sql` - The SQL statement to prepare.
      `returnedKeys` - Flag indicating whether to return generated keys or not.
    Returns:
      An initialized `PreparedStatement`.
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6

  - ### rethrow

    protected void rethrow(SQLException cause, String sql, Object... params) throws 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 parameters; `null` is a valid value to pass in.
    Throws:
      `SQLException` - if a database access error occurs

  - ### wrap

    protected ResultSet wrap(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.