Package groovy.sql

# Class BatchingStatementWrapper

java.lang.Object
groovy.lang.GroovyObjectSupport
groovy.sql.BatchingStatementWrapper

All Implemented Interfaces:
  `GroovyObject`, `AutoCloseable`

Direct Known Subclasses:
  `BatchingPreparedStatementWrapper`

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
  Modifier and Type
  Field
  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
  Description
  `BatchingStatementWrapper(Statement delegate, int batchSize, Logger log)`
  Creates a batching wrapper for a statement.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addBatch(GString sql)`
  Adds a SQL command to the current batch, composed from a `GString`.
  `void`
  `addBatch(String sql)`
  Adds a SQL command to the current batch.
  `void`
  `clearBatch()`
  Clears the current batch and resets this wrapper's batch bookkeeping.
  `void`
  `close()`
  Closes the wrapped statement.
  `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.
  `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.

  ### Methods inherited from class groovy.lang.GroovyObjectSupport

  `getMetaClass, setMetaClass`

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

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

  ### Methods inherited from interface groovy.lang.GroovyObject

  `getProperty, setProperty`

- ## Field Details

  - ### batchSize

    protected int batchSize
    Automatic execution threshold; `0` disables automatic partitioning.

  - ### batchCount

    protected int batchCount
    Number of commands added since the last delegate batch execution.

  - ### log

    protected Logger log
    Logger used for batch diagnostics.

  - ### results

    protected List<Integer> results
    Accumulated update counts across delegate batch executions.

- ## Constructor Details

  - ### BatchingStatementWrapper

    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 Details

  - ### reset

    protected void reset()
    Resets the wrapper's in-memory batch bookkeeping.

  - ### invokeMethod

    public Object invokeMethod(String name, Object args)
    Delegates unknown method calls to the wrapped `Statement`.
    Specified by:
      `invokeMethod` in interface `GroovyObject`
    Parameters:
      `name` - the method name
      `args` - the method arguments
    Returns:
      the delegated result

  - ### addBatch

    public void addBatch(String sql) throws SQLException
    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(String, groovy.lang.Closure)`, whose wrapper takes parameters rather than text.

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

  - ### addBatch

    public void addBatch(GString sql) throws SQLException
    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.

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

  - ### incrementBatchCount

    protected void incrementBatchCount() throws SQLException
    Increments batch count (after addBatch(..) has been called) and execute `delegate.executeBatch()` if batchSize has been reached.
    Throws:
      `SQLException`

  - ### clearBatch

    public void clearBatch() throws SQLException
    Clears the current batch and resets this wrapper's batch bookkeeping.
    Throws:
      `SQLException` - if the wrapped statement fails to clear its batch

  - ### executeBatch

    public int[] executeBatch() throws SQLException
    Executes any pending batched commands and returns the aggregated update counts.
    Returns:
      one update count per executed batch command
    Throws:
      `SQLException` - if batch execution fails

  - ### processResult

    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

  - ### close

    public void close() throws SQLException
    Closes the wrapped statement.
    Specified by:
      `close` in interface `AutoCloseable`
    Throws:
      `SQLException` - if the statement cannot be closed