Package org.apache.commons.dbutils

# Class AsyncQueryRunner

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

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

Since:
  1.4
See Also:
  - `ResultSetHandler`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected class`
  `AsyncQueryRunner.BatchCallableStatement`
  Deprecated.
  No longer used by this class.
  `protected class`
  `AsyncQueryRunner.QueryCallableStatement<T>`
  Class that encapsulates the continuation for query calls.
  `protected class`
  `AsyncQueryRunner.UpdateCallableStatement`
  Deprecated.
  No longer used by this class.

- ## Field Summary

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

  `ds`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AsyncQueryRunner(boolean pmdKnownBroken, ExecutorService executorService)`
  Deprecated.
  Use `AsyncQueryRunner(ExecutorService, QueryRunner)` instead.
  `AsyncQueryRunner(ExecutorService executorService)`
  Constructor for AsyncQueryRunner.
  `AsyncQueryRunner(ExecutorService executorService, QueryRunner queryRunner)`
  Constructor for AsyncQueryRunner which uses a provided ExecutorService and underlying QueryRunner.
  `AsyncQueryRunner(DataSource ds, boolean pmdKnownBroken, ExecutorService executorService)`
  Deprecated.
  Use `AsyncQueryRunner(ExecutorService, QueryRunner)` instead.
  `AsyncQueryRunner(DataSource ds, ExecutorService executorService)`
  Deprecated.
  Use `AsyncQueryRunner(ExecutorService, QueryRunner)` instead.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Future<int[]>`
  `batch(String sql, Object[][] params)`
  Execute a batch of SQL INSERT, UPDATE, or DELETE queries.
  `Future<int[]>`
  `batch(Connection conn, String sql, Object[][] params)`
  Execute a batch of SQL INSERT, UPDATE, or DELETE queries.
  `<T> Future<T>`
  `insert(String sql, ResultSetHandler<T> rsh)`
  Executes `QueryRunner.insert(String, ResultSetHandler)` asynchronously.
  `<T> Future<T>`
  `insert(String sql, ResultSetHandler<T> rsh, Object... params)`
  Executes `QueryRunner.insert(String, ResultSetHandler, Object...)` asynchronously.
  `<T> Future<T>`
  `insert(Connection conn, String sql, ResultSetHandler<T> rsh)`
  Executes `QueryRunner.insert(Connection, String, ResultSetHandler)` asynchronously.
  `<T> Future<T>`
  `insert(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params)`
  Executes `QueryRunner.insert(Connection, String, ResultSetHandler, Object...)` asynchronously.
  `<T> Future<T>`
  `insertBatch(String sql, ResultSetHandler<T> rsh, Object[][] params)`
  `QueryRunner.insertBatch(String, ResultSetHandler, Object[][])` asynchronously.
  `<T> Future<T>`
  `insertBatch(Connection conn, String sql, ResultSetHandler<T> rsh, Object[][] params)`
  `QueryRunner.insertBatch(Connection, String, ResultSetHandler, Object[][])` asynchronously.
  `<T> Future<T>`
  `query(String sql, ResultSetHandler<T> rsh)`
  Executes the given SELECT SQL without any replacement parameters.
  `<T> Future<T>`
  `query(String sql, ResultSetHandler<T> rsh, Object... params)`
  Executes the given SELECT SQL query and returns a result object.
  `<T> Future<T>`
  `query(Connection conn, String sql, ResultSetHandler<T> rsh)`
  Execute an SQL SELECT query without any replacement parameters.
  `<T> Future<T>`
  `query(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params)`
  Execute an SQL SELECT query with replacement parameters.
  `Future<Integer>`
  `update(String sql)`
  Executes the given INSERT, UPDATE, or DELETE SQL statement without any replacement parameters.
  `Future<Integer>`
  `update(String sql, Object param)`
  Executes the given INSERT, UPDATE, or DELETE SQL statement with a single replacement parameter.
  `Future<Integer>`
  `update(String sql, Object... params)`
  Executes the given INSERT, UPDATE, or DELETE SQL statement.
  `Future<Integer>`
  `update(Connection conn, String sql)`
  Execute an SQL INSERT, UPDATE, or DELETE query without replacement parameters.
  `Future<Integer>`
  `update(Connection conn, String sql, Object param)`
  Execute an SQL INSERT, UPDATE, or DELETE query with a single replacement parameter.
  `Future<Integer>`
  `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

  - ### AsyncQueryRunner

    @Deprecated public AsyncQueryRunner(boolean pmdKnownBroken, ExecutorService executorService)
    Deprecated.
    Use `AsyncQueryRunner(ExecutorService, QueryRunner)` instead. Constructor for AsyncQueryRunner 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.
      `executorService` - the `ExecutorService` instance used to run JDBC invocations concurrently.

  - ### AsyncQueryRunner

    @Deprecated public AsyncQueryRunner(DataSource ds, boolean pmdKnownBroken, ExecutorService executorService)
    Deprecated.
    Use `AsyncQueryRunner(ExecutorService, QueryRunner)` instead. Constructor for AsyncQueryRunner that take 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.
      `executorService` - the `ExecutorService` instance used to run JDBC invocations concurrently.

  - ### AsyncQueryRunner

    @Deprecated public AsyncQueryRunner(DataSource ds, ExecutorService executorService)
    Deprecated.
    Use `AsyncQueryRunner(ExecutorService, QueryRunner)` instead. Constructor for AsyncQueryRunner that takes a `DataSource`. Methods that do not take a `Connection` parameter will retrieve connections from this `DataSource`.
    Parameters:
      `ds` - The `DataSource` to retrieve connections from.
      `executorService` - the `ExecutorService` instance used to run JDBC invocations concurrently.

  - ### AsyncQueryRunner

    public AsyncQueryRunner(ExecutorService executorService)
    Constructor for AsyncQueryRunner.
    Parameters:
      `executorService` - the `ExecutorService` instance used to run JDBC invocations concurrently.

  - ### AsyncQueryRunner

    public AsyncQueryRunner(ExecutorService executorService, QueryRunner queryRunner)
    Constructor for AsyncQueryRunner which uses a provided ExecutorService and underlying QueryRunner.
    Parameters:
      `executorService` - the `ExecutorService` instance used to run JDBC invocations concurrently.
      `queryRunner` - the `QueryRunner` instance to use for the queries.
    Since:
      1.5

