Jakarta EE 11.0.0 · jakarta.batch.operations.JobOperator

Method Summary

Modifier and Type	Method and Description
public void	abandon(long specifies the job execution to abandon. executionId) Set batch status to ABANDONED.
public JobExecution	Returns: job execution getJobExecution(long specifies the job execution. executionId) Return job execution for specified execution id.
public List<JobExecution>	Returns: list of job executions getJobExecutions(JobInstance specifies the job instance. instance) Return all job executions belonging to the specified job instance.
public JobInstance	Returns: job instance getJobInstance(long specifies the job execution. executionId) Return the job instance for the specified execution id.
public int	Returns: count of instances of the named job. getJobInstanceCount(String specifies the name of the job. jobName) Returns number of instances of a job with a particular name.
public List<JobInstance>	Returns: list of JobInstances. getJobInstances(String specifies the job name. jobName, int specifies the relative starting number (zero based) to return from the maximal list of job instances. start, int specifies the number of job instances to return from the starting position of the maximal list of job instances. count) Returns all JobInstances belonging to a job with a particular name in reverse chronological order.
public Set<String>	Returns: a set of job names. getJobNames() Returns a set of all job names known to the batch runtime.
public Properties	Returns: a Properties object containing the key/value job parameter pairs. getParameters(long specifies the execution from which to retrieve the parameters. executionId) Returns job parameters for a specified job instance.
public List<Long>	Returns: a list of execution ids. getRunningExecutions(String specifies the job name. jobName) Returns execution ids for job instances with the specified name that have running executions.
public List<StepExecution>	Returns: step executions (order not guaranteed) getStepExecutions(long specifies the job execution. jobExecutionId) Return StepExecutions for specified execution id.
public long	Returns: new executionId restart(long specifies the execution to to restart. This execution must be the most recent execution that ran. executionId, Properties specifies the keyword/value pairs for attribute substitution in the Job XML. restartParameters) Restarts a failed or stopped job instance, which executes asynchronously.
public long	Returns: executionId for the job execution. start(String specifies the name of the Job XML describing the job. jobXMLName, Properties specifies the keyword/value pairs for attribute substitution in the Job XML. jobParameters) Creates a new job instance and starts the first execution of that instance, which executes asynchronously.
public void	stop(long specifies the job execution to stop. The job execution must be running. executionId) Request a running job execution stops.

Method Detail

abandon	back to summary
public void abandon(long executionId) throws NoSuchJobExecutionException, JobExecutionIsRunningException, JobSecurityException Set batch status to ABANDONED. The instance must have no running execution. Note that ABANDONED executions cannot be restarted. Parameters executionId:long specifies the job execution to abandon. Exceptions NoSuchJobExecutionException: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository. JobExecutionIsRunningException: Thrown when the job execution associated with executionId is currently running JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

abandon

back to summary

public void abandon(long executionId) throws NoSuchJobExecutionException, JobExecutionIsRunningException, JobSecurityException

Set batch status to ABANDONED. The instance must have no running execution.

Note that ABANDONED executions cannot be restarted.

Parameters

executionId:long: specifies the job execution to abandon.

Exceptions

NoSuchJobExecutionException:: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository.
JobExecutionIsRunningException:: Thrown when the job execution associated with executionId is currently running
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobExecution	back to summary
public JobExecution getJobExecution(long executionId) throws NoSuchJobExecutionException, JobSecurityException Return job execution for specified execution id. Parameters executionId:long specifies the job execution. Returns:JobExecution job execution Exceptions NoSuchJobExecutionException: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository. JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobExecution

back to summary

public JobExecution getJobExecution(long executionId) throws NoSuchJobExecutionException, JobSecurityException

Return job execution for specified execution id.

Parameters

executionId:long: specifies the job execution.

Returns:JobExecution

job execution

Exceptions

