org.springframework.batch.repeat.support

## Class RepeatTemplate

- java.lang.Object
- - org.springframework.batch.repeat.support.RepeatTemplate

- All Implemented Interfaces:
    RepeatOperations
  Direct Known Subclasses:
    TaskExecutorRepeatTemplate

      public class RepeatTemplate
      extends java.lang.Object
      implements RepeatOperations

  Simple implementation and base class for batch templates implementing `RepeatOperations`. Provides a framework including interceptors and policies. Subclasses just need to provide a method that gets the next result and one that waits for all the results to be returned from concurrent processes or threads.
  N.B. the template accumulates thrown exceptions during the iteration, and they are all processed together when the main loop ends (i.e. finished processing the items). Clients that do not want to stop execution when an exception is thrown can use a specific `CompletionPolicy` that does not finish when exceptions are received. This is not the default behaviour.
  Clients that want to take some business action when an exception is thrown by the `RepeatCallback` can consider using a custom `RepeatListener` instead of trying to customise the `CompletionPolicy`. This is generally a friendlier interface to implement, and the `RepeatListener.after(RepeatContext, RepeatStatus)` method is passed in the result of the callback, which would be an instance of `Throwable` if the business processing had thrown an exception. If the exception is not to be propagated to the caller, then a non-default `CompletionPolicy` needs to be provided as well, but that could be off the shelf, with the business action implemented only in the interceptor.
  Author:
    Dave Syer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected org.apache.commons.logging.Log` | `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RepeatTemplate()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected boolean` | `canContinue(RepeatStatus value)` Check return value from batch operation.
    `protected RepeatInternalState` | `createInternalState(RepeatContext context)` Create an internal state object that is used to store data needed internally in the scope of an iteration.
    `protected void` | `executeAfterInterceptors(RepeatContext context, RepeatStatus value)` Convenience method to execute after interceptors on a callback result.
    `protected RepeatStatus` | `getNextResult(RepeatContext context, RepeatCallback callback, RepeatInternalState state)` Get the next completed result, possibly executing several callbacks until one finally finishes.
    `protected boolean` | `isComplete(RepeatContext context)` Delegate to `CompletionPolicy`.
    `protected boolean` | `isComplete(RepeatContext context, RepeatStatus result)` Delegate to the `CompletionPolicy`.
    `RepeatStatus` | `iterate(RepeatCallback callback)` Execute the batch callback until the completion policy decides that we are finished.
    `void` | `registerListener(RepeatListener listener)` Register an additional listener.
    `void` | `setCompletionPolicy(CompletionPolicy terminationPolicy)` Setter for policy to decide when the batch is complete.
    `void` | `setExceptionHandler(ExceptionHandler exceptionHandler)` Setter for exception handler strategy.
    `void` | `setListeners(RepeatListener[] listeners)` Set the listeners for this template, registering them for callbacks at appropriate times in the iteration.
    `protected RepeatContext` | `start()` Delegate to the `CompletionPolicy`.
    `protected void` | `update(RepeatContext context)` Delegate to the `CompletionPolicy`.
    `protected boolean` | `waitForResults(RepeatInternalState state)` If necessary, wait for results to come back from remote or concurrent processes.

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

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

- - ### Field Detail

    - #### logger

          protected org.apache.commons.logging.Log logger

  - ### Constructor Detail

    - #### RepeatTemplate

          public RepeatTemplate()

  - ### Method Detail

    - #### setListeners

          public void setListeners(RepeatListener[] listeners)

      Set the listeners for this template, registering them for callbacks at appropriate times in the iteration.
      Parameters:
        `listeners` - listeners to be used

    - #### registerListener

          public void registerListener(RepeatListener listener)

      Register an additional listener.
      Parameters:
        `listener` - a single listener to be added to the list

    - #### setExceptionHandler

          public void setExceptionHandler(ExceptionHandler exceptionHandler)

      Setter for exception handler strategy. The exception handler is called at the end of a batch, after the `CompletionPolicy` has determined that the batch is complete. By default all exceptions are re-thrown.
      Parameters:
        `exceptionHandler` - the `ExceptionHandler` to use.
      See Also:
        `ExceptionHandler`, `DefaultExceptionHandler`, `setCompletionPolicy(CompletionPolicy)`

    - #### setCompletionPolicy

          public void setCompletionPolicy(CompletionPolicy terminationPolicy)

      Setter for policy to decide when the batch is complete. The default is to complete normally when the callback returns a `RepeatStatus` which is not marked as continuable, and abnormally when the callback throws an exception (but the decision to re-throw the exception is deferred to the `ExceptionHandler`).
      Parameters:
        `terminationPolicy` - a TerminationPolicy.
      Throws:
        `java.lang.IllegalArgumentException` - if the argument is null
      See Also:
        `setExceptionHandler(ExceptionHandler)`

    - #### iterate

          public RepeatStatus iterate(RepeatCallback callback)

      Execute the batch callback until the completion policy decides that we are finished. Wait for the whole batch to finish before returning even if the task executor is asynchronous.
      Specified by:
        `iterate` in interface `RepeatOperations`
      Parameters:
        `callback` - the batch callback.
      Returns:
        the aggregate of the result of all the callback operations. An indication of whether the `RepeatOperations` can continue processing if this method is called again.
      See Also:
        `RepeatOperations.iterate(org.springframework.batch.repeat.RepeatCallback)`

    - #### createInternalState

          protected RepeatInternalState createInternalState(RepeatContext context)

      Create an internal state object that is used to store data needed internally in the scope of an iteration. Used by subclasses to manage the queueing and retrieval of asynchronous results. The default just provides an accumulation of Throwable instances for processing at the end of the batch.
      Parameters:
        `context` - the current `RepeatContext`
      Returns:
        a `RepeatInternalState` instance.
      See Also:
        `waitForResults(RepeatInternalState)`

    - #### getNextResult

          protected RepeatStatus getNextResult(RepeatContext context,
                                               RepeatCallback callback,
                                               RepeatInternalState state)
                                        throws java.lang.Throwable

      Get the next completed result, possibly executing several callbacks until one finally finishes. Normally a subclass would have to override both this method and `createInternalState(RepeatContext)` because the implementation of this method would rely on the details of the internal state.
      Parameters:
        `context` - current BatchContext.
        `callback` - the callback to execute.
        `state` - maintained by the implementation.
      Returns:
        a finished result.
      Throws:
        `java.lang.Throwable` - any Throwable emitted during the iteration
      See Also:
        `isComplete(RepeatContext)`, `createInternalState(RepeatContext)`

    - #### waitForResults

          protected boolean waitForResults(RepeatInternalState state)

      If necessary, wait for results to come back from remote or concurrent processes. By default does nothing and returns true.
      Parameters:
        `state` - the internal state.
      Returns:
        true if `canContinue(RepeatStatus)` is true for all results retrieved.

    - #### canContinue

          protected final boolean canContinue(RepeatStatus value)

      Check return value from batch operation.
      Parameters:
        `value` - the last callback result.
      Returns:
        true if the value is `RepeatStatus.CONTINUABLE`.

    - #### executeAfterInterceptors

          protected void executeAfterInterceptors(RepeatContext context,
                                                  RepeatStatus value)

      Convenience method to execute after interceptors on a callback result.
      Parameters:
        `context` - the current batch context.
        `value` - the result of the callback to process.

    - #### isComplete

          protected boolean isComplete(RepeatContext context,
                                       RepeatStatus result)

      Delegate to the `CompletionPolicy`.
      Parameters:
        `context` - the current batch context.
        `result` - the result of the latest batch item processing.
      Returns:
        true if complete according to policy and result value, else false.
      See Also:
        `CompletionPolicy.isComplete(RepeatContext, RepeatStatus)`

    - #### isComplete

          protected boolean isComplete(RepeatContext context)

      Delegate to `CompletionPolicy`.
      Parameters:
        `context` - the current batch context.
      Returns:
        true if complete according to policy alone not including result value, else false.
      See Also:
        `CompletionPolicy.isComplete(RepeatContext)`

    - #### start

          protected RepeatContext start()

      Delegate to the `CompletionPolicy`.
      Returns:
        a `RepeatContext` object that can be used by the implementation to store internal state for a batch step.
      See Also:
        `CompletionPolicy.start(RepeatContext)`

    - #### update

          protected void update(RepeatContext context)

      Delegate to the `CompletionPolicy`.
      Parameters:
        `context` - the value returned by start.
      See Also:
        `CompletionPolicy.update(RepeatContext)`