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 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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### ds

          @Deprecated
          protected final DataSource ds

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

  - ### Constructor Detail

    - #### 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 Detail

    - #### 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.