From 1129888e121ed4deeddc65e3ce2934f27cd5bc2f Mon Sep 17 00:00:00 2001 From: Jay Bryant Date: Fri, 6 Oct 2017 12:42:20 -0500 Subject: [PATCH] Editing pass for repeat.adoc I edited for readability and consistency and fixed sentence errors. No questions this time. Polishing on Merge --- spring-batch-docs/asciidoc/repeat.adoc | 127 ++++++++++++------------- 1 file changed, 63 insertions(+), 64 deletions(-) diff --git a/spring-batch-docs/asciidoc/repeat.adoc b/spring-batch-docs/asciidoc/repeat.adoc index 539b1e488..2ce1b12cb 100644 --- a/spring-batch-docs/asciidoc/repeat.adoc +++ b/spring-batch-docs/asciidoc/repeat.adoc @@ -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 ---- -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`. -