From ed7c1df278164dac8fa11281cc6e9882a66e67fe Mon Sep 17 00:00:00 2001 From: lucasward Date: Fri, 27 Jun 2008 04:29:15 +0000 Subject: [PATCH] BATCH-691:Corrected sections that are out of date with the latest 1.1 changes. --- docs/src/site/docbook/reference/core.xml | 173 ++++++++++++++--------- 1 file changed, 107 insertions(+), 66 deletions(-) diff --git a/docs/src/site/docbook/reference/core.xml b/docs/src/site/docbook/reference/core.xml index a39de91e6..edabf423b 100644 --- a/docs/src/site/docbook/reference/core.xml +++ b/docs/src/site/docbook/reference/core.xml @@ -76,13 +76,13 @@ with out of the box implementations, but an architecture team may make specific implementations that better address their specific needs. Yellow represents the pieces that must be configured by a developer. For example, - they need to configure their job schedule so that the job is kicked off at - the appropriate time. They also need to create a job configuration that - defines how their job will be run. It is also worth noting that the + a job schedule needs to be configured so that the job is kicked off at the + appropriate time. A job configuration file also needs to be created, which + defines how a job will be run. It is also worth noting that the ItemReader and ItemWriter - used by an application may just as easily be a custom one made by the - developer for the specific batch job, rather than one provided by Spring - Batch or even an architecture team. + used by an application may just as easily be a custom one made by a + developer for their specific batch job, rather than one provided by Spring + Batch or an architecture team. The Batch Application Style is organized into four logical tiers, which include Run, Job, Application, and Data. The primary goal for @@ -113,14 +113,14 @@ Application Tier: The Application Tier contains components required to execute the - program. It contains specific tasklets that address the required - batch functionality and enforces policies around a tasklet execution - (e.g., commit intervals, capture of statistics, etc.) + program. It contains specific tasks that address required batch + functionality and enforces policies around execution (e.g., commit + intervals, capture of statistics, etc.) Data Tier: The Data Tier - provides the integration with the physical data sources that might + provides integration with the physical data sources that might include databases, files, or queues. @@ -130,11 +130,11 @@ Job Stereotypes This section describes stereotypes relating to the concept of a - batch job. A job is an entity that encapsulates an entire batch process. - As is common with other Spring projects, a Job will - be wired together via an XML configuration file. This file may be referred - to as the "job configuration". However, Job is just - the top of an overall hierarchy: + batch job. A Job is an entity that encapsulates an + entire batch process. As is common with other Spring projects, a + Job will be wired together via an XML configuration + file. This file may be referred to as the "job configuration". However, + Job is just the top of an overall hierarchy: @@ -244,9 +244,9 @@ 01-01-2008 and another that was started with a parameter of 01-02-2008. Thus, the contract can be defined as: JobInstance = Job + JobParameters. - This allows you to effectively control how you define a - JobInstance, since you control what parameters - are passed in. + This allows a developer to effectively control how you a + JobInstance is defined, since they control what + parameters are passed in.
@@ -256,19 +256,21 @@ concept of a single attempt to run a Job. An execution may end in failure or success, but the JobInstance corresponding to a given execution - will not be marked as complete unless the execution completes - successfully. For instance, if we have a - JobInstance of the EndOfDay job for 01-01-2008, - as described above, that fails to successfully complete its work the - first time it is run, when we attempt to run it again (with the same job - parameters of 01-01-2008), a new job execution will be created. + will not be considered complete unless the execution completes + successfully. Using the EndOfDay Job described + above as an example, consider a JobInstance for 01-01-2008 that failed + the first time it was run. If it is ran again, with the same job + parameters as the first run (01-01-2008), a new JobExecution will be + created. However, there will still be only one + JobInstance. - A Job defines what a job is and defines how it is to be executed, - and JobInstance is a purely organization object - to group executions together, primarily to enable correct restart. A - JobExecution, however, is the primary storage - mechanism for what actually happened during a run, and as such contains - many more properties that must be controlled and persisted: + A Job defines what a job is and how it is + to be executed, and JobInstance is a purely + organizational object to group executions together, primarily to enable + correct restart semantics. A JobExecution, + however, is the primary storage mechanism for what actually happened + during a run, and as such contains many more properties that must be + controlled and persisted: JobExecution properties @@ -307,6 +309,17 @@ exit code that will be returned to the caller. See chapter 5 for more details. + + + createTime + + A java.util.Date representing the + current system time when the JobExecution was first persisted. + The job may not have been started yet (and thus has no start + time), but it will always have a createTime, which is required + by the framework for managing job level + ExecutionContexts. +
@@ -398,7 +411,7 @@ - extra columns in the table have been removed for added + extra columns in the tables have been removed for added clarity. @@ -412,9 +425,10 @@ requirement that one JobInstance be kicked off after another, unless there is potential for the two jobs to attempt to access the same data, causing issues with locking at the database level. - It is entirely up to the scheduler to determine when to run. Since - they're separate JobInstances, Spring Batch will make no attempt to stop - them from being run concurrently. (Attempting to run the same + It is entirely up to the scheduler to determine when a + Job should be run. Since they're separate + JobInstances, Spring Batch will make no attempt to stop them from being + run concurrently. (Attempting to run the same JobInstance while another is already running will result in a JobExecutionAlreadyRunningException being thrown) There should now be an extra entry in both the @@ -548,18 +562,19 @@ Step Stereotypes A Step is a domain object that encapsulates - an independent, sequential phase of a batch job. Therefore, every Job is - composed entirely of one or more steps. A Step - should be thought of as a unique processing stream that will be executed - in sequence. For example, if you have one step that loads a file into a - database, another that reads from the database, validates the data, - preforms processing, and then writes to another table, and another that - reads from that table and writes out to a file. Each of these steps will - be performed completely before moving on to the next step. The file will - be completely read into the database before step 2 can begin. As with - Job, a Step has an - individual StepExecution that corresponds with a - unique JobExecution: + an independent, sequential phase of a batch job. Therefore, every + Job is composed entirely of one or more steps. A + Step should be thought of as a unique processing + stream that will be executed in sequence. For example, if you have one + step that loads a file into a database, another that reads from the + database, validates the data, preforms processing, and then writes to + another table, and another that reads from that table and writes out to a + file. Each of these steps will be performed completely before moving on to + the next step. The file will be completely read into the database before + step 2 can begin. As with Job, a + Step has an individual + StepExecution that corresponds with a unique + JobExecution: @@ -610,7 +625,10 @@ invocation of the batch framework, but they will all correspond to the same JobInstance, just as multiple JobExecutions belong to the same - JobInstance. + JobInstance. However, if a step fails to execute + because the step before it fails, there will be no execution persisted + for it. An execution will only be created when the + Step is actually started. Step executions are represented by objects of the StepExecution class. Each execution contains a @@ -682,6 +700,27 @@ The number of items that have been processed for this execution. + + + rollbackCount + + The number of times the business transaction controlled + by the Step has been rolled back. + + + + readSkipCount + + The number of times read has + failed, resulting in a skipped item. + + + + writeSkipCount + + The number of times write has + failed, resulting in a skipped item. + @@ -693,25 +732,27 @@ An ExecutionContext represents a collection of key/value pairs that are persisted and controlled by the framework in order to allow developers a place to store persistent state that is - scoped to a StepExecution. For those familiar - with Quartz, it is very similar to JobDataMap. - The best usage example is restart. Using flat file input as an example, - while processing individual lines, the framework periodically persists - the ExecutionContext at commit points. This - allows the ItemReader to store its state in case - a fatal error occurs during the run, or even if the power goes out. All - that is needed is to put the current number of lines read into the - context, and the framework will do the rest: + scoped to a StepExecution or + JobExecution. For those familiar with Quartz, it + is very similar to JobDataMap. The best usage + example is restart. Using flat file input as an example, while + processing individual lines, the framework periodically persists the + ExecutionContext at commit points. This allows + the ItemReader to store its state in case a fatal + error occurs during the run, or even if the power goes out. All that is + needed is to put the current number of lines read into the context, and + the framework will do the rest: executionContext.putLong(getKey(LINES_READ_COUNT), reader.getPosition()); The call above will store the current number of lines read into the ExecutionContext. It should be made just before the framework commits. Being notified before a commit requires one of the various - StepListeners, or an ItemStream, which are discussed in more detail - later in this guide. When the ItemReader is - opened, it can check to see if it has any stored state in the context, - and initialize itself from there: + StepListeners, or an ItemStream, which are + discussed in more detail later in this guide. When the + 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))) { log.debug("Initializing for restart. Restart data is: " + executionContext); @@ -820,11 +861,11 @@ } This interface is very necessary due to the nature of Spring itself. - Because we can't guarantee one ApplicationContext - equals one Job, an abstraction is needed to obtain - a Job for a given name. It becomes especially - useful when launching jobs from within a Java EE application - server. + Because it can't be guaranteed that one + ApplicationContext equals one + Job, an abstraction is needed to obtain a + Job for a given name. It becomes especially useful + when launching jobs from within a Java EE application server.
@@ -834,7 +875,7 @@ the retrieval of input for a Step, one item at a time. When the ItemReader has exhausted the items it can provide, it will indicate this by returning null. More details - about the ItemReader interface and it's various + about the ItemReader interface and its various implementations can be found in Chapter 3.