Package org.springframework.batch.core.launch

# Interface JobOperator

All Known Implementing Classes:
  `SimpleJobOperator`

public interface JobOperator
Low level interface for inspecting and controlling jobs with access only to primitive and collection types. Suitable for a command-line client (e.g. that launches a new process for each operation), or a remote launcher like a JMX console.

Since:
  2.0
Author:
  Dave Syer

- ## Method Summary

  Modifier and Type
  Method
  Description
  `JobExecution`
  `abandon(long jobExecutionId)`
  Mark the `JobExecution` as ABANDONED.
  `List<Long>`
  `getExecutions(long instanceId)`
  List the `JobExecutions` associated with a particular `JobInstance`, in reverse order of creation (and therefore usually of execution).
  `List<Long>`
  `getJobInstances(String jobName, int start, int count)`
  List the `JobInstances` for a given job name, in reverse order of creation (and therefore usually of first execution).
  `Set<String>`
  `getJobNames()`
  List the available job names that can be launched with `start(String, String)`.
  `String`
  `getParameters(long executionId)`
  Get the `JobParameters` as an easily readable String.
  `Set<Long>`
  `getRunningExecutions(String jobName)`
  Get the id values of all the running `JobExecutions` with the given job name.
  `Map<Long,String>`
  `getStepExecutionSummaries(long executionId)`
  Summarise the `StepExecution` instances belonging to the `JobExecution` with the supplied id, giving details of status, start and end times etc.
  `String`
  `getSummary(long executionId)`
  Summarise the `JobExecution` with the supplied id, giving details of status, start and end times etc.
  `Long`
  `restart(long executionId)`
  Restart a failed or stopped `JobExecution`.
  `Long`
  `start(String jobName, String parameters)`
  Start a new instance of a job with the parameters specified.
  `Long`
  `startNextInstance(String jobName)`
  Launch the next in a sequence of `JobInstance` determined by the `JobParametersIncrementer` attached to the specified job.
  `boolean`
  `stop(long executionId)`
  Send a stop signal to the `JobExecution` with the supplied id.

