Because the script launching the job must kick off a Java Virtual Machine, there needs to be a class with a main method to act as the primary entry point. Spring Batch provides an implementation that serves just this purpose: CommandLineJobRunner. It's important to note that this is just one way to bootstrap your application, but there are many ways to launch a Java process, and this class should in no way be viewed as definitive. It performs four tasks:

All of these tasks are accomplished based completely upon the arguments passed in. The following are required arguments:

These arguments must be passed in with the path first and the name second. All arguments after these are considered to be JobParameters and must be in the format of 'name=value':

bash$ java CommandLineJobRunner endOfDayJob.xml endOfDay schedule.date(date)=2008/01/01

In most cases you would want to use a manifest to declare your main class in a jar, but for simplicity, the class was used directly. This example is using the same 'EndOfDay' example from Chapter 2. The first argument is 'endOfDayJob.xml', which is the Spring ApplicationContext containing the Job. The second argument, 'endOfDay' represents the job name. The final argument, 'schedule.date=01-01-2008' will be converted into JobParameters. An example of the XML configuration is below:

  <bean id="endOfDay"
        class="org.springframework.batch.core.job.SimpleJob">
    <property name="steps">
      <bean id="step1" parent="simpleStep" />
      <!-- Step details removed for clarity -->
    </property> 
  </bean>

  <!-- Launcher details removed for clarity -->
  <bean id="jobLauncher"
        class="org.springframework.batch.core.launch.support.SimpleJobLauncher" />

This example is overly simplistic, since there are many more requirements to a run a batch job in Spring Batch in general, but it serves to show the two main requirements of the CommandLineJobRunner: Job and JobLauncher

When launching a batch job from the command-line, it is often from an enterprise scheduler. Most schedulers are fairly dumb, and work only at the process level. Meaning, they only know about some operating system process such as a shell script that they're invoking. In this scenario, the only way to communicate back to the scheduler about the success or failure of a job is through return codes. A number is returned to a scheduler that is told how to interpret the result. In the simple case: 0 is success and 1 is failure. However, there may be scenarios such as: If job A returns 4 kick off job B, if it returns 5 kick off job C. This type of behavior is configured at the scheduler level, but it is important that a processing framework such as Spring Batch provide a way to return a numeric representation of of the 'Exit Code' for a particular batch job. In Spring Batch this is encapsulated within an ExitStatus, which is covered in more detail in Chapter 5. For the purposes of discussing exit codes, the only important thing to know is that an ExitStatus has an exit code property that is set by the framework (or the developer) and is returned as part of the JobExecution returned from the JobLauncher. The CommandLineJobRunner converts this string value to a number using the ExitCodeMapper interface:

  public interface ExitCodeMapper {

    public int intValue(String exitCode);
}

The essential contract of an ExitCodeMapper is that, given a string exit code, a number representation will be returned. The default implementation used by the job runner is the SimpleJvmExitCodeMapper that returns 0 for completion, 1 for generic errors, and 2 for any job runner errors such as not being able to find a Job in the provided context. If anything more complex than the 3 values above is needed, then a custom implementation of the ExitCodeMapper interface must be supplied. Because the CommandLineJobRunner is the class that creates an ApplicationContext, and thus cannot be 'wired together', any values that need to be overwritten must be autowired. This means that if an implementation of ExitCodeMapper is found within the BeanFactory, it will be injected into the runner after the context is created. All that needs to be done to provide your own ExitCodeMapper is to declare the implementation as a root level bean, and ensure it's part of the ApplicationContext that is loaded by the runner.

One of the most common reasons for wanting to launching a job asynchronously is to be able to gracefully stop it. This can be done through the JobExecution returned by the JobLauncher:

  JobExecution jobExecution = launcher.run(getJob(), jobParameters);

  //give job adequate time to start
  Thread.sleep(1000);

  assertEquals(BatchStatus.STARTED, jobExecution.getStatus());
  assertTrue(jobExecution.isRunning());

  jobExecution.stop();

  //give job time to stop
  Thread.sleep(1000);

  assertEquals(BatchStatus.STOPPED, jobExecution.getStatus());
  assertFalse(jobExecution.isRunning());

The shutdown is not immediate, since there is no way to force immediate shutdown, especially if the execution is currently in developer code that the framework has no control over, such as a business service. What it does mean, is that as soon as control is returned back to the framework, it will set the status of the current StepExecution to BatchStatus.STOPPED, save it, then do the same for the JobExecution before finishing.

Including the incrementers, which must be database specific, the configuration above is verbose. In order to make this more manageable, the framework provides a FactoryBean for convenience: JobRepositoryFactoryBean.

  <bean id="jobRepository"
        class="org.springframework.batch.execution.repository.JobRepositoryFactoryBean"
    <property name="databaseType" value="hsql" /> 
    <property name="dataSource" value="dataSource" />
  </bean>

