svn commit: r1738459 - /sling/site/trunk/content/documentation/bundles/apache-sling-eventing-and-job-handling.mdtext

[kw...@apache.org]

Author: kwin
Date: Sun Apr 10 18:52:15 2016
New Revision: 1738459

URL: http://svn.apache.org/viewvc?rev=1738459&view=rev
Log:
added section around scheduled jobs

some clarification on retries and the default queue

Modified:
    sling/site/trunk/content/documentation/bundles/apache-sling-eventing-and-job-handling.mdtext

Modified: sling/site/trunk/content/documentation/bundles/apache-sling-eventing-and-job-handling.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/apache-sling-eventing-and-job-handling.mdtext?rev=1738459&r1=1738458&r2=1738459&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/apache-sling-eventing-and-job-handling.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/apache-sling-eventing-and-job-handling.mdtext Sun Apr 10 18:52:15 2016
@@ -12,6 +12,7 @@ The bundle provides the following featur
 * [Scheduled Events](#sending-scheduled-events)
 
 To get some hands on code, you can refer to the following tutorials:
+
 * [How to Manage Events in Sling]({{ refs.how-to-manage-events-in-sling.path }})
 * [Scheduler Service (commons scheduler)]({{ refs.scheduler-service-commons-scheduler.path }})
 
@@ -52,6 +53,43 @@ The job topic follows the conventions fo
 
 As soon as the method returns from the job manager, the job is persisted and the job manager ensures that this job will be processed exactly once.
 
+### JobBuilder
+
+Instead of creating the jobs manually by calling `JobManager.addJob("my/special/jobtopic", props);` the `JobBuilder` can be used, which is retrieved via `JobManager.createJob("my/special/jobtopic")`.
+
+
+### Scheduled Jobs
+
+Scheduled Jobs are put in the queue at a specific time (optionally periodically). For that the `ScheduleBuilder` must be used which is retrieved via `JobBuilder.schedule()`.
+
+An example code for scheduling a jobs looks like this:
+
+    import org.apache.sling.jobs.JobManager;
+    import org.apache.sling.event.jobs.JobBuilder.ScheduleBuilder;
+    import org.apache.felix.scr.annotations.Component;
+    import org.apache.felix.scr.annotations.Reference;
+    import java.util.Map;
+    import java.util.HashMap;
+
+    @Component
+    public class MyComponent {
+
+        @Reference
+        private JobManager jobManager;
+
+        public void startScheduledJob() {
+            ScheduleBuilder scheduleBuilder = jobManager.startJob("my/special/jobtopic").schedule();
+            scheduleBuilder.daily(0,0); // execute daily at midnight
+            if (scheduleBuilder.add() == null) {
+            	// something went wrong here
+            }
+        }        
+    }
+
+
+Internally the scheduled Jobs use the [Commons Scheduler Service]({{ refs.scheduler-service-commons-scheduler.path }}). But in addition they are persisted (by default below `/var/eventing/scheduled-jobs`) and survive therefore even server restarts. When the scheduled time is reached, the job is automatically added as regular Sling Job through the `JobManager`.
+
+
 ### Job Consumers
 
 A job consumer is a service consuming and processing a job. It registers itself as an OSGi service together with a property defining which topics this consumer can process:
@@ -78,7 +116,7 @@ The *Job* interface allows to query the
 
 New jobs are first persisted in the resource tree (for failover etc.), then the job is distributed to an instance responsible for processing the job and on that instance the job is put into a processing queue. There are different types of queues defining how the jobs are processed (one after the other, in parallel etc.).
 
-For managing queues, the Sling Job Handler uses the OSGi ConfigAdmin - it is possible to configure one or more queue configurations through the ConfigAdmin. One way of creating and configuring such configurations is the Apache Felix WebConsole.
+For managing queues, the Sling Job Handler uses the OSGi ConfigAdmin - it is possible to configure one or more queue configurations through the ConfigAdmin. One way of creating and configuring such configurations is the Apache Felix WebConsole. If there is no specific queue configuration maintained for the given job topic, the Sling Job Handler falls back to using the `Apache Sling Job Default Queue` (which can be configured through OSGi as well).
 
 #### Queue Configurations
 
@@ -90,7 +128,7 @@ A queue configuration can have the follo
 | `queue.type` | The type of the queue: ORDERED, UNORDERED, TOPIC_ROUND_ROBIN |
 | `queue.topics` | A list of topics processed by this queue. Either the concrete topic is specified or the topic string ends with /* or /. If a star is at the end all topics and sub topics match, with a dot only direct sub topics match. |
 | `queue.maxparallel` | How many jobs can be processed in parallel? -1 for number of processors.|
-| `queue.retries` | How often should the job be retried. -1 for endless retries. |
+| `queue.retries` | How often the job should be retried in case of failure (i.e. Job did not finish with succeeded or cancelled result). -1 for endless retries. In case of exceptions there is no retry. |
 | `queue.retrydelay` | The waiting time in milliseconds between job retries. |
 | `queue.priority` | The thread priority: NORM, MIN, or MAX |
 | `service.ranking` | A ranking for this configuration.|