Interface JobOperator


  • public interface JobOperator
    JobOperator provide the interface for operating on batch jobs. Through the JobOperator a program can start, stop, and restart jobs. It can additionally inspect job history, to discover what jobs are currently running and what jobs have previously run. The JobOperator interface imposes no security constraints. However, the implementer is free to limit JobOperator methods with a security scheme of its choice. The implementer should terminate any method that is limited by the security scheme with a JobSecurityException.
    • Method Detail

      • getJobNames

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

        int getJobInstanceCount​(String jobName)
                         throws NoSuchJobException,
                                JobSecurityException
        Returns number of instances of a job with a particular name.
        Parameters:
        jobName - specifies the name of the job.
        Returns:
        count of instances of the named job.
        Throws:
        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

        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 - specifies the job name.
        start - specifies the relative starting number (zero based) to return from the maximal list of job instances.
        count - specifies the number of job instances to return from the starting position of the maximal list of job instances.
        Returns:
        list of JobInstances.
        Throws:
        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

        List<Long> getRunningExecutions​(String jobName)
                                 throws NoSuchJobException,
                                        JobSecurityException
        Returns execution ids for job instances with the specified name that have running executions.
        Parameters:
        jobName - specifies the job name.
        Returns:
        a list of execution ids.
        Throws:
        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).
      • getParameters

        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 - specifies the execution from which to retrieve the parameters.
        Returns:
        a Properties object containing the key/value job parameter pairs.
        Throws:
        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).
      • start

        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 - specifies the name of the Job XML describing the job.
        jobParameters - specifies the keyword/value pairs for attribute substitution in the Job XML.
        Returns:
        executionId for the job execution.
        Throws:
        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).
      • restart

        long restart​(long executionId,
                     Properties restartParameters)
              throws JobExecutionAlreadyCompleteException,
                     NoSuchJobExecutionException,
                     JobExecutionNotMostRecentException,
                     JobRestartException,
                     JobSecurityException
        Restarts a failed or stopped job instance, which executes asynchronously.
        Parameters:
        executionId - specifies the execution to to restart. This execution must be the most recent execution that ran.
        restartParameters - specifies the keyword/value pairs for attribute substitution in the Job XML.
        Returns:
        new executionId
        Throws:
        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).
      • stop

        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 - specifies the job execution to stop. The job execution must be running.
        Throws:
        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).
      • abandon

        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 - specifies the job execution to abandon.
        Throws:
        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).
      • getJobInstance

        JobInstance getJobInstance​(long executionId)
                            throws NoSuchJobExecutionException,
                                   JobSecurityException
        Return the job instance for the specified execution id.
        Parameters:
        executionId - specifies the job execution.
        Returns:
        job instance
        Throws:
        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

        List<JobExecution> getJobExecutions​(JobInstance instance)
                                     throws NoSuchJobInstanceException,
                                            JobSecurityException
        Return all job executions belonging to the specified job instance.
        Parameters:
        instance - specifies the job instance.
        Returns:
        list of job executions
        Throws:
        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).
      • getJobExecution

        JobExecution getJobExecution​(long executionId)
                              throws NoSuchJobExecutionException,
                                     JobSecurityException
        Return job execution for specified execution id.
        Parameters:
        executionId - specifies the job execution.
        Returns:
        job execution
        Throws:
        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).
      • getStepExecutions

        List<StepExecution> getStepExecutions​(long jobExecutionId)
                                       throws NoSuchJobExecutionException,
                                              JobSecurityException
        Return StepExecutions for specified execution id.
        Parameters:
        jobExecutionId - specifies the job execution.
        Returns:
        step executions (order not guaranteed)
        Throws:
        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).