The databaseType property indicates the type of incrementer that must be used. Options include: "db2", "derby", "hsql", "mysql", "oracle", and "postgres".

There are scenarios in which you may not want to persist your domain objects to the database. One reason may be speed, storing domain objects at each commit point takes extra time. Another reason may be that you just don't need to persist status for a particular job. Spring batch provides a solution:

  <bean id="jobRepository" class="org.springframework.batch.core.repository.support.SimpleJobRepository">
    <constructor-arg ref="mapJobInstanceDao" />
    <constructor-arg ref="mapJobExecutionDao" />
    <constructor-arg ref="mapJtepExecutionDao" />
  </bean>

  <bean id="mapJobInstanceDao"
        class="org.springframework.batch.execution.repository.dao.MapJobInstanceDao" />

  <bean id="mapJobExecutionDao"
        class="org.springframework.batch.execution.repository.dao.MapJobExecutionDao" />

  <bean id="mapStepExecutionDao"
        class="org.springframework.batch.execution.repository.dao.MapStepExecutionDao" />

The Map* DAO implementations store the batch artifacts in a transactional map. So, the repository and DAOs may still be used normally, and are transactionally sound, but their contents will be lost when the class is destroyed.

<aop:config>
    <aop:advisor 
        pointcut="execution(* org.springframework.batch.core..*Repository+.*(..))"
    <advice-ref="txAdvice" />
</aop:config>

<tx:advice id="txAdvice" transaction-manager="transactionManager">
    <tx:attributes>
        <tx:method name="create*" propagation="REQUIRES_NEW" isolation="SERIALIZABLE" />
        <tx:method name="*" />
    </tx:attributes>
</tx:advice>

One key concern when execution a batch job, is what happens when a failed job is restarted? A Job is considered to have been 'restarted' if the same JobInstance has more than one JobExecution. Ideally, all jobs should be able to start up where they left off, but there are scenarios where this is not possible. It is entirely up to the developer to ensure that a new instance is always created in this scenario. However, Spring Batch does provide some help. If a Job should never be restarted, but should always be run as part of a new JobInstance, then the restartable property may be set to 'false':

  <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>
    </property>
    <property name="jobRepository" ref="jobRepository" />
    <property name="restartable" value="false" />
  </bean>

To phrase it another way, setting restartable to false means "this Job does not support being started again". Restarting a Job that is not restartable will cause a JobRestartException to be thrown:

  Job job = new SimpleJob();
  job.setRestartable(false);

  JobParameters jobParameters = new JobParameters();

  JobExecution firstExecution = jobRepository.createJobExecution(job, jobParameters);
  jobRepository.saveOrUpdate(firstExecution);

  try {
    jobRepository.createJobExecution(job, jobParameters);
    fail();
  }
  catch (JobRestartException e) {
    // expected
  }

This snippet of JUnit code shows how attempting to create a JobExecution the first time for a non restartable job will cause no issues. However, the second attempt will throw a JobRestartException.

During the course of the execution of a Job, it may be useful to be notified of various events in its lifecycle so that custom code may be executed. The SimpleJob allows for this by calling a JobListener at the appropriate time:

  public interface JobListener {

    void beforeJob(JobExecution jobExecution);

    void afterJob(JobExecution jobExecution);

    void onError(JobExecution jobExecution, Throwable e);

    void onInterrupt(JobExecution jobExecution);
  }

Listeners can be added to a SimpleJob via the setJobListeners property:

  <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>
    </property>
    <property name="jobRepository" ref="jobRepository" />
  <property name="jobListeners">
    <bean class="org.springframework.batch.core.listener.JobListenerSupport" />
  </property>
  </bean>

Despite the relatively short list of required dependencies for an ItemOrientedStep, it is an extremely complex class that can potentially contain many collaborators. In order to ease configuration, a SimpleStepFactoryBean can be used:

  <bean id="simpleStep"
        class="org.springframework.batch.core.step.item.SimpleStepFactoryBean" >
    <property name="transactionManager" ref="transactionManager" />
    <property name="jobRepository" ref="jobRepository" />
    <property name="itemReader" ref="itemReader" />
    <property name="itemWriter" ref="itemWriter" />
  </bean>

The configuration above represents the only required dependencies of the factory bean. Attempting to instantiate a SimpleStepFactoryBean without at least those four dependencies will result in an exception being thrown during construction by the Spring container.

