From bfa98e3bdb397ee099772bc34aa69f1bf72c6d05 Mon Sep 17 00:00:00 2001 From: dsyer Date: Fri, 28 Mar 2008 11:47:42 +0000 Subject: [PATCH] RESOLVED - issue BATCH-512: delegating item reader/writer needs documentation on registering delegate as a Stream. Added a couple of sections on registering delegates with the step directly (execution.xml and readersAndWriters.xml). --- docs/src/site/docbook/reference/execution.xml | 40 +++++++++++++++++ .../docbook/reference/readersAndWriters.xml | 45 ++++++++++++++++++- 2 files changed, 83 insertions(+), 2 deletions(-) diff --git a/docs/src/site/docbook/reference/execution.xml b/docs/src/site/docbook/reference/execution.xml index 1a389ee45..4ea7f2e68 100644 --- a/docs/src/site/docbook/reference/execution.xml +++ b/docs/src/site/docbook/reference/execution.xml @@ -1035,6 +1035,46 @@ that are 'retryable'. +
+ Registering ItemStreams with the Step + + The step has to take care of the + ItemStream callbacks at the necessary points in + the flow. This is vital if a step is going to be fail, and might need + to be restarted, because the ItemStream + interface is where the step gets the information it needs about + persistent state between executions. The factory beans that Spring + Batch provides for convenient configuration of + Step instances have features that allow streams + to be registered with the step when it is configured. + + If the ItemReader of ItemWriter themselves implement the + ItemStream interface, then these will be registered automatically. Any + other streams need to be registered separately. This is often the case + where there are indirect dependencies, like delegates being injected + into the reader and writer. To register these they can be injected + into teh factory beans through the streams property, e.g.: + + <bean id="step1" parent="simpleStep" + class="org.springframework.batch.core.step.item.StatefulRetryStepFactoryBean"> + <property name="streams" ref="fileItemReader" /> + <property name="itemReader"> + <bean + class="org.springframework.batch.item.validator.ValidatingItemReader"> + <property name="itemReader" ref="itemReader" /> + <property name="validator" ref="fixedValidator" /> + </bean> + </property> + ... +</bean> + + In the example above the main item reader is being set up to + delegate to a bean called "fileItemReader", which itself is being + registered as a stream directly. The step will now be restartable and + the state of the reader will be correctly persisted in case of a + failure. +
+
Intercepting Step Execution diff --git a/docs/src/site/docbook/reference/readersAndWriters.xml b/docs/src/site/docbook/reference/readersAndWriters.xml index 7b79751c3..e0338205e 100644 --- a/docs/src/site/docbook/reference/readersAndWriters.xml +++ b/docs/src/site/docbook/reference/readersAndWriters.xml @@ -1114,7 +1114,7 @@ a PropertyPlaceholderConfigurer can be used here, it is not necessary if the system property is always set because the ResourceEditor in Spring already filters and does - placeholder replacement on system properties.) + placeholder replacement on system properties.) Often in a batch setting it is preferable to parameterise the file name in the JobParameters of the job, instead of @@ -1130,7 +1130,7 @@ </bean> Assuming a job name of 'fooJob', and a step name of 'fooStep', and - the key-value pair of 'file.name="fileName.txt' is in the + the key-value pair of 'file.name="fileName.txt"' is in the JobParameters the job is start with, the following filename will be passed as the Resource: "//fooJob/fooStep/fileName.txt". It should be noted @@ -1913,6 +1913,27 @@ itemReader.close(executionContext); itemTransformerItemWriter.setDelegate(new BarWriter()); itemTransformerItemWriter.write(new Foo()); +
+ The Delegate Pattern and Registering with the Step + +
+ Note that the ItemTransformerItemWriter + and the CompositeItemWriter are examples of a + delegation pattern, which is quite common usage in Spring Batch. The + delegates themselves might implement callback interfaces like + ItemStream or + StepListener. If they do, and they are being + used in conjunction with Spring Batch Core as part of a step in a job, + then they almost certainly need to be registered manually with the + Step. Registration is automatic when using the + factory beans (*StepFactoryBean) , but only for + the ItemReader and + ItemWriter injected directly - the delegates + are not known to the step, so they need to be injected as listeners or + streams (or both if appropriate). +
+
+
Chaining ItemTransformers @@ -2048,6 +2069,26 @@ itemReader.close(executionContext); ValangValidator that is used to validate an order object. The intent is not to show Valang functionality as much as to show how a validator could be added. + +
+ The Delegate Pattern and Registering with the Step + +
+ Note that the ValidatingItemReader is + another example of a delegation pattern, and the delegates themselves + might implement callback interfaces like + ItemStream or + StepListener. If they do, and they are being + used in conjunction with Spring Batch Core as part of a step in a job, + then they almost certainly need to be registered manually with the + Step. Registration is automatic when using the + factory beans (*StepFactoryBean) , but only for + the ItemReader and + ItemWriter injected directly - the delegates + are not known to the step, so they need to be injected as listeners or + streams (or both if appropriate). +
+