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, Mahmoud Ben Hassine
-
Method Summary
Modifier and TypeMethodDescriptionabandon
(long jobExecutionId) Mark theJobExecution
as ABANDONED.getExecutions
(long instanceId) List theJobExecutions
associated with a particularJobInstance
, in reverse order of creation (and therefore usually of execution).default JobInstance
getJobInstance
(String jobName, JobParameters jobParameters) getJobInstances
(String jobName, int start, int count) List theJobInstances
for a given job name, in reverse order of creation (and therefore usually of first execution).List the available job names that can be launched withstart(String, String)
.getParameters
(long executionId) Get theJobParameters
as an easily readable String.getRunningExecutions
(String jobName) Get the id values of all the runningJobExecutions
with the given job name.getStepExecutionSummaries
(long executionId) Summarise theStepExecution
instances belonging to theJobExecution
with the supplied id, giving details of status, start and end times etc.getSummary
(long executionId) Summarise theJobExecution
with the supplied id, giving details of status, start and end times etc.restart
(long executionId) Restart a failed or stoppedJobExecution
.Start a new instance of a job with the parameters specified.startNextInstance
(String jobName) Launch the next in a sequence ofJobInstance
determined by theJobParametersIncrementer
attached to the specified job.boolean
stop
(long executionId) Send a stop signal to theJobExecution
with the supplied id.
-
Method Details
-
getExecutions
List theJobExecutions
associated with a particularJobInstance
, in reverse order of creation (and therefore usually of execution).- Parameters:
instanceId
- the id of aJobInstance
- Returns:
- the id values of all the
JobExecutions
associated with this instance - Throws:
NoSuchJobInstanceException
- if theJobInstance
associated with theinstanceId
cannot be found.
-
getJobInstances
List theJobInstances
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 havestart
- the start index of the instancescount
- the maximum number of values to return- Returns:
- the id values of the
JobInstances
- Throws:
NoSuchJobException
- is thrown if noJobInstance
s for the jobName exist.
-
getJobInstance
- Parameters:
jobName
-String
name of the job.jobParameters
-JobParameters
parameters for the job instance.- Returns:
- the
JobInstance
with the given name and parameters, ornull
. - Since:
- 5.0
-
getRunningExecutions
Get the id values of all the runningJobExecutions
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 noJobExecutions
with that job name
-
getParameters
Get theJobParameters
as an easily readable String.- Parameters:
executionId
- the id of an existingJobExecution
- Returns:
- the job parameters that were used to launch the associated instance
- Throws:
NoSuchJobExecutionException
- if the id was not associated with anyJobExecution
-
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 theJob
to launchparameters
- 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 noJob
with the specified nameJobInstanceAlreadyExistsException
- if a job instance with this name and parameters already existsJobParametersInvalidException
- thrown if any of the job parameters are invalid.
-
restart
Long restart(long executionId) throws JobInstanceAlreadyCompleteException, NoSuchJobExecutionException, NoSuchJobException, JobRestartException, JobParametersInvalidException Restart a failed or stoppedJobExecution
. Fails with an exception if the id provided does not exist or corresponds to aJobInstance
that in normal circumstances already completed successfully.- Parameters:
executionId
- the id of a failed or stoppedJobExecution
- Returns:
- the id of the
JobExecution
that was started - Throws:
JobInstanceAlreadyCompleteException
- if the job was already successfully completedNoSuchJobExecutionException
- if the id was not associated with anyJobExecution
NoSuchJobException
- if theJobExecution
was found, but its correspondingJob
is no longer available for launchingJobRestartException
- 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 ofJobInstance
determined by theJobParametersIncrementer
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 theJobParametersIncrementer
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 availableJobParametersNotFoundException
- if the parameters cannot be foundJobParametersInvalidException
- thrown if some of the job parameters are invalid.UnexpectedJobExecutionException
- if an unexpected condition arisesJobRestartException
- 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
Send a stop signal to theJobExecution
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 runningJobExecution
- Returns:
- true if the message was successfully sent (does not guarantee that the job has stopped)
- Throws:
NoSuchJobExecutionException
- if there is noJobExecution
with the id suppliedJobExecutionNotRunningException
- if theJobExecution
is not running (so cannot be stopped)
-
getSummary
Summarise theJobExecution
with the supplied id, giving details of status, start and end times etc.- Parameters:
executionId
- the id of an existingJobExecution
- Returns:
- a String summarising the state of the job execution
- Throws:
NoSuchJobExecutionException
- if there is noJobExecution
with the supplied id
-
getStepExecutionSummaries
Summarise theStepExecution
instances belonging to theJobExecution
with the supplied id, giving details of status, start and end times etc.- Parameters:
executionId
- the id of an existingJobExecution
- Returns:
- a map of step execution id to String summarising the state of the execution
- Throws:
NoSuchJobExecutionException
- if there is noJobExecution
with the supplied id
-
getJobNames
List the available job names that can be launched withstart(String, String)
.- Returns:
- a set of job names
-
abandon
JobExecution abandon(long jobExecutionId) throws NoSuchJobExecutionException, JobExecutionAlreadyRunningException Mark theJobExecution
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)
-