As mentioned above, the ItemOrientedStep reads in and writes out items, periodically commiting using the supplied PlatformTransactionManager. By default, it will commit after each item has been written. This is less than ideal in many situations, since beginning and commiting a transaction is expensive. Ideally, you would like to process as many items as possible in each transaction, which is completely dependant upon the type of data being processed and the resources that are being interacted with. For this reason, the number of items that are processed within a commit can be set as the commit interval:

 <bean id="simpleStep"
        class="org.springframework.batch.core.step.item.SimpleStepFactoryBean" >
    <property name="transactionManager" ref="transactionManager" />
    <property name="jobRepository" ref="jobRepository" />
    <property name="itemReader" ref="itemReader" />
    <property name="itemWriter" ref="itemWriter" />
    <property name="commitInterval" value="10" />
  </bean>

In this example, 10 items will be processed within each transaction. At the beginning of processing a transaction is begun, and each time read is called on the ItemReader, a counter is incremented. When it reaches 10, the transaction will be committed.

Earlier in this chapter, restarting a Job was discussed. Restart has numerous impacts on steps, and as such may require some specific configuration.

 <bean id="simpleStep"
        class="org.springframework.batch.core.step.item.SimpleStepFactoryBean" >
    <property name="transactionManager" ref="transactionManager" />
    <property name="jobRepository" ref="jobRepository" />
    <property name="itemReader" ref="itemReader" />
    <property name="itemWriter" ref="itemWriter" />
    <property name="commitInterval" value="10" />
    <property name="startLimit" value="1" />
  </bean>

 <bean id="simpleStep"
        class="org.springframework.batch.core.step.item.SimpleStepFactoryBean" >
    <property name="transactionManager" ref="transactionManager" />
    <property name="jobRepository" ref="jobRepository" />
    <property name="itemReader" ref="itemReader" />
    <property name="itemWriter" ref="itemWriter" />
    <property name="commitInterval" value="10" />
    <property name="startLimit" value="1" />
    <property name="allowStartIfComplete" value="true" />
  </bean>

  <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" >
          <property name="allowStartIfComplete" value="true" />
        </bean>
        <bean id="playerSummarization" parent="simpleStep" >
          <property name="startLimit" value="2" />
        </bean>
      </list>
    </property>
    <property name="jobRepository" ref="jobRepository" />
    <property name="restartable" value="true" />
  </bean>

There are many scenarios where errors encountered while processing should not result in Step failure, but should be skipped instead. This is usually a decision that must be made by someone who understands the data itself and what meaning it has. Financial data, for example, may not be skippable because it results in money being transferred, which needs to be completely accurate. Loading in a list of vendors, on the other hand, might allow for skips, since a vendor not being loaded because it was formatted incorrectly, or missing necessary information, won't cause issues. Usually these bad records are logged as well, which will be covered later when discussing listeners. Configuring skip handling requires using a new factory bean: SkipLimitStepFactoryBean

  <bean id="skipSample" parent="simpleStep"
        class="org.springframework.batch.core.step.item.SkipLimitStepFactoryBean">
    <property name="skipLimit" value="10" />
    <property name="itemReader" ref="flatFileItemReader" />
    <property name="itemWriter" ref="itemWriter" />
    <property name="skippableExceptionClasses"
              value="org.springframework.batch.item.file.FlatFileParseException">
    </property>
  </bean> 

In this example, a FlatFileItemReader is used, and if at any point a FlatFileParseException is thrown, it will be skipped and counted against the total skip limit of 10. It should be noted that any failures encountered while reading will not count against the commit interval. In other words, the commit interval is only incremented on writes (regardless of success or failure).

In most cases you want an Exception to cause either a skip or Step failure. However, not all exceptions are deterministic. If a FlatFileParseException is encountered while reading, it will always be thrown for that record. Resseting the ItemReader will not help. However, for other exceptions, such as a DeadlockLoserDataAccessException, which indicates that the current process has attempted to update a record that another process holds a lock on, waiting and trying again might result in success. In this case, a StatefulRetryStepFactoryBean should be used:

  <bean id="step1" parent="simpleStep"
        class="org.springframework.batch.core.step.item.StatefulRetryStepFactoryBean">
    <property name="itemReader" ref="itemGenerator" />
    <property name="itemWriter" ref="itemWriter" />
    <property name="retryLimit" value="3" />
    <property name="retryableExceptionClasses" value="org.springframework.dao.DeadlockLoserDataAccessException" />
  </bean>

The StatefulRetryStepFactoryBean requires a limit for the number of times an individual item can be retried, and a list of Exceptions that are 'retryable'.

The step has to take care of ItemStream callbacks at the necessary points in its lifecycle. This is vital if a step fails, and might need to be restarted, because the ItemStream interface is where the step gets the information it needs about persistent state between executions. The factory beans that Spring Batch provides for convenient configuration of Step instances have features that allow streams to be registered with the step when it is configured.

