Package org.apache.sling.event.jobs.consumer

Interface JobExecutor

  • @ConsumerType
public interface JobExecutor
    A job executor consumes a job.

    A job executor registers itself with the 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

    • a job topic, or
    • a topic category ending with "/*" which means all topics in this category, or
    • a topic category ending with "/**" which means all topics in this category and all sub categories. This matching is new since version 1.2.
    A consumer registering for just "*" or "**" is not considered.

    For example, the value org/apache/sling/jobs/* matches the topics org/apache/sling/jobs/a and org/apache/sling/jobs/b but neither org/apache/sling/jobs nor org/apache/sling/jobs/subcategory/a. A value of org/apache/sling/jobs/** matches the same topics but also all sub topics like org/apache/sling/jobs/subcategory/a or org/apache/sling/jobs/subcategory/a/c/d.

    If there is more than one job consumer or executor registered for a job topic, the selection is as follows:

    • If there is a single consumer registering for the exact topic, this one is used.
    • 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.
    • If there is a single consumer registered for the category, it is used.
    • 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.
    • 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.

    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

    • Field Detail

      • PROPERTY_TOPICS

        static final String PROPERTY_TOPICS
        Service registration property defining the jobs this executor is able to process. The value is either a string or an array of strings.
        See Also:
        Constant Field Values

    • Method Detail

      • process

        JobExecutionResult process​(Job job,
                           JobExecutionContext context)
        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 JobExecutionContext.result().succeeded() If the job has not been processed completely, but might be rescheduled "failed" should be returned. This result can be generated by calling JobExecutionContext.result().failed(). If the job processing failed and should not be rescheduled, "cancelled" should be returned. This result can be generated by calling JobExecutionContext.result().cancelled(). If the executor decides to process the job asynchronously it should return null and notify the job manager by using the 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 JobExecutionContext.result().
        Parameters:
        job - The job
        context - The execution context.
        Returns:
        The job execution result or null for asynchronous processing.