| /* |
| * 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.jobs; |
| |
| import org.jetbrains.annotations.NotNull; |
| import org.jetbrains.annotations.Nullable; |
| import org.osgi.annotation.versioning.ProviderType; |
| |
| /** |
| * Based on org.apache.sling.event.job.JobManager but trimmed down and adjusted to deal with distributed job queues. |
| */ |
| @ProviderType |
| public interface JobManager { |
| |
| |
| |
| |
| |
| /** |
| * Fluent API to create, start and schedule new jobs |
| * @param queue Required queue. This job will be submitted to the named queue. |
| * @param jobType required job type. The job will have a job type which is used to select the Job consumer that can |
| * process the job. |
| * @return A job builder |
| */ |
| @NotNull |
| JobBuilder newJobBuilder(@NotNull Types.JobQueue queue, @NotNull Types.JobType jobType); |
| |
| /** |
| * 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 <code>null</code> |
| */ |
| |
| @Nullable |
| Job getJobById(@NotNull String jobId); |
| |
| |
| /** |
| * This method comes from the existing Sling Event API and has not been implemented, as it was found |
| * not to be necessary to implement Jobs on the MoM API. Since it was not implemented |
| * It has not been included in the first release of the API. |
| * If it is required, it can be added and implemented. |
| * |
| * --------------------------------------- |
| * 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. |
| * |
| * Even if the method return null, the Job may exist remotely and has not yet sent any messages. |
| * |
| * @param queue Topic is required. |
| * @param template The map acts like a template. The searched job |
| * must match the template (AND query). |
| * @return A job or <code>null</code> |
| * @Nullable |
| * Job getJob(@NotNull Types.JobQueue queue, @NotNull Map<String, Object> template); |
| * |
| */ |
| |
| /** |
| * 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 |
| } |
| /** |
| * This method comes from the existing Sling Event API and has not been implemented, as it was found |
| * not to be necessary to implement Jobs on the MoM API. Since it was not implemented |
| * It has not been included in the first release of the API. |
| * If it is required, it can be added and implemented. |
| * |
| * --------------------------------------- |
| * 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. |
| * |
| * The Jobs returned are only jobs known to the JobManager instance. |
| * |
| * @param type Required parameter for the type. See above. |
| * @param queue Queue Name 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. |
| * @NotNull |
| * Collection<Job> findJobs(@NotNull QueryType type, @NotNull Types.JobQueue queue, long limit, @Nullable Map<String, Object>... templates); |
| */ |
| |
| /** |
| * Stop a job, by sending a message. |
| * 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 to stop. |
| */ |
| void stopJobById(@NotNull String jobId); |
| |
| /** |
| * Aborts a job by sending an abort message, may or may not be successful. |
| * |
| * |
| * @param jobId The unique identifier from {@link Job#getId()} |
| * @return <code>true</code> if the job could be removed or does not exist anymore. |
| * <code>false</code> if the job is not know to the job manager, however the abort message should be sent anyway. |
| */ |
| boolean abortJob(@NotNull String jobId); |
| |
| |
| /** |
| * Retry a cancelled job, by requeuing. |
| * 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 <code>null</code>. |
| * @param jobId The job id. |
| * @return If the job is requeued, the new job object otherwise <code>null</code> |
| */ |
| @Nullable |
| Job retryJobById(@NotNull String jobId); |
| |
| |
| } |