org.apache.sling.event.jobs.JobManager Maven / Gradle / Ivy
Show all versions of aem-sdk-api Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.sling.event.jobs;
import java.util.Collection;
import java.util.Map;
import org.osgi.annotation.versioning.ProviderType;
/**
* 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
*/
@ProviderType
public interface JobManager {
/**
* Return statistics information about all queues.
* @return The statistics.
*/
Statistics getStatistics();
/**
* Return statistics information about job topics.
* @return The statistics for all topics.
*/
Iterable getTopicStatistics();
/**
* Return a queue with a specific name (if running)
* @param name The queue name
* @return The queue or null
*/
Queue getQueue(String name);
/**
* Return an iterator for all available queues.
* @return An iterator for all queues.
*/
Iterable getQueues();
/**
* The requested job types for the query.
* This can either be all (unfinished) jobs, all activated (started) or all queued jobs.
*/
enum QueryType {
ALL, // all means all active and all queued
ACTIVE,
QUEUED,
HISTORY, // returns the complete history of cancelled and succeeded jobs (if available)
CANCELLED, // history of cancelled jobs (STOPPED, GIVEN_UP, ERROR, DROPPED)
SUCCEEDED, // history of succeeded jobs
STOPPED, // history of stopped jobs
GIVEN_UP, // history of given up jobs
ERROR, // history of jobs signaled CANCELLED or throw an exception
DROPPED // history of dropped jobs
}
/**
* 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.
*
* @param topic The required job topic.
* @param properties Optional job properties. The properties must be serializable.
* @return The new job - or null if the job could not be created.
* @since 1.2
*/
Job addJob(String topic, Map properties);
/**
* 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.
*
* @param jobId The unique identifier from {@link Job#getId()}
* @return A job or null
* @since 1.2
*/
Job getJobById(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.
*
* @param jobId The unique identifier from {@link Job#getId()}
* @return true if the job could be removed or does not exist anymore.
* false otherwise.
* @since 1.2
*/
boolean removeJobById(String jobId);
/**
* 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.
*
* @param topic Topic is required.
* @param template The map acts like a template. The searched job
* must match the template (AND query).
* @return A job or null
* @since 1.2
*/
Job getJob(String topic, Map template);
/**
* 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.
*
* @param type Required parameter for the type. See above.
* @param topic Topic can be used as a filter, if it is non-null, only jobs with this topic will be returned.
* @param 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.
* @param 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).
* @return A collection of jobs - the collection might be empty.
* @since 1.2
*/
Collection findJobs(QueryType type, String topic, long limit, Map... templates);
/**
* 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.
* @param jobId The job id
* @since 1.3
*/
void stopJobById(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.
* @param jobId The job id.
* @return If the job is requeued, the new job object otherwise null
*/
Job retryJobById(String jobId);
/**
* Fluent API to create, start and schedule new jobs
* @param topic Required topic
* @return A job builder
* @since 1.3
*/
JobBuilder createJob(final String topic);
/**
* Return all available job schedules.
* @return A collection of scheduled job infos
* @since 1.3
*/
Collection getScheduledJobs();
/**
* Return all matching available job schedules.
* @param topic Topic can be used as a filter, if it is non-null, only jobs with this topic will be returned.
* @param 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.
* @param 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).
* @return All matching scheduled job infos.
* @since 1.4
*/
Collection getScheduledJobs(String topic, long limit, Map... templates);
}