org.springframework.batch.core.explore

## Interface JobExplorer

- All Known Implementing Classes:
    SimpleJobExplorer

      public interface JobExplorer

  Entry point for browsing executions of running or historical jobs and steps. Since the data may be re-hydrated from persistent storage, it may not contain volatile fields that would have been present when the execution was active.
  Since:
    2.0
  Author:
    Dave Syer, Michael Minella, Will Schipp, Mahmoud Ben Hassine

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.List<JobInstance>` | `findJobInstancesByJobName(java.lang.String jobName, int start, int count)` Fetch `JobInstance` values in descending order of creation (and there for usually of first execution) with a 'like'/wildcard criteria.
    `java.util.Set<JobExecution>` | `findRunningJobExecutions(java.lang.String jobName)` Retrieve running job executions.
    `JobExecution` | `getJobExecution(java.lang.Long executionId)` Retrieve a `JobExecution` by its id.
    `java.util.List<JobExecution>` | `getJobExecutions(JobInstance jobInstance)` Retrieve job executions by their job instance.
    `JobInstance` | `getJobInstance(java.lang.Long instanceId)`
    `int` | `getJobInstanceCount(java.lang.String jobName)` Query the repository for the number of unique `JobInstance`s associated with the supplied job name.
    `java.util.List<JobInstance>` | `getJobInstances(java.lang.String jobName, int start, int count)` Fetch `JobInstance` values in descending order of creation (and therefore usually of first execution).
    `java.util.List<java.lang.String>` | `getJobNames()` Query the repository for all unique `JobInstance` names (sorted alphabetically).
    `default JobExecution` | `getLastJobExecution(JobInstance jobInstance)` Find the last `JobExecution` that has been created for a given `JobInstance`.
    `default JobInstance` | `getLastJobInstance(java.lang.String jobName)` Find the last job instance by Id for the given job.
    `StepExecution` | `getStepExecution(java.lang.Long jobExecutionId, java.lang.Long stepExecutionId)` Retrieve a `StepExecution` by its id and parent `JobExecution` id.

- - ### Method Detail

    - #### getJobInstances

          java.util.List<JobInstance> getJobInstances(java.lang.String jobName,
                                                      int start,
                                                      int count)

      Fetch `JobInstance` values in descending order of creation (and therefore usually of first execution).
      Parameters:
        `jobName` - the name of the job to query
        `start` - the start index of the instances to return
        `count` - the maximum number of instances to return
      Returns:
        the `JobInstance` values up to a maximum of count values

    - #### getLastJobInstance

          @Nullable
          default JobInstance getLastJobInstance(java.lang.String jobName)

      Find the last job instance by Id for the given job.
      Parameters:
        `jobName` - name of the job
      Returns:
        the last job instance by Id if any or null otherwise
      Since:
        4.2

    - #### getJobExecution

          @Nullable
          JobExecution getJobExecution(@Nullable
                                                 java.lang.Long executionId)

      Retrieve a `JobExecution` by its id. The complete object graph for this execution should be returned (unless otherwise indicated) including the parent `JobInstance` and associated `ExecutionContext` and `StepExecution` instances (also including their execution contexts).
      Parameters:
        `executionId` - the job execution id
      Returns:
        the `JobExecution` with this id, or null if not found

    - #### getStepExecution

          @Nullable
          StepExecution getStepExecution(@Nullable
                                                   java.lang.Long jobExecutionId,
                                                   @Nullable
                                                   java.lang.Long stepExecutionId)

      Retrieve a `StepExecution` by its id and parent `JobExecution` id. The execution context for the step should be available in the result, and the parent job execution should have its primitive properties, but may not contain the job instance information.
      Parameters:
        `jobExecutionId` - the parent job execution id
        `stepExecutionId` - the step execution id
      Returns:
        the `StepExecution` with this id, or null if not found
      See Also:
        `getJobExecution(Long)`

    - #### getJobInstance

          @Nullable
          JobInstance getJobInstance(@Nullable
                                               java.lang.Long instanceId)

      Parameters:
        `instanceId` - `Long` id for the jobInstance to obtain.
      Returns:
        the `JobInstance` with this id, or null

    - #### getJobExecutions

          java.util.List<JobExecution> getJobExecutions(JobInstance jobInstance)

      Retrieve job executions by their job instance. The corresponding step executions may not be fully hydrated (e.g. their execution context may be missing), depending on the implementation. Use `getStepExecution(Long, Long)` to hydrate them in that case.
      Parameters:
        `jobInstance` - the `JobInstance` to query
      Returns:
        the set of all executions for the specified `JobInstance`

    - #### getLastJobExecution

          @Nullable
          default JobExecution getLastJobExecution(JobInstance jobInstance)

      Find the last `JobExecution` that has been created for a given `JobInstance`.
      Parameters:
        `jobInstance` - the `JobInstance`
      Returns:
        the last `JobExecution` that has been created for this instance or `null` if no job execution is found for the given job instance.
      Since:
        4.2

    - #### findRunningJobExecutions

          java.util.Set<JobExecution> findRunningJobExecutions(@Nullable
                                                               java.lang.String jobName)

      Retrieve running job executions. The corresponding step executions may not be fully hydrated (e.g. their execution context may be missing), depending on the implementation. Use `getStepExecution(Long, Long)` to hydrate them in that case.
      Parameters:
        `jobName` - the name of the job
      Returns:
        the set of running executions for jobs with the specified name

    - #### getJobNames

          java.util.List<java.lang.String> getJobNames()

      Query the repository for all unique `JobInstance` names (sorted alphabetically).
      Returns:
        the set of job names that have been executed

    - #### findJobInstancesByJobName

          java.util.List<JobInstance> findJobInstancesByJobName(java.lang.String jobName,
                                                                int start,
                                                                int count)

      Fetch `JobInstance` values in descending order of creation (and there for usually of first execution) with a 'like'/wildcard criteria.
      Parameters:
        `jobName` - the name of the job to query for.
        `start` - the start index of the instances to return.
        `count` - the maximum number of instances to return.
      Returns:
        a list of `JobInstance` for the job name requested.

    - #### getJobInstanceCount

          int getJobInstanceCount(@Nullable
                                  java.lang.String jobName)
                           throws NoSuchJobException

      Query the repository for the number of unique `JobInstance`s associated with the supplied job name.
      Parameters:
        `jobName` - the name of the job to query for
      Returns:
        the number of `JobInstance`s that exist within the associated job repository
      Throws:
        `NoSuchJobException` - thrown when there is no `JobInstance` for the jobName specified.