BatchSqlUpdate (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jdbc.object

## Class BatchSqlUpdate

- java.lang.Object
- - org.springframework.jdbc.object.RdbmsOperation
  - - org.springframework.jdbc.object.SqlOperation
    - - org.springframework.jdbc.object.SqlUpdate
      - - org.springframework.jdbc.object.BatchSqlUpdate

- All Implemented Interfaces:
    InitializingBean

      public class BatchSqlUpdate
      extends SqlUpdate

  SqlUpdate subclass that performs batch update operations. Encapsulates queuing up records to be updated, and adds them as a single batch once `flush` is called or the given batch size has been met.

  Note that this class is a non-thread-safe object, in contrast to all other JDBC operations objects in this package. You need to create a new instance of it for each use, or call `reset` before reuse within the same thread.

  Since:
    1.1
  Author:
    Keith Donald, Juergen Hoeller
  See Also:
    `flush()`, `reset()`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_BATCH_SIZE` Default number of inserts to accumulate before commiting a batch (5000).

    - ### Fields inherited from class org.springframework.jdbc.object.RdbmsOperation

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BatchSqlUpdate()` Constructor to allow use as a JavaBean.
    `BatchSqlUpdate(DataSource ds, String sql)` Construct an update object with a given DataSource and SQL.
    `BatchSqlUpdate(DataSource ds, String sql, int[] types)` Construct an update object with a given DataSource, SQL and anonymous parameters.
    `BatchSqlUpdate(DataSource ds, String sql, int[] types, int batchSize)` Construct an update object with a given DataSource, SQL, anonymous parameters and specifying the maximum number of rows that may be affected.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int[]` | `flush()` Trigger any queued update operations to be added as a final batch.
    `int` | `getExecutionCount()` Return the number of already executed statements.
    `int` | `getQueueCount()` Return the current number of statements or statement parameters in the queue.
    `int[]` | `getRowsAffected()` Return the number of affected rows for all already executed statements.
    `void` | `reset()` Reset the statement parameter queue, the rows affected cache, and the execution count.
    `void` | `setBatchSize(int batchSize)` Set the number of statements that will trigger an automatic intermediate flush.
    `void` | `setTrackRowsAffected(boolean trackRowsAffected)` Set whether to track the rows affected by batch updates performed by this operation object.
    `protected boolean` | `supportsLobParameters()` BatchSqlUpdate does not support BLOB or CLOB parameters.
    `int` | `update(Object... params)` Overridden version of `update` that adds the given statement parameters to the queue rather than executing them immediately.

    - ### Methods inherited from class org.springframework.jdbc.object.SqlUpdate

      `checkRowsAffected, setMaxRowsAffected, setRequiredRowsAffected, update, update, update, update, update, update, update, update, updateByNamedParam, updateByNamedParam`

    - ### Methods inherited from class org.springframework.jdbc.object.SqlOperation

      `compileInternal, getParsedSql, newPreparedStatementCreator, newPreparedStatementCreator, newPreparedStatementSetter, onCompileInternal`

    - ### Methods inherited from class org.springframework.jdbc.object.RdbmsOperation

      `afterPropertiesSet, allowsUnusedParameters, checkCompiled, compile, declareParameter, getDeclaredParameters, getGeneratedKeysColumnNames, getJdbcTemplate, getResultSetType, getSql, isCompiled, isReturnGeneratedKeys, isUpdatableResults, setDataSource, setFetchSize, setGeneratedKeysColumnNames, setJdbcTemplate, setMaxRows, setParameters, setQueryTimeout, setResultSetType, setReturnGeneratedKeys, setSql, setTypes, setUpdatableResults, validateNamedParameters, validateParameters`

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

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

- - ### Field Detail

    - #### DEFAULT_BATCH_SIZE

          public static int DEFAULT_BATCH_SIZE

      Default number of inserts to accumulate before commiting a batch (5000).

  - ### Constructor Detail

    - #### BatchSqlUpdate

          public BatchSqlUpdate()

      Constructor to allow use as a JavaBean. DataSource and SQL must be supplied before compilation and use.
      See Also:
        `RdbmsOperation.setDataSource(javax.sql.DataSource)`, `RdbmsOperation.setSql(java.lang.String)`

    - #### BatchSqlUpdate

          public BatchSqlUpdate(DataSource ds,
                        String sql)

      Construct an update object with a given DataSource and SQL.
      Parameters:
        `ds` - DataSource to use to obtain connections
        `sql` - SQL statement to execute

    - #### BatchSqlUpdate

          public BatchSqlUpdate(DataSource ds,
                        String sql,
                        int[] types)

      Construct an update object with a given DataSource, SQL and anonymous parameters.
      Parameters:
        `ds` - DataSource to use to obtain connections
        `sql` - SQL statement to execute
        `types` - SQL types of the parameters, as defined in the `java.sql.Types` class
      See Also:
        `Types`

    - #### BatchSqlUpdate

          public BatchSqlUpdate(DataSource ds,
                        String sql,
                        int[] types,
                        int batchSize)

      Construct an update object with a given DataSource, SQL, anonymous parameters and specifying the maximum number of rows that may be affected.
      Parameters:
        `ds` - DataSource to use to obtain connections
        `sql` - SQL statement to execute
        `types` - SQL types of the parameters, as defined in the `java.sql.Types` class
        `batchSize` - the number of statements that will trigger an automatic intermediate flush
      See Also:
        `Types`

  - ### Method Detail

    - #### setBatchSize

          public void setBatchSize(int batchSize)

      Set the number of statements that will trigger an automatic intermediate flush. `update` calls or the given statement parameters will be queued until the batch size is met, at which point it will empty the queue and execute the batch.

      You can also flush already queued statements with an explicit `flush` call. Note that you need to this after queueing all parameters to guarantee that all statements have been flushed.

    - #### setTrackRowsAffected

          public void setTrackRowsAffected(boolean trackRowsAffected)

      Set whether to track the rows affected by batch updates performed by this operation object.

      Default is "true". Turn this off to save the memory needed for the list of row counts.

      See Also:
        `getRowsAffected()`

    - #### supportsLobParameters

          protected boolean supportsLobParameters()

      BatchSqlUpdate does not support BLOB or CLOB parameters.
      Overrides:
        `supportsLobParameters` in class `RdbmsOperation`

    - #### update

          public int update(Object... params)
                     throws DataAccessException

      Overridden version of `update` that adds the given statement parameters to the queue rather than executing them immediately. All other `update` methods of the SqlUpdate base class go through this method and will thus behave similarly.

      You need to call `flush` to actually execute the batch. If the specified batch size is reached, an implicit flush will happen; you still need to finally call `flush` to flush all statements.

      Overrides:
        `update` in class `SqlUpdate`
      Parameters:
        `params` - array of parameter objects
      Returns:
        the number of rows affected by the update (always -1, meaning "not applicable", as the statement is not actually executed by this method)
      Throws:
        `DataAccessException`
      See Also:
        `flush()`

    - #### flush

          public int[] flush()

      Trigger any queued update operations to be added as a final batch.
      Returns:
        an array of the number of rows affected by each statement

    - #### getQueueCount

          public int getQueueCount()

      Return the current number of statements or statement parameters in the queue.

    - #### getExecutionCount

          public int getExecutionCount()

      Return the number of already executed statements.

    - #### getRowsAffected

          public int[] getRowsAffected()

      Return the number of affected rows for all already executed statements. Accumulates all of `flush`'s return values until `reset` is invoked.
      Returns:
        an array of the number of rows affected by each statement
      See Also:
        `reset()`

    - #### reset

          public void reset()

      Reset the statement parameter queue, the rows affected cache, and the execution count.