| /* |
| * 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.consumer; |
| |
| import org.apache.sling.event.jobs.Job; |
| |
| import org.osgi.annotation.versioning.ConsumerType; |
| |
| |
| |
| /** |
| * A job consumer consumes a job. |
| * <p> |
| * If the job consumer needs more features like providing progress information or adding |
| * more information of the processing, {@link JobExecutor} should be implemented instead. |
| * <p> |
| * A job consumer registers itself with the {@link #PROPERTY_TOPICS} service registration |
| * property. The value of this property defines which topics a consumer is able to process. |
| * Each string value of this property is either |
| * <ul> |
| * <li>a job topic, or |
| * <li>a topic category ending with "/*" which means all topics in this category, or |
| * <li>a topic category ending with "/**" which means all topics in this category and all |
| * sub categories. This matching is new since version 1.2. |
| * </ul> |
| * A consumer registering for just "*" or "**" is not considered. |
| * <p> |
| * For example, the value {@code org/apache/sling/jobs/*} matches the topics |
| * {@code org/apache/sling/jobs/a} and {@code org/apache/sling/jobs/b} but neither |
| * {@code org/apache/sling/jobs} nor {@code org/apache/sling/jobs/subcategory/a}. A value of |
| * {@code org/apache/sling/jobs/**} matches the same topics but also all sub topics |
| * like {@code org/apache/sling/jobs/subcategory/a} or {@code org/apache/sling/jobs/subcategory/a/c/d}. |
| * <p> |
| * If there is more than one job consumer or executor registered for a job topic, the selection is as |
| * follows: |
| * <ul> |
| * <li>If there is a single consumer registering for the exact topic, this one is used. |
| * <li>If there is more than a single consumer registering for the exact topic, the one |
| * with the highest service ranking is used. If the ranking is equal, the one with |
| * the lowest service ID is used. |
| * <li>If there is a single consumer registered for the category, it is used. |
| * <li>If there is more than a single consumer registered for the category, the service |
| * with the highest service ranking is used. If the ranking is equal, the one with |
| * the lowest service ID is used. |
| * <li>The search continues with consumer registered for deep categories. The nearest one |
| * is tried next. If there are several, the one with the highest service ranking is |
| * used. If the ranking is equal, the one with the lowest service ID is used. |
| * </ul> |
| * <p> |
| * If the consumer decides to process the job asynchronously, the processing must finish |
| * within the current lifetime of the job consumer. If the consumer (or the instance |
| * of the consumer) dies, the job processing will mark this processing as failed and |
| * reschedule. |
| * |
| * @since 1.0 |
| */ |
| @ConsumerType |
| public interface JobConsumer { |
| |
| /** |
| * The result of the job processing. |
| */ |
| enum JobResult { |
| /** Processing finished successfully. */ |
| OK, |
| /** Processing failed but might be retried. */ |
| FAILED, |
| /** Processing failed permanently and must not be retried. */ |
| CANCEL, |
| /** Processing will be done asynchronously. */ |
| ASYNC |
| } |
| |
| /** Job property containing an asynchronous handler. */ |
| String PROPERTY_JOB_ASYNC_HANDLER = ":sling:jobs:asynchandler"; |
| |
| /** |
| * If the consumer decides to process the job asynchronously, this handler |
| * interface can be used to notify finished processing. The asynchronous |
| * handler can be retried using the property name {@link #PROPERTY_JOB_ASYNC_HANDLER}. |
| */ |
| interface AsyncHandler { |
| |
| void failed(); |
| |
| void ok(); |
| |
| void cancel(); |
| } |
| |
| /** |
| * Service registration property defining the jobs this consumer is able to process. |
| * The value is either a string or an array of strings. |
| */ |
| String PROPERTY_TOPICS = "job.topics"; |
| |
| |
| /** |
| * Execute the job. |
| * <p> |
| * If the job has been processed successfully, {@link JobResult#OK} should be returned. |
| * If the job has not been processed completely, but might be rescheduled {@link JobResult#FAILED} |
| * should be returned. |
| * If the job processing failed and should not be rescheduled, {@link JobResult#CANCEL} should |
| * be returned. |
| * <p> |
| * If the consumer decides to process the job asynchronously it should return {@link JobResult#ASYNC} |
| * and notify the job manager by using the {@link AsyncHandler} interface. |
| * <p> |
| * If the processing fails with throwing an exception/throwable, the process will not be rescheduled |
| * and treated like the method would have returned {@link JobResult#CANCEL}. |
| * |
| * @param job The job |
| * @return The job result |
| */ |
| JobResult process(Job job); |
| } |