Package 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

  Modifier and Type
  Method
  Description
  `List<JobInstance>`
  `findJobInstancesByJobName(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.
  `Set<JobExecution>`
  `findRunningJobExecutions(String jobName)`
  Retrieve running job executions.
  `JobExecution`
  `getJobExecution(Long executionId)`
  Retrieve a `JobExecution` by its id.
  `List<JobExecution>`
  `getJobExecutions(JobInstance jobInstance)`
  Retrieve job executions by their job instance.
  `JobInstance`
  `getJobInstance(Long instanceId)`
  `int`
  `getJobInstanceCount(String jobName)`
  Query the repository for the number of unique `JobInstance`s associated with the supplied job name.
  `List<JobInstance>`
  `getJobInstances(String jobName, int start, int count)`
  Fetch `JobInstance` values in descending order of creation (and therefore usually of first execution).
  `List<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(String jobName)`
  Find the last job instance by Id for the given job.
  `StepExecution`
  `getStepExecution(Long jobExecutionId, Long stepExecutionId)`
  Retrieve a `StepExecution` by its id and parent `JobExecution` id.

- ## Method Details

  - ### getJobInstances

    List<JobInstance> getJobInstances(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(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 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 Long jobExecutionId, @Nullable 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 Long instanceId)
    Parameters:
      `instanceId` - `Long` id for the jobInstance to obtain.
    Returns:
      the `JobInstance` with this id, or null

  - ### getJobExecutions

    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

    Set<JobExecution> findRunningJobExecutions(@Nullable 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

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

  - ### findJobInstancesByJobName

    List<JobInstance> findJobInstancesByJobName(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 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.