NoSuchJobExecutionException:: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository.
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobExecutions	back to summary
public List<JobExecution> getJobExecutions(JobInstance instance) throws NoSuchJobInstanceException, JobSecurityException Return all job executions belonging to the specified job instance. Parameters instance:JobInstance specifies the job instance. Returns:List<JobExecution> list of job executions Exceptions NoSuchJobInstanceException: Thrown when the instance parameter value doesn't correspond to a job instance recognized by the implementation's repository. JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobExecutions

back to summary

public List<JobExecution> getJobExecutions(JobInstance instance) throws NoSuchJobInstanceException, JobSecurityException

Return all job executions belonging to the specified job instance.

Parameters

instance:JobInstance: specifies the job instance.

Returns:List<JobExecution>

list of job executions

Exceptions

NoSuchJobInstanceException:: Thrown when the instance parameter value doesn't correspond to a job instance recognized by the implementation's repository.
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobInstance	back to summary
public JobInstance getJobInstance(long executionId) throws NoSuchJobExecutionException, JobSecurityException Return the job instance for the specified execution id. Parameters executionId:long specifies the job execution. Returns:JobInstance job instance Exceptions NoSuchJobExecutionException: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository. JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobInstance

back to summary

public JobInstance getJobInstance(long executionId) throws NoSuchJobExecutionException, JobSecurityException

Return the job instance for the specified execution id.

Parameters

executionId:long: specifies the job execution.

Returns:JobInstance

job instance

Exceptions

NoSuchJobExecutionException:: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository.
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobInstanceCount	back to summary
public int getJobInstanceCount(String jobName) throws NoSuchJobException, JobSecurityException Returns number of instances of a job with a particular name. Parameters jobName:String specifies the name of the job. Returns:int count of instances of the named job. Exceptions NoSuchJobException: Thrown when the jobName parameter value doesn't correspond to a job recognized by the implementation's repository. JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobInstanceCount

back to summary

public int getJobInstanceCount(String jobName) throws NoSuchJobException, JobSecurityException

Returns number of instances of a job with a particular name.

Parameters

jobName:String: specifies the name of the job.

Returns:int

count of instances of the named job.

Exceptions

NoSuchJobException:: Thrown when the jobName parameter value doesn't correspond to a job recognized by the implementation's repository.
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobInstances	back to summary
public List<JobInstance> getJobInstances(String jobName, int start, int count) throws NoSuchJobException, JobSecurityException Returns all JobInstances belonging to a job with a particular name in reverse chronological order. Parameters jobName:String specifies the job name. start:int specifies the relative starting number (zero based) to return from the maximal list of job instances. count:int specifies the number of job instances to return from the starting position of the maximal list of job instances. Returns:List<JobInstance> list of JobInstances. Exceptions NoSuchJobException: Thrown when the jobName parameter value doesn't correspond to a job recognized by the implementation's repository. JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobInstances

back to summary

public List<JobInstance> getJobInstances(String jobName, int start, int count) throws NoSuchJobException, JobSecurityException

Returns all JobInstances belonging to a job with a particular name in reverse chronological order.

Parameters

jobName:String: specifies the job name.
start:int: specifies the relative starting number (zero based) to return from the maximal list of job instances.
count:int: specifies the number of job instances to return from the starting position of the maximal list of job instances.

Returns:List<JobInstance>

list of JobInstances.

Exceptions

NoSuchJobException:: Thrown when the jobName parameter value doesn't correspond to a job recognized by the implementation's repository.
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobNames	back to summary
public Set<String> getJobNames() throws JobSecurityException Returns a set of all job names known to the batch runtime. Returns:Set<String> a set of job names. Exceptions JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getJobNames

back to summary

public Set<String> getJobNames() throws JobSecurityException

Returns a set of all job names known to the batch runtime.

Returns:Set<String>

a set of job names.

Exceptions

JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getParameters	back to summary
public Properties getParameters(long executionId) throws NoSuchJobExecutionException, JobSecurityException Returns job parameters for a specified job instance. These are the key/value pairs specified when the instance was originally created by the start method. Parameters executionId:long specifies the execution from which to retrieve the parameters. Returns:Properties a Properties object containing the key/value job parameter pairs. Exceptions NoSuchJobExecutionException: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository. JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getParameters

