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

RESOLVED - issue BATCH-512: delegating item reader/writer needs documentation on registering delegate as a Stream.

Browse Source 
Added a couple of sections on registering delegates with the step directly (execution.xml and readersAndWriters.xml).
This commit is contained in:
dsyer
2008-03-28 11:47:42 +00:00
parent 9d35d8c95f
commit bfa98e3bdb
2 changed files with 83 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/src/site/docbook/reference/execution.xml
View File

@@ -1035,6 +1035,46 @@
that are 'retryable'.</para>
</section>
<section>
<title>Registering ItemStreams with the Step</title>
<para>The step has to take care of the
<classname>ItemStream</classname> 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 <classname>ItemStream</classname>
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
<classname>Step</classname> instances have features that allow streams
to be registered with the step when it is configured.</para>
<para>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.:</para>
<programlisting>&lt;bean id="step1" parent="simpleStep"
class="org.springframework.batch.core.step.item.StatefulRetryStepFactoryBean"&gt;
&lt;property name="streams" ref="fileItemReader" /&gt;
&lt;property name="itemReader"&gt;
&lt;bean
class="org.springframework.batch.item.validator.ValidatingItemReader"&gt;
&lt;property name="itemReader" ref="itemReader" /&gt;
&lt;property name="validator" ref="fixedValidator" /&gt;
&lt;/bean&gt;
&lt;/property&gt;
...
&lt;/bean&gt;</programlisting>
<para>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.</para>
</section>
<section>
<title>Intercepting Step Execution</title>

45
docs/src/site/docbook/reference/readersAndWriters.xml
View File

@@ -1114,7 +1114,7 @@
a <classname>PropertyPlaceholderConfigurer</classname> can be used here,
it is not necessary if the system property is always set because the
<classname>ResourceEditor</classname> in Spring already filters and does
placeholder replacement on system properties.) </para>
placeholder replacement on system properties.)</para>
<para>Often in a batch setting it is preferable to parameterise the file
name in the <classname>JobParameters</classname> of the job, instead of
@@ -1130,7 +1130,7 @@
&lt;/bean&gt;</programlisting>
<para>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
<classname>JobParameters</classname> the job is start with, the following
filename will be passed as the <classname>Resource</classname>:
"<filename>//fooJob/fooStep/fileName.txt</filename>". It should be noted
@@ -1913,6 +1913,27 @@ itemReader.close(executionContext);</programlisting>
itemTransformerItemWriter.setDelegate(new BarWriter());
itemTransformerItemWriter.write(new Foo());</programlisting>
<section>
<title>The Delegate Pattern and Registering with the Step</title>
<section>
<para>Note that the <classname>ItemTransformerItemWriter</classname>
and the <classname>CompositeItemWriter</classname> are examples of a
delegation pattern, which is quite common usage in Spring Batch. The
delegates themselves might implement callback interfaces like
<classname>ItemStream</classname> or
<classname>StepListener</classname>. 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
<classname>Step</classname>. Registration is automatic when using the
factory beans (<classname>*StepFactoryBean</classname>) , but only for
the <classname>ItemReader</classname> and
<classname>ItemWriter</classname> injected directly - the delegates
are not known to the step, so they need to be injected as listeners or
streams (or both if appropriate).</para>
</section>
</section>
<section>
<title>Chaining ItemTransformers</title>
@@ -2048,6 +2069,26 @@ itemReader.close(executionContext);</programlisting>
<classname>ValangValidator</classname> 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.</para>
<section>
<title>The Delegate Pattern and Registering with the Step</title>
<section>
<para>Note that the <classname>ValidatingItemReader</classname> is
another example of a delegation pattern, and the delegates themselves
might implement callback interfaces like
<classname>ItemStream</classname> or
<classname>StepListener</classname>. 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
<classname>Step</classname>. Registration is automatic when using the
factory beans (<classname>*StepFactoryBean</classname>) , but only for
the <classname>ItemReader</classname> and
<classname>ItemWriter</classname> injected directly - the delegates
are not known to the step, so they need to be injected as listeners or
streams (or both if appropriate).</para>
</section>
</section>
</section>
<section>