Listener

Overview

A listener is an interface for inserting processing before and after executing a job or a step.

Since this function works differently for chunk model and tasket model, respective explanations are given.

A listener consists of multiple interfaces, respective roles are explained here. Subsequently, how to set and implement a listener is explained.

Types of listener

A lot of listener interfaces are defined in Spring Batch. Not everything is explained here, however, we will focus on the items with high usage.

A listener is roughly divided into 2 types.

JobListener: An interface to insert the processing for execution of the job
StepListener: An interface to insert the processing for execution of the step

About JobListener

An interface called JobListener does not exist in Spring Batch. It is conveniently described in this guideline for the comparison with StepListener.
Java Batch(jBatch) has an interface called javax.batch.api.listener.JobListener, so care should be taken to avoid mistakes at the time of implementation. Further, StepListener also consists of interface with same name but different signature (javax.batch.api.listener.StepListener), so it is necessary to take adequate precautions.

JobListener

JobListener interface consists of only one JobExecutionListener.

JobExecutionListener: Process is inserted prior to starting a job and after terminating a job.

JobExecutionListener interface

public interface JobExecutionListener {
  void beforeJob(JobExecution jobExecution);
  void afterJob(JobExecution jobExecution);
}

StepListener

There are many types of interface of StepListener as below.

StepListener: Marker interfaces of various listeners will be introduced later.

StepExecutionListener: Inserts process before and after step execution.

StepExecutionListener interface

public interface StepExecutionListener extends StepListener {
  void beforeStep(StepExecution stepExecution);
  ExitStatus afterStep(StepExecution stepExecution);
}

ChunkListener: A process is inserted before and after processing one chunk and when an error occurs.

ChunkListener interface

public interface ChunkListener extends StepListener {
  static final String ROLLBACK_EXCEPTION_KEY = "sb_rollback_exception";
  void beforeChunk(ChunkContext context);
  void afterChunk(ChunkContext context);
  void afterChunkError(ChunkContext context);
}

Uses of ROLLBACK_EXCEPTION_KEY

It is used when the exception occurred is to be fetched by afterChunkError method. If an error occurs during chunk process, Spring Batch uses sb_rollback_exception key in ChunkContext to call ChunkListener after storing the exception which can be accessed as below.

Usage example

public void afterChunkError(ChunkContext context) {
    logger.error("Exception occurred while chunk. [context:{}]", context,
            context.getAttribute(ChunkListener.ROLLBACK_EXCEPTION_KEY));
}

For exception handling, refer Exception handling using ChunkListener interface

ItemReadListener: Inserts a process before and after ItemReader fetches one data record and when an error occurs.

ItemReadListener interface

public interface ItemReadListener<T> extends StepListener {
  void beforeRead();
  void afterRead(T item);
  void onReadError(Exception ex);
}

ItemProcessListener: Inserts a process before and after ItemProcessor processes one data record and when an error occurs.

ItemProcessListener interface

public interface ItemProcessListener<T, S> extends StepListener {
  void beforeProcess(T item);
  void afterProcess(T item, S result);
  void onProcessError(T item, Exception e);
}

ItemWriteListener: Inserts a process before and after ItemWriter outputs one chunk and when an error occurs.

ItemWriteListener interface

public interface ItemWriteListener<S> extends StepListener {
  void beforeWrite(List<? extends S> items);
  void afterWrite(List<? extends S> items);
  void onWriteError(Exception exception, List<? extends S> items);
}

This guideline does not explain following listeners.

Retry type listener
Skip type listener

These listeners are intended to be used for exception handling, however, the policy of these guidelines is not to perform exception handling using these listeners. For details, refer Exception handling.

How to use

Explanation is given about how to implement and set a listener.

Implementation of a listener

Explanation is given about how to implement and set a listener.

Implement the listener interface with implements.
Implement components with method-based annotation.

The selection of type of implementation is based on the role of listener. Criteria will be described later.

When an interface is to be implemented

Various listener interfaces are implemented by using implements. Multiple interfaces can be implemented at the same time based on requirement. Implementation example is shown below.

Implementation example for JobExecutionListener