- ## Method Details

  - ### getExecutions

    List<Long> getExecutions(long instanceId) throws NoSuchJobInstanceException
    List the `JobExecutions` associated with a particular `JobInstance`, in reverse order of creation (and therefore usually of execution).
    Parameters:
      `instanceId` - the id of a `JobInstance`
    Returns:
      the id values of all the `JobExecutions` associated with this instance
    Throws:
      `NoSuchJobInstanceException` - if the `JobInstance` associated with the `instanceId` cannot be found.

  - ### getJobInstances

    List<Long> getJobInstances(String jobName, int start, int count) throws NoSuchJobException
    List the `JobInstances` for a given job name, in reverse order of creation (and therefore usually of first execution).
    Parameters:
      `jobName` - the job name that all the instances have
      `start` - the start index of the instances
      `count` - the maximum number of values to return
    Returns:
      the id values of the `JobInstances`
    Throws:
      `NoSuchJobException` - is thrown if no `JobInstance`s for the jobName exist.

  - ### getRunningExecutions

    Set<Long> getRunningExecutions(String jobName) throws NoSuchJobException
    Get the id values of all the running `JobExecutions` with the given job name.
    Parameters:
      `jobName` - the name of the job to search under
    Returns:
      the id values of the running `JobExecution` instances
    Throws:
      `NoSuchJobException` - if there are no `JobExecutions` with that job name

  - ### getParameters

    String getParameters(long executionId) throws NoSuchJobExecutionException
    Get the `JobParameters` as an easily readable String.
    Parameters:
      `executionId` - the id of an existing `JobExecution`
    Returns:
      the job parameters that were used to launch the associated instance
    Throws:
      `NoSuchJobExecutionException` - if the id was not associated with any `JobExecution`

  - ### start

    Long start(String jobName, String parameters) throws NoSuchJobException, JobInstanceAlreadyExistsException, JobParametersInvalidException
    Start a new instance of a job with the parameters specified.
    Parameters:
      `jobName` - the name of the `Job` to launch
      `parameters` - the parameters to launch it with (comma or newline separated name=value pairs)
    Returns:
      the id of the `JobExecution` that is launched
    Throws:
      `NoSuchJobException` - if there is no `Job` with the specified name
      `JobInstanceAlreadyExistsException` - if a job instance with this name and parameters already exists
      `JobParametersInvalidException` - thrown if any of the job parameters are invalid.

  - ### restart

    Long restart(long executionId) throws JobInstanceAlreadyCompleteException, NoSuchJobExecutionException, NoSuchJobException, JobRestartException, JobParametersInvalidException
    Restart a failed or stopped `JobExecution`. Fails with an exception if the id provided does not exist or corresponds to a `JobInstance` that in normal circumstances already completed successfully.
    Parameters:
      `executionId` - the id of a failed or stopped `JobExecution`
    Returns:
      the id of the `JobExecution` that was started
    Throws:
      `JobInstanceAlreadyCompleteException` - if the job was already successfully completed
      `NoSuchJobExecutionException` - if the id was not associated with any `JobExecution`
      `NoSuchJobException` - if the `JobExecution` was found, but its corresponding `Job` is no longer available for launching
      `JobRestartException` - if there is a non-specific error with the restart (e.g. corrupt or inconsistent restart data)
      `JobParametersInvalidException` - if the parameters are not valid for this job

  - ### startNextInstance

    Long startNextInstance(String jobName) throws NoSuchJobException, JobParametersNotFoundException, JobRestartException, JobExecutionAlreadyRunningException, JobInstanceAlreadyCompleteException, UnexpectedJobExecutionException, JobParametersInvalidException
    Launch the next in a sequence of `JobInstance` determined by the `JobParametersIncrementer` attached to the specified job. If the previous instance is still in a failed state, this method should still create a new instance and run it with different parameters (as long as the `JobParametersIncrementer` is working).
    The last three exception described below should be extremely unlikely, but cannot be ruled out entirely. It points to some other thread or process trying to use this method (or a similar one) at the same time.
    Parameters:
      `jobName` - the name of the job to launch
    Returns:
      the `JobExecution` id of the execution created when the job is launched
    Throws:
      `NoSuchJobException` - if there is no such job definition available
      `JobParametersNotFoundException` - if the parameters cannot be found
      `JobParametersInvalidException` - thrown if some of the job parameters are invalid.
      `UnexpectedJobExecutionException` - if an unexpected condition arises
      `JobRestartException` - thrown if a job is restarted illegally.
      `JobExecutionAlreadyRunningException` - thrown if attempting to restart a job that is already executing.
      `JobInstanceAlreadyCompleteException` - thrown if attempting to restart a completed job.

  - ### stop

    boolean stop(long executionId) throws NoSuchJobExecutionException, JobExecutionNotRunningException
    Send a stop signal to the `JobExecution` with the supplied id. The signal is successfully sent if this method returns true, but that doesn't mean that the job has stopped. The only way to be sure of that is to poll the job execution status.
    Parameters:
      `executionId` - the id of a running `JobExecution`
    Returns:
      true if the message was successfully sent (does not guarantee that the job has stopped)
    Throws:
      `NoSuchJobExecutionException` - if there is no `JobExecution` with the id supplied
      `JobExecutionNotRunningException` - if the `JobExecution` is not running (so cannot be stopped)

  - ### getSummary

    String getSummary(long executionId) throws NoSuchJobExecutionException
    Summarise the `JobExecution` with the supplied id, giving details of status, start and end times etc.
    Parameters:
      `executionId` - the id of an existing `JobExecution`
    Returns:
      a String summarising the state of the job execution
    Throws:
      `NoSuchJobExecutionException` - if there is no `JobExecution` with the supplied id

  - ### getStepExecutionSummaries

    Map<Long,String> getStepExecutionSummaries(long executionId) throws NoSuchJobExecutionException
    Summarise the `StepExecution` instances belonging to the `JobExecution` with the supplied id, giving details of status, start and end times etc.
    Parameters:
      `executionId` - the id of an existing `JobExecution`
    Returns:
      a map of step execution id to String summarising the state of the execution
    Throws:
      `NoSuchJobExecutionException` - if there is no `JobExecution` with the supplied id

  - ### getJobNames

    Set<String> getJobNames()
    List the available job names that can be launched with `start(String, String)`.
    Returns:
      a set of job names

  - ### abandon

    JobExecution abandon(long jobExecutionId) throws NoSuchJobExecutionException, JobExecutionAlreadyRunningException
    Mark the `JobExecution` as ABANDONED. If a stop signal is ignored because the process died this is the best way to mark a job as finished with (as opposed to STOPPED). An abandoned job execution cannot be restarted by the framework.
    Parameters:
      `jobExecutionId` - the job execution id to abort
    Returns:
      the `JobExecution` that was aborted
    Throws:
      `NoSuchJobExecutionException` - thrown if there is no job execution for the jobExecutionId.
      `JobExecutionAlreadyRunningException` - if the job is running (it should be stopped first)