Package org.springframework.batch.core.launch.support

# Class CommandLineJobRunner

java.lang.Object
org.springframework.batch.core.launch.support.CommandLineJobRunner

public class CommandLineJobRunner extends Object

Basic launcher for starting jobs from the command line. In general, it is assumed that this launcher will primarily be used to start a job via a script from an Enterprise Scheduler. Therefore, exit codes are mapped to integers so that schedulers can use the returned values to determine the next course of action. The returned values can also be useful to operations teams in determining what should happen upon failure. For example, a returned code of 5 might mean that some resource wasn't available and the job should be restarted. However, a code of 10 might mean that something critical has happened and the issue should be escalated.

With any launch of a batch job within Spring Batch, a Spring context containing the `Job` and some execution context has to be created. This command line launcher can be used to load the job and its context from a single location. All dependencies of the launcher will then be satisfied by autowiring by type from the combined application context. Default values are provided for all fields except the `JobLauncher` and `JobLocator` . Therefore, if autowiring fails to set it (it should be noted that dependency checking is disabled because most of the fields have default values and thus don't require dependencies to be fulfilled via autowiring) then an exception will be thrown. It should also be noted that even if an exception is thrown by this class, it will be mapped to an integer and returned.

Notice a property is available to set the `SystemExiter`. This class is used to exit from the main method, rather than calling System.exit() directly. This is because unit testing a class the calls System.exit() is impossible without kicking off the test within a new JVM, which it is possible to do, however it is a complex solution, much more so than strategizing the exiter.

The arguments to this class can be provided on the command line (separated by spaces), or through stdin (separated by new line). They are as follows:

`jobPath <options> jobIdentifier (jobParameters)*`

The command line options are as follows

- jobPath: the xml application context containing a `Job`
- -restart: (optional) to restart the last failed execution
- -stop: (optional) to stop a running execution
- -abandon: (optional) to abandon a stopped execution
- -next: (optional) to start the next in a sequence according to the `JobParametersIncrementer` in the `Job`
- jobIdentifier: the name of the job or the id of a job execution (for -stop, -abandon or -restart).
- jobParameters: 0 to many parameters that will be used to launch a job specified in the form of `key=value` pairs.

If the `-next` option is used the parameters on the command line (if any) are appended to those retrieved from the incrementer, overriding any with the same key.

The combined application context must contain only one instance of `JobLauncher`. The job parameters passed in to the command line will be converted to `Properties` by assuming that each individual element is one parameter that is separated by an equals sign. For example, "vendor.id=290232". The resulting properties instance is converted to `JobParameters` using a `JobParametersConverter` from the application context (if there is one, or a `DefaultJobParametersConverter` otherwise). Below is an example arguments list: "

`java org.springframework.batch.core.launch.support.CommandLineJobRunner testJob.xml testJob schedule.date=2008/01/24 vendor.id=3902483920`

By default, the `CommandLineJobRunner` uses a `DefaultJobParametersConverter` which implicitly converts key/value pairs to identifying job parameters. However, it is possible to explicitly specify which job parameters are identifying and which are not by prefixing them with `+` or `-` respectively. In the following example, `schedule.date` is an identifying job parameter while `vendor.id` is not:

`java org.springframework.batch.core.launch.support.CommandLineJobRunner testJob.xml testJob +schedule.date=2008/01/24 -vendor.id=3902483920`

This behaviour can be overridden by using a custom `JobParametersConverter`.

Once arguments have been successfully parsed, autowiring will be used to set various dependencies. The `JobLauncher` for example, will be loaded this way. If none is contained in the bean factory (it searches by type) then a `BeanDefinitionStoreException` will be thrown. The same exception will also be thrown if there is more than one present. Assuming the JobLauncher has been set correctly, the jobIdentifier argument will be used to obtain an actual `Job`. If a `JobLocator` has been set, then it will be used, if not the beanFactory will be asked, using the jobIdentifier as the bean id.

Since:
  1.0
Author:
  Dave Syer, Lucas Ward, Mahmoud Ben Hassine

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final org.apache.commons.logging.Log`
  `logger`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CommandLineJobRunner()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `exit(int status)`
  Delegate to the exiter to (possibly) exit the VM gracefully.
  `static String`
  `getErrorMessage()`
  Retrieve the error message set by an instance of `CommandLineJobRunner` as it exits.
  `static void`
  `main(String[] args)`
  Launch a batch job using a `CommandLineJobRunner`.
  `static void`
  `presetSystemExiter(SystemExiter systemExiter)`
  Static setter for the `SystemExiter` so it can be adjusted before dependency injection.
  `void`
  `setExitCodeMapper(ExitCodeMapper exitCodeMapper)`
  Injection setter for the `ExitCodeMapper`.
  `void`
  `setJobExplorer(JobExplorer jobExplorer)`
  Injection setter for `JobExplorer`.
  `void`
  `setJobLocator(JobLocator jobLocator)`
  `JobLocator` to find a job to run.
  `void`
  `setJobParametersConverter(JobParametersConverter jobParametersConverter)`
  Injection setter for `JobParametersConverter`.
  `void`
  `setJobRepository(JobRepository jobRepository)`
  `void`
  `setLauncher(JobLauncher launcher)`
  Injection setter for the `JobLauncher`.
  `void`
  `setSystemExiter(SystemExiter systemExiter)`
  Injection setter for the `SystemExiter`.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### logger

    protected static final org.apache.commons.logging.Log logger

- ## Constructor Details

  - ### CommandLineJobRunner

    public CommandLineJobRunner()

- ## Method Details

  - ### setLauncher

    public void setLauncher(JobLauncher launcher)
    Injection setter for the `JobLauncher`.
    Parameters:
      `launcher` - the launcher to set

  - ### setJobRepository

    public void setJobRepository(JobRepository jobRepository)
    Parameters:
      `jobRepository` - the jobRepository to set

  - ### setJobExplorer

    public void setJobExplorer(JobExplorer jobExplorer)
    Injection setter for `JobExplorer`.
    Parameters:
      `jobExplorer` - the `JobExplorer` to set

  - ### setExitCodeMapper

    public void setExitCodeMapper(ExitCodeMapper exitCodeMapper)
    Injection setter for the `ExitCodeMapper`.
    Parameters:
      `exitCodeMapper` - the exitCodeMapper to set

  - ### presetSystemExiter

    public static void presetSystemExiter(SystemExiter systemExiter)
    Static setter for the `SystemExiter` so it can be adjusted before dependency injection. Typically overridden by `setSystemExiter(SystemExiter)`.
    Parameters:
      `systemExiter` - `SystemExiter` instance to be used by CommandLineJobRunner instance.

  - ### getErrorMessage

    public static String getErrorMessage()
    Retrieve the error message set by an instance of `CommandLineJobRunner` as it exits. Empty if the last job launched was successful.
    Returns:
      the error message

  - ### setSystemExiter

    public void setSystemExiter(SystemExiter systemExiter)
    Injection setter for the `SystemExiter`.
    Parameters:
      `systemExiter` - `SystemExiter` instance to be used by CommandLineJobRunner instance.

  - ### setJobParametersConverter

    public void setJobParametersConverter(JobParametersConverter jobParametersConverter)
    Injection setter for `JobParametersConverter`.
    Parameters:
      `jobParametersConverter` - instance of `JobParametersConverter` to be used by the CommandLineJobRunner instance.

  - ### exit

    public void exit(int status)
    Delegate to the exiter to (possibly) exit the VM gracefully.
    Parameters:
      `status` - int exit code that should be reported.

  - ### setJobLocator

    public void setJobLocator(JobLocator jobLocator)
    `JobLocator` to find a job to run.
    Parameters:
      `jobLocator` - a `JobLocator`

  - ### main

    public static void main(String[] args) throws Exception
    Launch a batch job using a `CommandLineJobRunner`. Creates a new Spring context for the job execution, and uses a common parent for all such contexts. No exception are thrown from this method, rather exceptions are logged and an integer returned through the exit status in a `JvmSystemExiter` (which can be overridden by defining one in the Spring context).
    Parameters can be provided in the form key=value, and will be converted using the injected `JobParametersConverter`.
    Parameters:
      `args` -
      - -restart: (optional) if the job has failed or stopped and the most should be restarted. If specified then the jobIdentifier parameter can be interpreted either as the name of the job or the id of the job execution that failed.
      - -next: (optional) if the job has a `JobParametersIncrementer` that can be used to launch the next instance in a sequence
      - jobPath: the xml application context containing a `Job`
      - jobIdentifier: the bean id of the job or id of the failed execution in the case of a restart.
      - jobParameters: 0 to many parameters that will be used to launch a job.

      The options (`-restart, -next`) can occur anywhere in the command line.

    Throws:
      `Exception` - is thrown if error occurs.