From 751246a5892bed364044ca2ae8c953d28024e748 Mon Sep 17 00:00:00 2001 From: dhgarrette Date: Wed, 3 Jun 2009 14:33:27 +0000 Subject: [PATCH] BATCH-1270: Update documentation for formatting consistency --- src/site/docbook/reference/domain.xml | 74 ++++---- .../docbook/reference/spring-batch-intro.xml | 10 +- src/site/docbook/reference/whatsnew.xml | 161 +++++++----------- 3 files changed, 104 insertions(+), 141 deletions(-) diff --git a/src/site/docbook/reference/domain.xml b/src/site/docbook/reference/domain.xml index 28df84eda..f646eb6b2 100644 --- a/src/site/docbook/reference/domain.xml +++ b/src/site/docbook/reference/domain.xml @@ -44,12 +44,18 @@ processing needs. - + + + + + Figure 2.1: Batch Stereotypes @@ -77,7 +83,7 @@ + scale="40" /> @@ -107,14 +113,11 @@ namespace abstracts away the need to instantiate it directly. Instead, the <job> tag can be used: - - <job id="footballJob"> + <job id="footballJob"> <step id="playerload" next="gameLoad"/> <step id="gameLoad" next="playerSummarization"/> <step id="playerSummarization"/> - </job> - - +</job>
JobInstance @@ -176,7 +179,7 @@ + scale="40" /> @@ -561,11 +564,11 @@ + scale="40" /> -
+
StepExecution A StepExecution represents a single attempt @@ -863,7 +866,7 @@ ItemReader is opened, it can check to see if it has any stored state in the context, and initialize itself from there: - if (executionContext.containsKey(getKey(LINES_READ_COUNT))) { + if (executionContext.containsKey(getKey(LINES_READ_COUNT))) { log.debug("Initializing for restart. Restart data is: " + executionContext); long lineCount = executionContext.getLong(getKey(LINES_READ_COUNT)); @@ -872,9 +875,9 @@ Object record = ""; while (reader.getPosition() < lineCount && record != null) { - record = readLine(); + record = readLine(); } - } +} In this case, after the above code is executed, the current line will be 40,322, allowing the Step to start again @@ -914,12 +917,9 @@ StepExecution. For example, consider the following code snippet: - - ExecutionContext ecStep = stepExecution.getExecutionContext(); - ExecutionContext ecJob = jobExecution.getExecutionContext(); - //ecStep does not equal ecJob - - + ExecutionContext ecStep = stepExecution.getExecutionContext(); +ExecutionContext ecJob = jobExecution.getExecutionContext(); +//ecStep does not equal ecJob As noted in the comment, ecStep will not equal ecJob; they are two different ExecutionContexts. The one scoped to the @@ -942,25 +942,21 @@ JobExecution implementations are persisted by passing them to the repository: - - <job-repository id="jobRepository"/> - - + <job-repository id="jobRepository"/>
-
+
JobLauncher JobLauncher represents a simple interface for launching a Job with a given set of JobParameters: - public interface JobLauncher { + public interface JobLauncher { public JobExecution run(Job job, JobParameters jobParameters) throws JobExecutionAlreadyRunningException, JobRestartException; -} - +} It is expected that implementations will obtain a valid JobExecution from the @@ -968,7 +964,7 @@ Job.
-
+
Item Reader ItemReader is an abstraction that represents @@ -980,7 +976,7 @@ linkend="readersAndWriters" />.
-
+
Item Writer ItemWriter is an abstraction that represents @@ -989,10 +985,10 @@ next, only the item that was passed in its current invocation. More details about the ItemWriter interface and its various implementations can be found in + linkend="readersAndWriters" />.
-
+
Item Processor ItemProcessor is an abstraction that @@ -1006,7 +1002,7 @@ found in .
-
+
Batch Namespace Many of the domain concepts listed above need to be configured in a @@ -1015,7 +1011,7 @@ bean definition, a namespace has been provided for ease of configuration: - <beans:beans xmlns="http://www.springframework.org/schema/batch" + <beans:beans xmlns="http://www.springframework.org/schema/batch" xmlns:beans="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" @@ -1025,14 +1021,14 @@ http://www.springframework.org/schema/batch/spring-batch-2.0.xsd"> <job id="ioSampleJob"> - <step id="step1"> - <tasklet> - <chunk reader="itemReader" writer="itemWriter" commit-interval="2"/> - </tasklet> - </step> + <step id="step1"> + <tasklet> + <chunk reader="itemReader" writer="itemWriter" commit-interval="2"/> + </tasklet> + </step> </job> - </beans:beans> +</beans:beans> As long as the batch namespace has been declared, any of its elements can be used. More information on configuring a diff --git a/src/site/docbook/reference/spring-batch-intro.xml b/src/site/docbook/reference/spring-batch-intro.xml index 0bbd577b7..68a5eea0b 100644 --- a/src/site/docbook/reference/spring-batch-intro.xml +++ b/src/site/docbook/reference/spring-batch-intro.xml @@ -37,7 +37,7 @@ high-volume batch jobs can leverage the framework in a highly scalable manner to process significant volumes of information. -
+
Background While open source software projects and associated communities have @@ -77,7 +77,7 @@ will benefit from Spring Batch.
-
+
Usage Scenarios A typical batch program generally reads a large number of records @@ -165,7 +165,7 @@
-
+
Spring Batch Architecture Spring Batch is designed with extensibility and a diverse group of @@ -174,12 +174,12 @@ developers. + format="PNG" scale="40" width="35%" /> + format="PNG" scale="40" scalefit="" width="35%" /> Figure 1.1: Spring Batch Layered diff --git a/src/site/docbook/reference/whatsnew.xml b/src/site/docbook/reference/whatsnew.xml index c97dd950c..c090cdd2f 100644 --- a/src/site/docbook/reference/whatsnew.xml +++ b/src/site/docbook/reference/whatsnew.xml @@ -32,7 +32,7 @@ -
+
Java 5 The 1.x releases of Spring Batch were all based on Java 1.4. This @@ -43,38 +43,33 @@ work with have been updated to support generic types. As an example, the ItemReader interface from 1.1 is below: - - public interface ItemReader { + public interface ItemReader { Object read() throws Exception; void mark() throws MarkFailedException; void reset() throws ResetFailedException; - } - - +} As you can see, the read method returns an Object. The 2.0 version is below: - - public interface ItemReader<T> { + public interface ItemReader<T> { T read() throws Exception, UnexpectedInputException, ParseException; - } - - +} As you can see, ItemReader now supports the - generic type, T, which is returned from read. You may also notice that - mark and reset have been - removed. This is due to step processing strategy changes, which are - discussed below. Many other interfaces have been similarly updated. + generic type, T, which is returned from read. You + may also notice that mark and + reset have been removed. This is due to step + processing strategy changes, which are discussed below. Many other + interfaces have been similarly updated.
-
+
Chunk Oriented Processing Previously, the default processing strategy provided by Spring Batch @@ -83,13 +78,13 @@ @@ -102,40 +97,32 @@ ItemWriter will each be called 5 times. This is illustrated in a simplified code example below: - - for(int i = 0; i < commitInterval; i++){ + for(int i = 0; i < commitInterval; i++){ Object item = itemReader.read(); itemWriter.write(item); - } - - +} Both the ItemReader and ItemWriter interfaces were completely geared toward this approach: - - public interface ItemReader { + public interface ItemReader { Object read() throws Exception; void mark() throws MarkFailedException; void reset() throws ResetFailedException; - } +} - - - public interface ItemWriter { + public interface ItemWriter { void write(Object item) throws Exception; void flush() throws FlushFailedException; void clear() throws ClearFailedException; - } - - +} Because the 'scope' of the processing was one item, supporting rollback scenarios required additional methods, which is what @@ -158,13 +145,13 @@ + scale="80" width="" /> + scale="60" width="60%" /> @@ -173,37 +160,28 @@ aggregated into a list, that will ultimately be written out, as the simplified example below illustrates: - - List items = new Arraylist(); - for(int i = 0; i < commitInterval; i++){ + List items = new Arraylist(); +for(int i = 0; i < commitInterval; i++){ items.add(itemReader.read()); - } - itemWriter.write(items); - - +} +itemWriter.write(items); This approach not only allows for much simpler processing and scalability approaches, it also makes the ItemReader and ItemWriter interfaces much cleaner: - - public interface ItemReader<T> { + public interface ItemReader<T> { T read() throws Exception, UnexpectedInputException, ParseException; - } +} - - - - public interface ItemWriter<T> { + public interface ItemWriter<T> { void write(List<? extends T> items) throws Exception; - } - - +} As you can see, the interfaces no longer contain the mark, reset, @@ -222,7 +200,7 @@ linkend="chunkOrientedProcessing" />. Reader and writer implementation information can be found in . -
+
ItemProcessor Previously, Steps had only two @@ -231,12 +209,12 @@ - - @@ -248,12 +226,12 @@ + scale="80" width="70%" /> + scale="40" width="" /> @@ -269,60 +247,52 @@ - + - +
-
- Configuration enhancements +
+ Configuration Enhancements Until 2.0, the only option for configuring batch jobs has been normal spring bean configuration. However, in 2.0 there is a new namespace for configuration. For example, in 1.1, configuring a job looked like the following: - - <bean id="footballJob" - class="org.springframework.batch.core.job.SimpleJob"> + <bean id="footballJob" + class="org.springframework.batch.core.job.SimpleJob"> <property name="steps"> - <list> - <!-- Step Bean details ommitted for clarity --> - <bean id="playerload" parent="simpleStep" /> - <bean id="gameLoad" parent="simpleStep" /> - <bean id="playerSummarization" parent="simpleStep" /> - </list> + <list> + <!-- Step Bean details ommitted for clarity --> + <bean id="playerload" parent="simpleStep" /> + <bean id="gameLoad" parent="simpleStep" /> + <bean id="playerSummarization" parent="simpleStep" /> + </list> </property> <property name="jobRepository" ref="jobRepository" /> - </bean> - - +</bean> In 2.0, the equivalent would be: - - <job id="footballJob"> + <job id="footballJob"> <step id="playerload" next="gameLoad"/> <step id="gameLoad" next="playerSummarization"/> <step id="playerSummarization"/> - </job> - - +</job> More information on how to configure Jobs and Steps with the new namespace can be found in , and .
-
- Meta Data access improvements +
+ Meta Data Access Improvements The JobRepository interface represents basic CRUD operations with Job meta-data. However, it may @@ -338,7 +308,7 @@ + scale="60" width="" /> @@ -349,7 +319,7 @@ in.
-
+
Non Sequential Step Execution 2.0 has also seen improvements in how steps can be configured. @@ -358,12 +328,12 @@ + scale="50" /> + scale="50" width="" /> @@ -372,35 +342,32 @@ + scale="50" width="" /> + scale="50" width="" /> This new 'conditional flow' support is made easy to configure via the new namespace: - - <job id="job"> + <job id="job"> <step id="stepA"> - <next on="FAILED" to="stepB" /> - <next on="*" to="stepC" /> + <next on="FAILED" to="stepB" /> + <next on="*" to="stepC" /> </step> <step id="stepB" next="stepC" /> <step id="stepC" /> - </job> - - +</job> More details on how to configure non sequential steps can be found in .
-
+
Scalability Spring Batch 1.x was always intended as a single VM, possibly @@ -412,7 +379,7 @@ are two approaches to scalability: remote chunking, and partitioning. -
+
Remote Chunking Remote chunking is a technique for dividing up the work of a step @@ -429,7 +396,7 @@ be found in
-
+
Partitioning Partitioning is an alternative approach which in contrast depends