back to summary

public Properties getParameters(long executionId) throws NoSuchJobExecutionException, JobSecurityException

Returns job parameters for a specified job instance. These are the key/value pairs specified when the instance was originally created by the start method.

Parameters

executionId:long: specifies the execution from which to retrieve the parameters.

Returns:Properties

a Properties object containing the key/value job parameter pairs.

Exceptions

NoSuchJobExecutionException:: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository.
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getRunningExecutions	back to summary
public List<Long> getRunningExecutions(String jobName) throws NoSuchJobException, JobSecurityException Returns execution ids for job instances with the specified name that have running executions. Parameters jobName:String specifies the job name. Returns:List<Long> a list of execution ids. Exceptions NoSuchJobException: Thrown when the jobName parameter value doesn't correspond to a job recognized by the implementation's repository. JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getRunningExecutions

back to summary

public List<Long> getRunningExecutions(String jobName) throws NoSuchJobException, JobSecurityException

Returns execution ids for job instances with the specified name that have running executions.

Parameters

jobName:String: specifies the job name.

Returns:List<Long>

a list of execution ids.

Exceptions

NoSuchJobException:: Thrown when the jobName parameter value doesn't correspond to a job recognized by the implementation's repository.
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getStepExecutions	back to summary
public List<StepExecution> getStepExecutions(long jobExecutionId) throws NoSuchJobExecutionException, JobSecurityException Return StepExecutions for specified execution id. Parameters jobExecutionId:long specifies the job execution. Returns:List<StepExecution> step executions (order not guaranteed) Exceptions NoSuchJobExecutionException: Thrown when the jobExecutionId parameter value doesn't correspond to an execution recognized by the implementation's repository. JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

getStepExecutions

back to summary

public List<StepExecution> getStepExecutions(long jobExecutionId) throws NoSuchJobExecutionException, JobSecurityException

Return StepExecutions for specified execution id.

Parameters

jobExecutionId:long: specifies the job execution.

Returns:List<StepExecution>

step executions (order not guaranteed)

Exceptions

NoSuchJobExecutionException:: Thrown when the jobExecutionId parameter value doesn't correspond to an execution recognized by the implementation's repository.
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

restart	back to summary
public long restart(long executionId, Properties restartParameters) throws JobExecutionAlreadyCompleteException, NoSuchJobExecutionException, JobExecutionNotMostRecentException, JobRestartException, JobSecurityException Restarts a failed or stopped job instance, which executes asynchronously. Parameters executionId:long specifies the execution to to restart. This execution must be the most recent execution that ran. restartParameters:Properties specifies the keyword/value pairs for attribute substitution in the Job XML. Returns:long new executionId Exceptions JobExecutionAlreadyCompleteException: Thrown when the job execution associated with executionId is currently complete. NoSuchJobExecutionException: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository. JobExecutionNotMostRecentException: Thrown when the executionId parameter value does not represent the most recent execution for the corresponding job instance. JobRestartException: Thrown for some error condition other than those listed by the other checked exceptions on this method. Note that batch runtime implementations have a choice of detecting certain conditions via upfront validation or only later, during execution. This nets out to the fact that one implementation may throw JobRestartException on a given error condition while another may not. JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

restart

back to summary

public long restart(long executionId, Properties restartParameters) throws JobExecutionAlreadyCompleteException, NoSuchJobExecutionException, JobExecutionNotMostRecentException, JobRestartException, JobSecurityException

Restarts a failed or stopped job instance, which executes asynchronously.

Parameters

executionId:long: specifies the execution to to restart. This execution must be the most recent execution that ran.
restartParameters:Properties: specifies the keyword/value pairs for attribute substitution in the Job XML.

Returns:long

new executionId

Exceptions

JobExecutionAlreadyCompleteException:: Thrown when the job execution associated with executionId is currently complete.
NoSuchJobExecutionException:: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository.
JobExecutionNotMostRecentException:: Thrown when the executionId parameter value does not represent the most recent execution for the corresponding job instance.
JobRestartException:: Thrown for some error condition other than those listed by the other checked exceptions on this method. Note that batch runtime implementations have a choice of detecting certain conditions via upfront validation or only later, during execution. This nets out to the fact that one implementation may throw JobRestartException on a given error condition while another may not.
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

