/*
 * 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 executor consumes a job.
 * <p>
 * A job executor registers itself with the {@link #PROPERTY_TOPICS} service registration
 * property. The value of this property defines which topics an executor 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 executor decides to process the job asynchronously, the processing must finish
 * within the current lifetime of the job executor. If the executor (or the instance
 * of the executor) dies, the job processing will mark this processing as failed and
 * reschedule.
 *
 * @since 1.1
 */
@ConsumerType
public interface JobExecutor {

    /**
     * Service registration property defining the jobs this executor is able to process.
     * The value is either a string or an array of strings.
     */
    String PROPERTY_TOPICS = "job.topics";

    /**
     * Execute the job.
     *
     * If the job has been processed successfully, a job result of "succeeded" should be returned. This result can
     * be generated by calling <code>JobExecutionContext.result().succeeded()</code>
     *
     * If the job has not been processed completely, but might be rescheduled "failed" should be returned.
     * This result can be generated by calling <code>JobExecutionContext.result().failed()</code>.
     *
     * If the job processing failed and should not be rescheduled, "cancelled" should be returned.
     * This result can be generated by calling <code>JobExecutionContext.result().cancelled()</code>.
     *
     * If the executor decides to process the job asynchronously it should return <code>null</code>
     * and notify the job manager by using the {@link JobExecutionContext#asyncProcessingFinished(JobExecutionResult)}
     * method of the processing result.
     *
     * If the processing fails with throwing an exception/throwable, the process will not be rescheduled
     * and treated like the method would have returned a "cancelled" result.
     *
     * Additional information can be added to the result by using the builder pattern available
     * from {@link JobExecutionContext#result()}.
     *
     * @param job The job
     * @param context The execution context.
     * @return The job execution result or <code>null</code> for asynchronous processing.
     */
    JobExecutionResult process(Job job, JobExecutionContext context);
}