Job Specification Language(JSL)

The job configuration is separated into 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.

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 job element, which is the root element of any JSL file. id attribute should contain a unique identifier for the job. A job can contain listeners (with listeners element) or batch elements. Listeners are notified when job starts or ends, while batch elements are executable parts of a job.

There are three kinds of batch elements: steps, flows, and splits. Steps are 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 job repository is persisted (see section Job Explorer and Job Repository), job restartability can be set with restartable attribute. 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 listeners element. Listeners must implement Summer.Batch.Core.IJobExecutionListener interface and be registered with the corresponding id in Unity container.

Example 4.3. Job Configuration¶

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

IJobExecutionListener interface has two methods, BeforeJob(JobExecution) and AfterJob(JobExecution) which are called respectively before and after the job execution.

AfterJob method is called even when job failed; JobExecution.Status property exposes job status.

Step Element¶

A step is defined using step element and 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. Step is divided in chunks: records are read until chunk size has been reached, then they are processed, and processed items are finally written. Chunks are repeated until there are no more records to read. Each chunk is executed in a transaction.

chunk element has a required attribute, item-count—which specifies the chunk size—, and must contain reader and writer elements. 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 IItemReader interface, the processor must implement IItemProcessor interface, and the writer must implement IItemWriter interface. All must be registered with the corresponding id in Unity container.

Batchlet Steps¶

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

Example 4.5. XML Batchlet Specification¶

<step id="testStep">
    <batchlet ref="testBatchlet" />
</step>

Listeners¶

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

Example 4.6. XML step configuration with listener¶

<step id="testStep">
    <chunk>
        <reader ref="testReader" />
        <processor ref="testProcessor" />
        <writer ref="testProcessor" />
    </chunk>
    <listeners>
        <listener ref="myStepListener"/>
    </listeners>
</step>

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

Partitioning¶

Partitioning allows execution of several instances of a step using a task executor. A partitioner implementing 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:

Example 4.7. XML Partition Specification¶

<step id="testStep">
    …
    <partition>
        <mapper ref="testPartitioner" grid-size="10" />
    </partition>
</step>

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

Note

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

Flow Element¶

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 flow will itself transition to an element in its parent.

Example 4.8. XML Flow Specification¶

<flow id="testFlow" next="…">
    <step id="testStep1" next="subFlow">
        …
    </step>
    <flow id="subFlow">
        <step id="testStep2">
            …
        </step>
    </flow>
</flow>

Split Element¶

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

Example 4.9. XML Split Specification¶

<split id="testSplit" next="…">
    <flow id="testFlow">
        …
    </flow>
    <step id="testStep">
        …
    </step>
</split>

Note

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

Batch Control Flow¶

The execution of batch elements in jobs and flows follows a certain control flow. First element is executed and then 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 next attribute, which contains the id of next batch element to execute.

Example 4.10. XML Two step Specification¶

<job id="testJobWithTwoSteps">
    <step id="step1" next="step2">
        …
    </step>
    <step id="step2">
        …
    </step>
</job>

Note

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

Conditional Control Flow¶

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

Example 4.11. XML conditional step Specification¶

<job id="testJobWithConditionalSteps">
    <step id="step1">
        …
        <next on="FAILED" to="step2"/>
        <next on="*" to="step3"/>
    </step>
    <step id="step2">
        …
    </step>
    <step id="step3">
        …
    </step>
</job>

Note

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

End and Fail Control flow¶

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

Example 4.12. XML conditional step Specification¶

<job id="testJobWithEndFailSteps">
    <step id="step1">
        …
        <fail on="SomeFailureCode"/>
        <next on="*" to="step2"/>
    </step>
    <step id="step2">
        …
        <end on="SomeTerminationCode"/>
        <next on"*" to="step3"/>
    </step>
    <step id="step3">
        …
    </step>
</job>