If the ItemReader or ItemWriter themselves implement the ItemStream interface, then these will be registered automatically. Any other streams need to be registered separately. This is often the case where there are indirect dependencies, like delegates being injected into the reader and writer. To register these they can be injected into the factory beans through the streams property, as illustrated below:

<bean id="step1" parent="simpleStep"
        class="org.springframework.batch.core.step.item.StatefulRetryStepFactoryBean">
    <property name="streams" ref="fileItemReader" />
    <property name="itemReader">
        <bean
            class="org.springframework.batch.item.validator.ValidatingItemReader">
            <property name="itemReader" ref="itemReader" />
            <property name="validator" ref="fixedValidator" />
        </bean>
    </property>
    ...
</bean>

In the example above the main item reader is being set up to delegate to a bean called "fileItemReader", which itself is being registered as a stream directly. The step will now be restartable and the state of the reader will be correctly persisted in case of a failure.

Just as with the Job, there are many events during the execution of a Step that a user may need notification of. For example, if writing out to a flat file that requires a footer, the ItemWriter needs to be notified when the Step has been completed, so that it can write the footer. This can be accomplished with one of many Step scoped listeners.

  public interface StepExecutionListener extends StepListener {

    void beforeStep(StepExecution stepExecution);

    ExitStatus onErrorInStep(StepExecution stepExecution, Throwable e);

    ExitStatus afterStep(StepExecution stepExecution);
}

  <bean id="simpleStep"
        class="org.springframework.batch.core.step.item.SimpleStepFactoryBean" >
    <property name="transactionManager" ref="transactionManager" />
    <property name="jobRepository" ref="jobRepository" />
    <property name="itemReader" ref="itemReader" />
    <property name="itemWriter" ref="itemWriter" />
    <property name="commitInterval" value="10" />
    <property name="listeners" ref="stepListener" />    
  </bean>

  public interface ChunkListener extends StepListener {

    void beforeChunk();

    void afterChunk();
  }

  public interface ItemReadListener extends StepListener {
  
    void beforeRead();

    void afterRead(Object item);
    
    void onReadError(Exception ex);
}

  public interface ItemWriteListener extends StepListener {

    void beforeWrite(Object item);

    void afterWrite(Object item);

    void onWriteError(Exception ex, Object item);
}

As with other adapters for the ItemWriter and ItemReader interfaces, the Tasklet interface contains an implementation that allows for adapting itself to any pre-existing class: TaskletAdapter. An example where this may be useful is an existing DAO that is used to upate a flag on a set of records. The TaskletAdapter can be used to call this class without having to write an adapter for the Tasklet interface:

  <bean id="deleteFilesInDir" parent="taskletStep">
    <property name="tasklet">
      <bean class="org.springframework.batch.core.step.tasklet.TaskletAdapter">
        <property name="targetObject">
          <bean class="org.mycompany.FooDao">
        </property>
        <property name="targetMethod" value-"updateFoo" />
      </bean>
    </property>
  </bean>

Many batch jobs contains steps that must be done before the main processing begins in order to set up various resources, or after processing has completed to cleanup those resources. In the case of a job that works heavily with files, it is often necessary to delete certain files locally after they have been uploaded successfully to another location. The example below taken from the Spring Batch samples project, is a Tasklet implementation with just such a responsibility:

  public class FileDeletingTasklet implements Tasklet, InitializingBean {

    private Resource directory;

    public ExitStatus execute() throws Exception {
      File dir = directory.getFile();
      Assert.state(dir.isDirectory());
    
      File[] files = dir.listFiles();
      for (int i = 0; i < files.length; i++) {
        boolean deleted = files[i].delete();
        if (!deleted) {
          throw new UnexpectedJobExecutionException("Could not delete file " + files[i].getPath());
        }
      }
      return ExitStatus.FINISHED;
    }

    public void setDirectoryResource(Resource directory) {
      this.directory = directory;
    }

    public void afterPropertiesSet() throws Exception {
      Assert.notNull(directory, "directory must be set");
    }
  }

The above Tasklet implementation will delete all files within a given directory. It should be noted that the execute method will only be called once. All that is left is to inject the Tasklet into a TaskletStep:

  <bean id="taskletJob" parent="simpleJob">
    <property name="steps">
      <bean id="deleteFilesInDir" parent="taskletStep">
        <property name="tasklet">
          <bean class="org.springframework.batch.sample.tasklet.FileDeletingTasklet">
            <property name="directoryResource" ref="directory" />
          </bean>
        </property>
      </bean>
    </property>
  </bean>

  <bean id="directory"
        class="org.springframework.core.io.FileSystemResource">
    <constructor-arg value="target/test-outputs/test-dir" />
  </bean>