start	back to summary
public long start(String jobXMLName, Properties jobParameters) throws JobStartException, JobSecurityException Creates a new job instance and starts the first execution of that instance, which executes asynchronously. Note the Job XML describing the job is first searched for by name according to a means prescribed by the batch runtime implementation. This may vary by implementation. If the Job XML is not found by that means, then the batch runtime must search for the specified Job XML as a resource from the META-INF/batch-jobs directory based on the current class loader. Job XML files under META-INF/batch-jobs directory follow a naming convention of "name".xml where "name" is the value of the jobXMLName parameter (see below). Parameters jobXMLName:String specifies the name of the Job XML describing the job. jobParameters:Properties specifies the keyword/value pairs for attribute substitution in the Job XML. Returns:long executionId for the job execution. Exceptions JobStartException: Thrown for some error condition other than those listed by the other checked exceptions on this method. Note that batch runtime implementations have a choice of detecting certain conditions via upfront validation or only later, during execution. This nets out to the fact that one implementation may throw JobStartException on a given error condition while another may not. JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

start

back to summary

public long start(String jobXMLName, Properties jobParameters) throws JobStartException, JobSecurityException

Creates a new job instance and starts the first execution of that instance, which executes asynchronously. Note the Job XML describing the job is first searched for by name according to a means prescribed by the batch runtime implementation. This may vary by implementation. If the Job XML is not found by that means, then the batch runtime must search for the specified Job XML as a resource from the META-INF/batch-jobs directory based on the current class loader. Job XML files under META-INF/batch-jobs directory follow a naming convention of "name".xml where "name" is the value of the jobXMLName parameter (see below).

Parameters

jobXMLName:String: specifies the name of the Job XML describing the job.
jobParameters:Properties: specifies the keyword/value pairs for attribute substitution in the Job XML.

Returns:long

executionId for the job execution.

Exceptions

JobStartException:: Thrown for some error condition other than those listed by the other checked exceptions on this method. Note that batch runtime implementations have a choice of detecting certain conditions via upfront validation or only later, during execution. This nets out to the fact that one implementation may throw JobStartException on a given error condition while another may not.
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

stop	back to summary
public void stop(long executionId) throws NoSuchJobExecutionException, JobExecutionNotRunningException, JobSecurityException Request a running job execution stops. This method notifies the job execution to stop and then returns. The job execution normally stops and does so asynchronously. Note JobOperator cannot guarantee the jobs stops: it is possible a badly behaved batch application does not relinquish control. Note for partitioned batchlet steps the Batchlet stop method is invoked on each thread actively processing a partition. Parameters executionId:long specifies the job execution to stop. The job execution must be running. Exceptions NoSuchJobExecutionException: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository. JobExecutionNotRunningException: Thrown when the associated execution is not running (is not already STARTED or STARTING). JobSecurityException: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

stop

back to summary

public void stop(long executionId) throws NoSuchJobExecutionException, JobExecutionNotRunningException, JobSecurityException

Request a running job execution stops. This method notifies the job execution to stop and then returns. The job execution normally stops and does so asynchronously. Note JobOperator cannot guarantee the jobs stops: it is possible a badly behaved batch application does not relinquish control.

Note for partitioned batchlet steps the Batchlet stop method is invoked on each thread actively processing a partition.

Parameters

executionId:long: specifies the job execution to stop. The job execution must be running.

Exceptions

NoSuchJobExecutionException:: Thrown when the executionId parameter value doesn't correspond to an execution recognized by the implementation's repository.
JobExecutionNotRunningException:: Thrown when the associated execution is not running (is not already STARTED or STARTING).
JobSecurityException:: Thrown when the implementation determines that execution of this method with these parameters is not authorized (by some implementation-specific mechanism).

public Interface JobOperator

Method Summary

Method Detail