@Component
public class JobExecutionLoggingListener implements JobExecutionListener { // (1)

    private static final Logger logger =
            LoggerFactory.getLogger(JobExecutionLoggingListener.class);

    @Override
    public void beforeJob(JobExecution jobExecution) { // (2)
        logger.info("job started. [JobName:{}]", jobExecution.getJobInstance().getJobName());
    }

    @Override
    public void afterJob(JobExecution jobExecution) { // (3)

        logger.info("job finished.[JobName:{}][ExitStatus:{}]", jobExecution.getJobInstance().getJobName(),
                jobExecution.getExitStatus().getExitCode());
    }
}

Configuration example of listener

<batch:job id="chunkJobWithListener" job-repository="jobRepository">
     <batch:step id="chunkJobWithListener.step01">
         <batch:tasklet transaction-manager="jobTransactionManager">
             <batch:chunk reader="reader" processor="processor"
                          writer="writer" commit-interval="10"/>
             <batch:listeners>
                 <batch:listener ref="loggingEachProcessInStepListener"/>
             </batch:listeners>
         </batch:tasklet>
     </batch:step>
     <batch:listeners>
         <batch:listener ref="jobExecutionLoggingListener"/> <!-- (4) -->
     </batch:listeners>
 </batch:job>

Description
Sr. No.	Description
(1)	Implement `JobExecutionListener` using `implements`.
(2)	Implement `beforeJob` method defined by `JobExecutionListener`. In this example, job start log is output.
(3)	Implement `afterJob` method defined by `JobExecutionListener`. In this example, job end log is output.
(4)	Set the listener implemented in (1), in `<listeners>` tag of Bean definition. Details of setup method are explained in Listener settings.

Listener support class

When multiple listener interfaces are set to implements, blank implementation is required to be done for the components which are not necessary for the process. Support classes wherein blank implementation is performed are provided in Spring Batch in order to simplify this operation. Please note that support classes may be used instead of interfaces, and extends is used instead of implements.

Support class

org.springframework.batch.core.listener.ItemListenerSupport
org.springframework.batch.core.listener.StepListenerSupport

When annotations are assigned

Annotations corresponding to various listener interfaces are assigned. Multiple annotations can also be implemented as required.

Correspondence table with listener interface
Listener interface	Annotation
JobExecutionListener	`@beforeJob` `@afterJob`
StepExecutionListener	`@BeforeStep` `@AfterStep`
ChunkListener	`@BeforeChunk` `@AfterChunk` `@afterChunkError`
ItemReadListener	`@BeforeRead` `@AfterRead` `@OnReadError`
ItemProcessListener	`@beforeProcess` `@afterProcess` `@onProcessError`
ItemWriteListener	`@BeforeWrite` `@AfterWrite` `@OnWriteError`

These annotations work for the target scope by assigning them to the implementation method which is divided into components. Implementation example is given below.

Implementation example for ItemProcessor wherein the annotation is assigned

@Component
public class AnnotationAmountCheckProcessor implements
        ItemProcessor<SalesPlanDetail, SalesPlanDetail> {

    private static final Logger logger =
            LoggerFactory.getLogger(AnnotationAmountCheckProcessor.class);

    @Override
    public SalesPlanDetail process(SalesPlanDetail item) throws Exception {
        if (item.getAmount().signum() == -1) {
            throw new IllegalArgumentException("amount is negative.");
        }
        return item;
    }

    // (1)
    /*
    @BeforeProcess
    public void beforeProcess(Object item) {
        logger.info("before process. [Item :{}]", item);
    }
    */

    // (2)
    @AfterProcess
    public void afterProcess(Object item, Object result) {
        logger.info("after process. [Result :{}]", result);
    }

    // (3)
    @OnProcessError
    public void onProcessError(Object item, Exception e) {
        logger.error("on process error.", e);
    }
}

Configuration example of listener

<batch:job id="chunkJobWithListenerAnnotation" job-repository="jobRepository">
    <batch:step id="chunkJobWithListenerAnnotation.step01">
        <batch:tasklet transaction-manager="jobTransactionManager">
            <batch:chunk reader="reader"
                         processor="annotationAmountCheckProcessor"
                         writer="writer" commit-interval="10"/>  <! -- (4) -->
        </batch:tasklet>
    </batch:step>
