Spring/spring-batch
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Editing pass for repeat.adoc

Browse Source 
I edited for readability and consistency and fixed sentence errors. No questions this time.

Polishing on Merge
This commit is contained in:
Jay Bryant
2017-10-06 12:42:20 -05:00
committed by Glenn Renfro
parent fe6e5e55e2
commit 1129888e12
1 changed files with 63 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
spring-batch-docs/asciidoc/repeat.adoc
View File

@@ -11,12 +11,11 @@
=== RepeatTemplate
Batch processing is about repetitive actions - either as a simple
optimization, or as part of a job. To strategize and generalize the
repetition as well as to provide what amounts to an iterator framework,
Batch processing is about repetitive actions, either as a simple
optimization or as part of a job. To strategize and generalize the
repetition and to provide what amounts to an iterator framework,
Spring Batch has the `RepeatOperations` interface.
The `RepeatOperations` interface looks like
this:
The `RepeatOperations` interface has the following definition:
[source, java]
@@ -28,7 +27,7 @@ public interface RepeatOperations {
}
----
The callback is a simple interface that allows you to insert
The callback is an interface, shown in the following definition, that lets you insert
some business logic to be repeated:
@@ -42,10 +41,10 @@ public interface RepeatCallback {
----
The callback is executed repeatedly until the implementation
decides that the iteration should end. The return value in these
determines that the iteration should end. The return value in these
interfaces is an enumeration that can either be
`RepeatStatus.CONTINUABLE` or
`RepeatStatus.FINISHED`. A `RepeatStatus`
`RepeatStatus.FINISHED`. A `RepeatStatus` enumeration
conveys information to the caller of the repeat operations about whether
there is any more work to do. Generally speaking, implementations of
`RepeatOperations` should inspect the
@@ -56,7 +55,7 @@ The callback is executed repeatedly until the implementation
The simplest general purpose implementation of
`RepeatOperations` is
`RepeatTemplate`. It could be used like this:
`RepeatTemplate`, as shown in the following example:
[source, java]
@@ -75,14 +74,14 @@ template.iterate(new RepeatCallback() {
});
----
In the example we return `RepeatStatus.CONTINUABLE` to
In the preceding example, we return `RepeatStatus.CONTINUABLE`, to
show that there is more work to do. The callback can also return
`RepeatStatus.FINISHED` if it wants to signal to the caller that
`RepeatStatus.FINISHED`, to signal to the caller that
there is no more work to do. Some iterations can be terminated by
considerations intrinsic to the work being done in the callback, others
considerations intrinsic to the work being done in the callback. Others
are effectively infinite loops as far as the callback is concerned and the
completion decision is delegated to an external policy as in the case
above.
completion decision is delegated to an external policy, as in the case
shown in the preceding example.
[[repeatContext]]
@@ -90,16 +89,16 @@ In the example we return `RepeatStatus.CONTINUABLE` to
==== RepeatContext
The method parameter for the `RepeatCallback`
is a `RepeatContext`. Many callbacks will simply
ignore the context, but if necessary it can be used as an attribute bag
is a `RepeatContext`. Many callbacks
ignore the context. However, if necessary, it can be used as an attribute bag
to store transient data for the duration of the iteration. After the
`iterate` method returns, the context will no
longer exist.
`iterate` method returns, the context no
longer exists.
A `RepeatContext` will have a parent context
if there is a nested iteration in progress. The parent context is
If there is a nested iteration in progress, a `RepeatContext` has a parent context.
The parent context is
occasionally useful for storing data that need to be shared between
calls to `iterate`. This is the case for instance
calls to `iterate`. This is the case, for instance,
if you want to count the number of occurrences of an event in the
iteration and remember it across subsequent calls.
@@ -109,8 +108,8 @@ A `RepeatContext` will have a parent context
==== RepeatStatus
`RepeatStatus` is an enumeration used by
Spring Batch to indicate whether processing has finished. These are
possible `RepeatStatus` values:
Spring Batch to indicate whether processing has finished. It has two
possible `RepeatStatus` values, described in the following table:
.RepeatStatus Properties
@@ -123,10 +122,10 @@ A `RepeatContext` will have a parent context
`RepeatStatus` values can also be combined
with a logical AND operation using the `and()`
with a logical AND operation by using the `and()`
method in `RepeatStatus`. The effect of this is to
do a logical AND on the continuable flag. In other words, if either
status is `FINISHED`, then the result will be
status is `FINISHED`, then the result is
`FINISHED`.
[[completionPolicies]]
@@ -134,9 +133,9 @@ A `RepeatContext` will have a parent context
=== Completion Policies
Inside a `RepeatTemplate` the termination of
Inside a `RepeatTemplate`, the termination of
the loop in the `iterate` method is determined by a
`CompletionPolicy` which is also a factory for the
`CompletionPolicy`, which is also a factory for the
`RepeatContext`. The
`RepeatTemplate` has the responsibility to use the
current policy to create a `RepeatContext` and pass
@@ -149,8 +148,8 @@ Inside a `RepeatTemplate` the termination of
it asks the policy if the iteration is complete.
Spring Batch provides some simple general purpose implementations of
`CompletionPolicy`. The
`SimpleCompletionPolicy` just allows an execution up
`CompletionPolicy`.
`SimpleCompletionPolicy` allows execution up
to a fixed number of times (with `RepeatStatus.FINISHED`
forcing early completion at any time).
@@ -167,53 +166,54 @@ Users might need to implement their own completion policies for more
If there is an exception thrown inside a
`RepeatCallback`, the
`RepeatTemplate` consults an
`ExceptionHandler` which can decide whether or not to
`ExceptionHandler`, which can decide whether or not to
re-throw the exception.
The following listing shows the `ExceptionHandler` interface definition:
[source, java]
----
public interface ExceptionHandler {
void handleException(RepeatContext context, Throwable throwable)
throws RuntimeException;
throws Throwable;
}
----
A common use case is to count the number of exceptions of a
given type, and fail when a limit is reached. For this purpose Spring
given type and fail when a limit is reached. For this purpose, Spring
Batch provides the `SimpleLimitExceptionHandler` and
slightly more flexible
a slightly more flexible
`RethrowOnThresholdExceptionHandler`. The
`SimpleLimitExceptionHandler` has a limit property
and an exception type that should be compared with the current exception -
all subclasses of the provided type are also counted. Exceptions of the
given type are ignored until the limit is reached, and then rethrown.
Those of other types are always rethrown.
and an exception type that should be compared with the current exception.
All subclasses of the provided type are also counted. Exceptions of the
given type are ignored until the limit is reached, and then they are rethrown.
Exceptions of other types are always rethrown.
An important optional property of the
`SimpleLimitExceptionHandler` is the boolean flag
`useParent`. It is false by default, so the limit is only
`SimpleLimitExceptionHandler` is the boolean flag called
`useParent`. It is `false` by default, so the limit is only
accounted for in the current `RepeatContext`. When
set to true, the limit is kept across sibling contexts in a nested
iteration (e.g. a set of chunks inside a step).
set to `true`, the limit is kept across sibling contexts in a nested
iteration (such as a set of chunks inside a step).
[[repeatListeners]]
=== Listeners
Often it is useful to be able to receive additional callbacks for
cross cutting concerns across a number of different iterations. For this
purpose Spring Batch provides the `RepeatListeners`
interface. The `RepeatTemplate` allows users to
register `RepeatListeners`, and they will be given
Often, it is useful to be able to receive additional callbacks for
cross-cutting concerns across a number of different iterations. For this
purpose, Spring Batch provides the `RepeatListener`
interface. The `RepeatTemplate` lets users
register `RepeatListener` implementations, and they are given
callbacks with the `RepeatContext` and
`RepeatStatus` where available during the
iteration.
The interface looks like this:
The `RepeatListener` interface has the following definition:
[source, java]
@@ -228,14 +228,14 @@ public interface RepeatListener {
----
The `open` and `close` callbacks come before and after the entire
iteration. `before`, `after`
iteration. `before`, `after`,
and `onError` apply to the individual
`RepeatCallback` calls.
Note that when there is more than one listener, they are in a list,
so there is an order. In this case `open` and
Note that, when there is more than one listener, they are in a list,
so there is an order. In this case, `open` and
`before` are called in the same order while
`after`, `onError` and
`after`, `onError`, and
`close` are called in reverse order.
[[repeatParallelProcessing]]
@@ -261,20 +261,20 @@ Implementations of `RepeatOperations` are not
Sometimes there is some business processing that you know you want
to repeat every time it happens. The classic example of this is the
optimization of a message pipeline - it is more efficient to process a
optimization of a message pipeline. It is more efficient to process a
batch of messages, if they are arriving frequently, than to bear the cost
of a separate transaction for every message. Spring Batch provides an AOP
interceptor that wraps a method call in a
`RepeatOperations` for just this purpose. The
`RepeatOperations` object for just this purpose. The
`RepeatOperationsInterceptor` executes the
intercepted method and repeats according to the
`CompletionPolicy` in the provided
`RepeatTemplate`.
Here is an example of declarative iteration using the Spring AOP
The following example shows declarative iteration using the Spring AOP
namespace to repeat a service call to a method called
processMessage (for more detail on how to
configure AOP interceptors see the Spring User Guide):
`processMessage` (for more detail on how to
configure AOP interceptors, see the Spring User Guide):
[source, xml]
@@ -289,20 +289,19 @@ Here is an example of declarative iteration using the Spring AOP
<bean id="retryAdvice" class="org.spr...RepeatOperationsInterceptor"/>
----
The example above uses a default
The preceding example uses a default
`RepeatTemplate` inside the interceptor. To change
the policies, listeners etc. you only need to inject an instance of
the policies, listeners, and other details, you can inject an instance of
`RepeatTemplate` into the interceptor.
If the intercepted method returns `void` then the
If the intercepted method returns `void`, then the
interceptor always returns `RepeatStatus.CONTINUABLE` (so there is a danger of
an infinite loop if the `CompletionPolicy` does not
have a finite end point). Otherwise it returns
have a finite end point). Otherwise, it returns
`RepeatStatus.CONTINUABLE` until the return value from the
intercepted method is null, at which point it returns
`RepeatStatus.FINISHED`. So the business logic inside the target
intercepted method is `null`, at which point it returns
`RepeatStatus.FINISHED`. Consequently, the business logic inside the target
method can signal that there is no more work to do by returning
`null`, or by throwing an exception that is re-thrown by the
`null` or by throwing an exception that is re-thrown by the
`ExceptionHandler` in the provided
`RepeatTemplate`.