- ## Method Details

  - ### batch

    public Future<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:
      A `Future` which returns the number of rows updated per statement.
    Throws:
      `SQLException` - if a database access error occurs

  - ### batch

    public Future<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:
      A `Future` which returns the number of rows updated per statement.
    Throws:
      `SQLException` - if a database access error occurs

  - ### insert

    public <T> Future<T> insert(Connection conn, String sql, ResultSetHandler<T> rsh) throws SQLException
    Executes `QueryRunner.insert(Connection, String, ResultSetHandler)` asynchronously.
    Type Parameters:
      `T` - Return type expected
    Parameters:
      `conn` - `Connection` to use to execute the SQL statement
      `sql` - SQL insert statement to execute
      `rsh` - `ResultSetHandler` for handling the results
    Returns:
      `Future` that executes a query runner insert
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6
    See Also:
      - `QueryRunner.insert(Connection, String, ResultSetHandler)`

  - ### insert

    public <T> Future<T> insert(Connection conn, String sql, ResultSetHandler<T> rsh, Object... params) throws SQLException
    Executes `QueryRunner.insert(Connection, String, ResultSetHandler, Object...)` asynchronously.
    Type Parameters:
      `T` - Return type expected
    Parameters:
      `conn` - `Connection` to use to execute the SQL statement
      `sql` - SQL insert statement to execute
      `rsh` - `ResultSetHandler` for handling the results
      `params` - Parameter values for substitution in the SQL statement
    Returns:
      `Future` that executes a query runner insert
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6
    See Also:
      - `QueryRunner.insert(Connection, String, ResultSetHandler, Object...)`

  - ### insert

    public <T> Future<T> insert(String sql, ResultSetHandler<T> rsh) throws SQLException
    Executes `QueryRunner.insert(String, ResultSetHandler)` asynchronously.
    Type Parameters:
      `T` - Return type expected
    Parameters:
      `sql` - SQL insert statement to execute
      `rsh` - `ResultSetHandler` for handling the results
    Returns:
      `Future` that executes a query runner insert
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6
    See Also:
      - `QueryRunner.insert(String, ResultSetHandler)`

  - ### insert

    public <T> Future<T> insert(String sql, ResultSetHandler<T> rsh, Object... params) throws SQLException
    Executes `QueryRunner.insert(String, ResultSetHandler, Object...)` asynchronously.
    Type Parameters:
      `T` - Return type expected
    Parameters:
      `sql` - SQL insert statement to execute
      `rsh` - `ResultSetHandler` for handling the results
      `params` - Parameter values for substitution in the SQL statement
    Returns:
      `Future` that executes a query runner insert
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6
    See Also:
      - `QueryRunner.insert(String, ResultSetHandler, Object...)`

  - ### insertBatch

    public <T> Future<T> insertBatch(Connection conn, String sql, ResultSetHandler<T> rsh, Object[][] params) throws SQLException
    `QueryRunner.insertBatch(Connection, String, ResultSetHandler, Object[][])` asynchronously.
    Type Parameters:
      `T` - Return type expected
    Parameters:
      `conn` - `Connection` to use to execute the SQL statement
      `sql` - SQL insert statement to execute
      `rsh` - `ResultSetHandler` for handling the results
      `params` - An array of query replacement parameters. Each row in this array is one set of batch replacement values.
    Returns:
      `Future` that executes a query runner batch insert
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6
    See Also:
      - `QueryRunner.insertBatch(Connection, String, ResultSetHandler, Object[][])`

  - ### insertBatch

    public <T> Future<T> insertBatch(String sql, ResultSetHandler<T> rsh, Object[][] params) throws SQLException
    `QueryRunner.insertBatch(String, ResultSetHandler, Object[][])` asynchronously.
    Type Parameters:
      `T` - Return type expected
    Parameters:
      `sql` - SQL insert statement to execute
      `rsh` - `ResultSetHandler` for handling the results
      `params` - An array of query replacement parameters. Each row in this array is one set of batch replacement values.
    Returns:
      `Future` that executes a query runner batch insert
    Throws:
      `SQLException` - if a database access error occurs
    Since:
      1.6
    See Also:
      - `QueryRunner.insertBatch(String, ResultSetHandler, Object[][])`

  - ### query

    public <T> Future<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:
      A `Future` which returns the result of the query call.
    Throws:
      `SQLException` - if a database access error occurs

  - ### query

    public <T> Future<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:
      A `Future` which returns the result of the query call.
    Throws:
      `SQLException` - if a database access error occurs

  - ### query

    public <T> Future<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:
      A `Future` which returns the result of the query call.
    Throws:
      `SQLException` - if a database access error occurs

  - ### query

    public <T> Future<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:
      A `Future` which returns the result of the query call.
    Throws:
      `SQLException` - if a database access error occurs

  - ### update

    public Future<Integer> 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:
      A `Future` which returns the number of rows updated.
    Throws:
      `SQLException` - if a database access error occurs

  - ### update

    public Future<Integer> 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:
      A `Future` which returns the number of rows updated.
    Throws:
      `SQLException` - if a database access error occurs

  - ### update

    public Future<Integer> 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:
      A `Future` which returns the number of rows updated.
    Throws:
      `SQLException` - if a database access error occurs

  - ### update

    public Future<Integer> 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:
      A `Future` which returns the number of rows updated.
    Throws:
      `SQLException` - if a database access error occurs

  - ### update

    public Future<Integer> 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:
      A `Future` which returns the number of rows updated.
    Throws:
      `SQLException` - if a database access error occurs

  - ### update

    public Future<Integer> 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:
      A `Future` which returns the number of rows updated.
    Throws:
      `SQLException` - if a database access error occurs