org.apache.sling.event.jobs

## Interface JobManager

    @ProviderType
    public interface JobManager

The job manager is the heart of the job processing.

The job manager allows to create new jobs, search for jobs and get statistics about the current state.

The terminology used in the job manager is slightly different from common terminology: Each job has a topic and a topic is associated with a queue. Queues can be created through configuration and each queue can process one or more topics.

Since:
  3.0

### Nested Class Summary

Nested Classes
`static class` `JobManager.QueryType` The requested job types for the query.

### Method Summary

All Methods Instance Methods Abstract Methods
`Job` `addJob(String topic, Map<String,Object> properties)` Add a new job If the topic is `null` or illegal, no job is created and `null` is returned.
`JobBuilder` `createJob(String topic)` Fluent API to create, start and schedule new jobs
`Collection<Job>` `findJobs(JobManager.QueryType type, String topic, long limit, Map<String,Object>... templates)` Return all jobs of a given type.
`Job` `getJob(String topic, Map<String,Object> template)` Find a job - either queued or active.
`Job` `getJobById(String jobId)` Return a job based on the unique id.
`Queue` `getQueue(String name)` Return a queue with a specific name (if running)
`Iterable<Queue>` `getQueues()` Return an iterator for all available queues.
`Collection<ScheduledJobInfo>` `getScheduledJobs()` Return all available job schedules.
`Collection<ScheduledJobInfo>` `getScheduledJobs(String topic, long limit, Map<String,Object>... templates)` Return all matching available job schedules.
`Statistics` `getStatistics()` Return statistics information about all queues.
`Iterable<TopicStatistics>` `getTopicStatistics()` Return statistics information about job topics.
`boolean` `removeJobById(String jobId)` Removes the job even if it is currently in processing.
`Job` `retryJobById(String jobId)` Retry a cancelled job.
`void` `stopJobById(String jobId)` Stop a job.

### Method Detail

#### getStatistics

    Statistics getStatistics()

Return statistics information about all queues.

Returns:
  The statistics.

#### getTopicStatistics

    Iterable<TopicStatistics> getTopicStatistics()

Return statistics information about job topics.

Returns:
  The statistics for all topics.

#### getQueue

    Queue getQueue(String name)

Return a queue with a specific name (if running)

Parameters:
  `name` - The queue name
Returns:
  The queue or `null`

#### getQueues

    Iterable<Queue> getQueues()

Return an iterator for all available queues.

Returns:
  An iterator for all queues.

#### addJob

    Job addJob(String topic,
               Map<String,Object> properties)

Add a new job If the topic is `null` or illegal, no job is created and `null` is returned. If properties are provided, all of them must be serializable. If there are non serializable objects in the properties, no job is created and `null` is returned. A job topic is a hierarchical name separated by dashes, each part has to start with a letter, allowed characters are letters, numbers and the underscore. The returned job object is a snapshot of the job state taken at the time of creation. Updates to the job state are not reflected and the client needs to get a new job object using the job id. If the queue for processing this job is configured to drop the job, `null` is returned as well.

Parameters:
  `topic` - The required job topic.
  `properties` - Optional job properties. The properties must be serializable.
Returns:
  The new job - or `null` if the job could not be created.
Since:
  1.2

#### getJobById

    Job getJobById(String jobId)

Return a job based on the unique id. The returned job object is a snapshot of the job state taken at the time of the call. Updates to the job state are not reflected and the client needs to get a new job object using the job id.

Parameters:
  `jobId` - The unique identifier from `Job.getId()`
Returns:
  A job or `null`
Since:
  1.2

#### removeJobById

    boolean removeJobById(String jobId)

Removes the job even if it is currently in processing. If the job exists and is not in processing, it gets removed from the processing queue. If the job exists and is in processing, it is removed from the persistence layer, however processing is not stopped.

Parameters:
  `jobId` - The unique identifier from `Job.getId()`
Returns:
  `true` if the job could be removed or does not exist anymore. `false` otherwise.
Since:
  1.2

#### getJob

    Job getJob(String topic,
               Map<String,Object> template)

Find a job - either queued or active. This method searches for a job with the given topic and filter properties. If more than one job matches, the first one found is returned which could be any of the matching jobs. The returned job object is a snapshot of the job state taken at the time of the call. Updates to the job state are not reflected and the client needs to get a new job object using the job id.

Parameters:
  `topic` - Topic is required.
  `template` - The map acts like a template. The searched job must match the template (AND query).
Returns:
  A job or `null`
Since:
  1.2

#### findJobs

    Collection<Job> findJobs(JobManager.QueryType type,
                             String topic,
                             long limit,
                             Map<String,Object>... templates)

Return all jobs of a given type. Based on the type parameter, either the history of jobs can be returned or unfinished jobs. The type parameter can further specify which category of jobs should be returned: for the history either succeeded jobs, cancelled jobs or both in combination can be returned. For unfinished jobs, either queued jobs, started jobs or the combination can be returned. If the history is returned, the result set is sorted in descending order, listening the newest entry first. For unfinished jobs, the result set is sorted in ascending order. The returned job objects are a snapshot of the jobs state taken at the time of the call. Updates to the job states are not reflected and the client needs to get new job objects.

Parameters:
  `type` - Required parameter for the type. See above.
  `topic` - Topic can be used as a filter, if it is non-null, only jobs with this topic will be returned.
  `limit` - A positive number indicating the maximum number of jobs returned by the iterator. A value of zero or less indicates that all jobs should be returned.
  `templates` - A list of filter property maps. Each map acts like a template. The searched job must match the template (AND query). By providing several maps, different filters are possible (OR query).
Returns:
  A collection of jobs - the collection might be empty.
Since:
  1.2

#### stopJobById

    void stopJobById(String jobId)

Stop a job. When a job is stopped and the job consumer supports stopping the job processing, it is up to the job consumer how the stopping is handled. The job can be marked as finished successful, permanently failed or being retried.

Parameters:
  `jobId` - The job id
Since:
  1.3

#### retryJobById

    Job retryJobById(String jobId)

Retry a cancelled job. If a job has failed permanently it can be requeued with this method. The job will be removed from the history and put into the queue again. The new job will get a new job id. For all other jobs calling this method has no effect and it simply returns `null`.

Parameters:
  `jobId` - The job id.
Returns:
  If the job is requeued, the new job object otherwise `null`

#### createJob

    JobBuilder createJob(String topic)

Fluent API to create, start and schedule new jobs

Parameters:
  `topic` - Required topic
Returns:
  A job builder
Since:
  1.3

#### getScheduledJobs

    Collection<ScheduledJobInfo> getScheduledJobs()

Return all available job schedules.

Returns:
  A collection of scheduled job infos
Since:
  1.3

#### getScheduledJobs

    Collection<ScheduledJobInfo> getScheduledJobs(String topic,
                                                  long limit,
                                                  Map<String,Object>... templates)

Return all matching available job schedules.

Parameters:
  `topic` - Topic can be used as a filter, if it is non-null, only jobs with this topic will be returned.
  `limit` - A positive number indicating the maximum number of jobs returned by the iterator. A value of zero or less indicates that all jobs should be returned.
  `templates` - A list of filter property maps. Each map acts like a template. The searched job must match the template (AND query). By providing several maps, different filters are possible (OR query).
Returns:
  All matching scheduled job infos.
Since:
  1.4