</batch:job>

Description
Sr. No.	Description
(1)	When the annotation is used for implementation, only the annotations required at the time for the processing should be assigned. In this example, since no operation is required prior to processing of ItemProcess, the implementation wherein `@beforeProcess` is assigned, becomes unnecessary.
(2)	Implement the process to be performed after the processing of ItemProcess. In this example, process results are output in a log.
(3)	Implement processing when an error occurs in ItemProcess. Exception generated in this example is output in a log.
(4)	Set ItemProcess wherein the listener is implemented by using annotation in `<chunk>` tag. Unlike listener interface, the listener is automatically registered even when it is not set in `<listener>` tag.

Constraints for the method which assigns the annotations

Any method cannot be used as a method to assign the annotation. The signature must match with the method of corresponding listener interface. This point is clearly mentioned in javadoc of respective annotations.

Precautions while implementing JobExecutionListener by an annotation

Since JobExecutionListener has a different scope than the other listeners, listener is not automatically registered in the configuration above. Hence, it is necessary to explicitly set in the <listener> tag. For details ,refer Listener settings.

Implementation of a listener to Tasklet implementation by using annotation

When a listener is implemented in Tasklet implementation by using an annotation, Note that listener does not start with the following settings.

In case of Tasklet

<batch:job id="taskletJobWithListenerAnnotation" job-repository="jobRepository">
    <batch:step id="taskletJobWithListenerAnnotation.step01">
        <batch:tasklet transaction-manager="jobTransactionManager"
                       ref="annotationSalesPlanDetailRegisterTasklet"/>
    </batch:step>
</batch:job>

In case of Tasket model, the listener interface should be used in accordance with How to choose an interface or an annotation.

Listener settings

Listeners are set by <listeners>.<listener> tag of Bean definition. Although it can be described at various locations by XML schema definition, some operations do not work as intended based on the type of interface. Set it to the following position.

Position where listener is set

<!-- for chunk mode -->
<batch:job id="chunkJob" job-repository="jobRepository">
    <batch:step id="chunkJob.step01">
        <batch:tasklet transaction-manager="jobTransactionManager">
            <batch:chunk reader="(1)"
                         processor="(1)"
                         writer="(1)" commit-interval="10"/>
            <batch:listeners>
                <batch:listener ref="(2)"/>
            </batch:listeners>
        </batch:tasklet>
    </batch:step>
    <batch:listeners>
        <batch:listener ref="(3)"/>
    </batch:listeners>
</batch:job>

<!-- for tasklet mode -->
<batch:job id="taskletJob" job-repository="jobRepository">
    <batch:step id="taskletJob.step01">
        <batch:tasklet transaction-manager="jobTransactionManager" ref="tasklet">
            <batch:listeners>
                <batch:listener ref="(2)"/>
            </batch:listeners>
        </batch:tasklet>
    </batch:step>
    <batch:listeners>
        <batch:listener ref="(3)"/>
    </batch:listeners>
</batch:job>

Description of configuration value
Sr. No.	Description
(1)	Set the component which includes the implementation attributing to StepListener, performed by using an annotation. In case of an annotation, it will be inevitably set to this location.
(2)	Set listener interface implementation attributing to StepListener. In case of tasklet model, `ItemReadListener`, `ItemProcessListener` and `ItemWriteListener` cannot be used.
(3)	Set listener attributing to JobListener. Either of interface or annotations must be implemented here.

Setting multiple listeners

Multiple listeners can be set in <batch:listeners> tag.

The sequence in which the listeners are started while registering multiple listeners is shown below.

ItemProcessListener implementation
- listenerA, listenerB
JobExecutionListener implementation
- listenerC, listenerD

Configuration example of multiple listeners

