Back to Summer Batch home page

Chapter 4. Configuration

Table of Contents

The job configuration is separated in two: a part describes the content of the job (e.g., steps, flows), while the other defines the artifacts used by the job (e.g., readers, writers) and their fine-grained properties. The former is declared in XML using a subset of the job specification language defined in JSR-352 and the latter is declared in C# using the Unity dependency injection.

Job Specification Language (JSL)

XSL Configuration

The XML Specification language for Summer Batch Configuration can be found at http://www.summerbatch.com/xmlns/SummerBatchXML_1_0.xsd. It can be declared on the specification top element like this:

Example 4.1. XSL declaration configuration:

<job id="SampleJob"
    xmlns="http://www.summerbatch.com/xmlns"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.summerbatch.com/xmlns
        http://www.summerbatch.com/xmlns/SummerBatchXML_1_0.xsd">

For readability, this XML setup will not be repeated in the examples of this section.

Job Configuration

A job is defined using the job element, which is the root element of any JSL file. The id attribute should contain a unique identifier for the job. A job can contain listeners (with the listeners element) or batch elements. Listeners are notified when the job starts or ends, while batch elements are the executable parts of a job.

There are three kinds of batch elements: steps, flows, and splits. Steps are the base executables of any job, and are responsible for reading, processing, and reading data. Flows contains other batch elements that are executed using regular flow control as explained in section Batch Control Flow. Splits contains other batch elements that are executed using a task executor (which, for instance, can execute them in parallel, see section Task Executor for more information).

Restartability

If the job repository is persisted (see section Job Explorer and Job Repository), the job restartability can be set with the restartable attribute. The default value is true.

Example 4.2. A Non Restartable Job

<job id="testJob" restartable="false"></job>

Job Listeners

Job listeners can be registered within the listeners element. The listeners must implement the Summer.Batch.Core.IJobExecutionListener interface and be registered with the corresponding id in the Unity container.

Example 4.3. Job Configuration

<job id="testJob">
    <listeners>
        <listener id="testListener" />
    </listeners></job>

The IJobExecutionListener interface has two methods, BeforeJob(JobExecution) and AfterJob(JobExecution) which are called respectively before and after the job execution. The AfterJob method is called even when the job failed; the JobExecution.Status property exposes the job status.

A step is defined using the step element and the id attribute must be specified. There are two kinds of steps: chunk steps and batchlet steps. Steps can also have listeners and be partitioned.

Chunk Steps

A chunk step has a fixed size and is composed of a reader, a writer, and (optionally) a processor. The step is divided in chunks: records are read until the chunk size has been reached, then they are processed, and the processed items are finally written. Chunks are repeated until there are no more records to read. Each chunk is executed in a transaction.

The chunk element has a required attribute, item-count—which specifies the chunk size—, and must contain the reader and writer elements. The processor element is optional.

Example 4.4. XML Chunk Specification

<step id="testStep">
    <chunk item-count="10">
        <reader ref="testReader" />
        <processor ref="testProcessor" />
        <writer ref="testProcessor" />
    </chunk>
</step>

The reader must implement the IItemReader interface, the processor must implement the IItemProcessor interface, and the writer must implement the IItemWriter interface. All must be registered with the corresponding id in the Unity container.

Batchlet Steps

A batchlet is a step that is entirely delegated to a C# class, that must implement the ITasklet interface. The Execute method will be executed repeatedly until it returns RepeatStatus.Finished. As with chunks, each call is done in a transaction.


As with jobs, listeners can be registered with a step using the listeners element. The listeners must implement the IStepExecutionListener interface and be registered with the corresponding id in the Unity container.


The IStepExecutionListener interface has two methods, BeforeStep(StepExecution) and AfterStep(StepExecution) which are called respectively before and after the step execution. The AfterStep must return an exit status. This Exit status wraps an Exit code, which can be used for step flow control.

Partitioning allows the execution of several instances of a step using a task executor. A partitioner, implementing the IPartitioner interface, creates several step execution contexts, which are used to create different instances of the step. To partition a step, add a partition element:


The mapper element specifies the Unity id of the partitioner with the ref attribute and the grid size (which will be provided to the partitioner as a parameter) with the grid-size attribute. If not specified, the default grid size is 6.

[Note]Note

The way the different step instances are executed depends entirely on the task executor. See section Task Executor for more information.

The flow element gathers batch elements together and execute them using standard control flow (see section Batch Control Flow). Elements in a flow can only have transitions to elements in the same flow, but the flow will itself transition to an element in its parent.


The split element gathers batch elements together and execute them using a task executor, thus elements in a split do not have specified transitions.


[Note]Note

The way the different batch elements are executed depends entirely on the task executor. See section Task Executor for more information.

The execution of batch elements in jobs and flows follows a certain control flow. The first element is executed, then the next element is chose using a set of rules explained in this section.

Straight Control Flow

The simplest control flow executes the elements in a predetermined sequence. This is achieved with the next attribute, which contains the id of the next batch element to execute.


[Note]Note

The first batch element to appear in the job will always be the first step to be executed. The other ones may appear in any order, as only the next attribute is relevant. However, it is strongly advised to write them in the correct order.

The batch element to execute can also depend on the status of the execution of the previous batch element by using the next element instead of the next attribute. The next element has two required attributes: on and to. The on attributes contains a string representing a status and the to contains the id of a batch element. The next elements are processed in order: the first that matches the status of the previous execution will designate the next element. If no element matches, the job fails.


[Note]Note

Here, FAILED is the standard Summer Batch code for step failure. The * value in the second next element is the usual wildcard for any value. The status of a step can be customized using the AfterStep method of the step listener.

In addition to the next element, end or fail elements can be used. Both terminate the job, but the latter forces a failure.


Back to Summer Batch home page