Package: groovy.sql

## [Java] Class BatchingStatementWrapper

- groovy.sql.BatchingStatementWrapper

- All Implemented Interfaces and Traits:
    AutoCloseable

      public class BatchingStatementWrapper
      extends GroovyObjectSupport
      implements AutoCloseable

  Class which delegates to a Statement but keeps track of a batch count size. If the batch count reaches the predefined number, this Statement does an executeBatch() automatically. If batchSize is zero, then no batching is performed.

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected int` | `batchCount` | Number of commands added since the last delegate batch execution.
    `protected int` | `batchSize` | Automatic execution threshold; `0` disables automatic partitioning.
    `protected Logger` | `log` | Logger used for batch diagnostics.
    `protected List<Integer>` | `results` | Accumulated update counts across delegate batch executions.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `BatchingStatementWrapper(Statement delegate, int batchSize, Logger log)` Creates a batching wrapper for a statement.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `addBatch(String sql)` Adds a SQL command to the current batch.
    `` | `public void` | `addBatch(GString sql)` Adds a SQL command to the current batch, composed from a GString.
    `` | `public void` | `clearBatch()` Clears the current batch and resets this wrapper's batch bookkeeping.
    `` | `public void` | `close()` Closes the wrapped statement.
    `` | `public int[]` | `executeBatch()` Executes any pending batched commands and returns the aggregated update counts.
    `` | `protected void` | `incrementBatchCount()` Increments batch count (after addBatch(..) has been called) and execute `delegate.executeBatch()` if batchSize has been reached.
    `` | `public Object` | `invokeMethod(String name, Object args)` Delegates unknown method calls to the wrapped Statement.
    `` | `protected void` | `processResult(int[] lastResult)` Incorporates one delegate batch execution result into this wrapper's state.
    `` | `protected void` | `reset()` Resets the wrapper's in-memory batch bookkeeping.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class GroovyObjectSupport` | `getMetaClass, setMetaClass`

- - ### Field Detail

    - #### protected int batchCount

      Number of commands added since the last delegate batch execution.

    - #### protected int batchSize

      Automatic execution threshold; `0` disables automatic partitioning.

    - #### protected Logger log

      Logger used for batch diagnostics.

    - #### protected List<Integer> results

      Accumulated update counts across delegate batch executions.

  - ### Constructor Detail

    - #### public BatchingStatementWrapper(Statement delegate, int batchSize, Logger log)

      Creates a batching wrapper for a statement.

      Parameters:
        `delegate` - the statement to wrap
        `batchSize` - the automatic execution threshold; `0` disables automatic partitioning
        `log` - the logger to use for batch diagnostics

  - ### Method Detail

    - #### public void addBatch(String sql)

      Adds a SQL command to the current batch.

      The command is used as SQL text. Unlike the query methods on Sql, a GString passed here is not converted into `PreparedStatement` placeholders: a JDBC Statement batch may hold different statements, so there is nothing to bind against. Interpolating an untrusted value therefore composes it into the SQL. To bind values, batch against a single statement with Sql.withBatch, whose wrapper takes parameters rather than text.

      throws:
        SQLException if the command cannot be added
      Parameters:
        `sql` - the SQL command to add

    - #### public void addBatch(GString sql)

      Adds a SQL command to the current batch, composed from a GString.

      Present so the coercion is visible rather than silent: the `GString` is rendered to text and added as SQL, and a warning is logged the first time this happens with an interpolated value that is not a deliberate expansion. It is not rejected, because a Statement batch has no parameterised equivalent to redirect callers to — batching heterogeneous statements, generated DDL or identifiers that cannot be bound are all legitimate uses of this method.

      throws:
        SQLException if the command cannot be added
      Parameters:
        `sql` - the SQL command to add
      Since:
        6.0.0

    - #### public void clearBatch()

      Clears the current batch and resets this wrapper's batch bookkeeping.

      throws:
        SQLException if the wrapped statement fails to clear its batch

    - #### public void close()

      Closes the wrapped statement.

      throws:
        SQLException if the statement cannot be closed

    - #### public int[] executeBatch()

      Executes any pending batched commands and returns the aggregated update counts.

      throws:
        SQLException if batch execution fails
      Returns:
        one update count per executed batch command

    - #### protected void incrementBatchCount()

      Increments batch count (after addBatch(..) has been called) and execute `delegate.executeBatch()` if batchSize has been reached.

    - #### public Object invokeMethod(String name, Object args)

      Delegates unknown method calls to the wrapped Statement.

      Parameters:
        `name` - the method name
        `args` - the method arguments
      Returns:
        the delegated result

    - #### protected void processResult(int[] lastResult)

      Incorporates one delegate batch execution result into this wrapper's state.

      Parameters:
        `lastResult` - the update counts returned by the wrapped statement

    - #### protected void reset()

      Resets the wrapper's in-memory batch bookkeeping.