<batch:job id="chunkJob" job-repository="jobRepository">
    <batch:step id="chunkJob.step01">
        <batch:tasklet transaction-manager="jobTransactionManager">
            <batch:chunk reader="reader"
                         processor="pocessor"
                         writer="writer" commit-interval="10"/>
            <batch:listeners>
                <batch:listener ref="listenerA"/>
                <batch:listener ref="listenerB"/>
            </batch:listeners>
        </batch:tasklet>
    </batch:step>
    <batch:listeners>
        <batch:listener ref="listenerC"/>
        <batch:listener ref="listenerD"/>
    </batch:listeners>
</batch:job>

Listener startup sequence

Processing corresponding to pre-processing is started in the sequence of listener registration.
Processing corresponding to post-processing or error processing is started in the reverse sequence of listener registration.

How to choose an interface or an annotation

How to use listener as a listener interface or as an annotation is explained.

Listener interface: It is used in case of cross-sectional processes which are shared across job, step and chunk.
Annotation: It is used when business logic specific process is to be performed.
As a rule, it is implemented only for ItemProcessor.

Exception occurred in pre-processing with StepExecutionListener

When an exception occurs in preprocessing (beforeStep method), open/close of resource changes with model. The occurrence of exception in preprocessing for each model is explained.

Chunk model: Since preprocessing is done before opening the resource, the resource is not opened.
Since the resource is closed even if the resource is not opened, it should be noted when implementing ItemReader/ItemWriter.
Tasklet model: In tasklet model, open/close the resource explicitly in execute method.
When an exception occurs in preprocessing, the resource does not open/close normally since execute method is not executed.

Job abort in preprocess (StepExecutionListener#beforeStep())

When the conditions to execute job, are not satisfied, you may want to abort the process before executing the job.

In such a case, by throwing an exception in preprocess (beforeStep method), the process can be aborted before executing the job.
Here, the case wherein the following requirements are implemented, is explained as an example.

Validate start parameters of input file and output file using beforeStep method defined by StepExecutionListener.
Throw an exception when any of the start parameters are not specified.

However, in TERASOLUNA Batch 5.x, it is recommended to use JobParametersValidator for validation of start parameters. Since easy to understand validation is being used persistently as a sample of aborting preprocess, refer "Parameters validation" to actually validate the start parameters.

Implementation example is shown below.

Implementation example of StepExecutionListener that validates start parameters

@Component
@Scope("step")
public class CheckingJobParameterErrorStepExecutionListener implements StepExecutionListener {

    @Value("#{jobParameters['inputFile']}") // (1)
    private File inputFile;

    @Value("#{jobParameters['outputFile']}") // (1)
    private File outputFile;

    @Override
    public void beforeStep(StepExecution stepExecution) {
        if (inputFile == null) {
            throw new BeforeStepException("The input file must be not null."); // (2)
        }
        else if (outputFile == null) {
            throw new BeforeStepException("The output file must be not null."); // (2)
        }
    }

    @Override
    public ExitStatus afterStep(StepExecution stepExecution) {
        // omitted.
    }
}

Configuration example of listener

<bean id="reader" class="org.terasoluna.batch.functionaltest.ch04.listener.LoggingReader" scope="step"
      p:resource="file:#{jobParameters['inputFile']}"/> <!-- (3) -->
<bean id="writer" class="org.terasoluna.batch.functionaltest.ch04.listener.LoggingWriter" scope="step"
      p:resource="file:#{jobParameters['outputFile']}"/> <!-- (3) -->

<batch:job id="chunkJobWithAbortListener" job-repository="jobRepository">
    <batch:step id="chunkJobWithAbortListener.step01">
        <batch:tasklet transaction-manager="jobTransactionManager">
            <batch:chunk reader="reader" writer="writer" commit-interval="10"/>
        </batch:tasklet>
        <batch:listeners>
            <batch:listener ref="checkingJobParameterErrorStepExecutionListener"/> <!-- (4) -->
        </batch:listeners>
    </batch:step>
</batch:job>

Description
Sr. No.	Description
(1)	Specify the parameters to refer by using @Value annotation.
(2)	Throw an exception. In this example, `RuntimeException` class is inherited and own exception class is used.
(3)	Specify the parameters to refer. The class that sets parameters is the own class that implements `ItemStreamReader` and `ItemStreamWriter` respectively.
(4)	Set listener interface implementation.