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

[kw...@apache.org]

Author: kwin
Date: Mon Apr 11 06:39:26 2016
New Revision: 1738515

URL: http://svn.apache.org/viewvc?rev=1738515&view=rev
Log:
some more fixes and cleanups

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=1738515&r1=1738514&r2=1738515&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 Mon Apr 11 06:39:26 2016
@@ -24,6 +24,8 @@ On the other hand, there are use cases w
 
 The Sling Event Support adds the notion of a job. A job is a special event that has to be processed exactly once. To be precise, the processing guarantee is at most once. However, the time window for a single job where exactly once is very small and only happens if the instance which processes a job crashes after the job processing is finished but before this state is persisted. Therefore a job consumer should be prepared to process a job more than once.
 
+The Sling Jobs Processing adds some overhead, so in some cases it might be better to use just the [Commons Scheduler Service]({{ refs.scheduler-service-commons-scheduler.path }}) or the [Commons Thread Pool]({{ refs.apache-sling-commons-thread-pool.path }}) for asynchronous execution of code.
+
 While older versions of the job handling were based on sending and receiving events through the OSGi event admin, newer versions provide enhanced support through special Java interface. This approach is preferred over the still supported but deprecated event admin way.
 
 A job consists of two parts, the job topic describing the nature of the job and the payload which is a key value map of serializable objects. A client can initiate a job by calling the *JobManager.addJob* method:
@@ -55,21 +57,19 @@ As soon as the method returns from the j
 
 ### 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")`.
+Instead of creating the jobs by calling `JobManager.addJob("my/special/jobtopic", props);` the `JobBuilder` can be used, which is retrieved via `JobManager.createJob("my/special/jobtopic")`. The last method being called on the `JobBuilder` must be `add(...)`, which finally adds the job to the queue.
 
 
 ### 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:
+An example code for scheduling a job 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 {
@@ -81,9 +81,9 @@ An example code for scheduling a jobs lo
             ScheduleBuilder scheduleBuilder = jobManager.startJob("my/special/jobtopic").schedule();
             scheduleBuilder.daily(0,0); // execute daily at midnight
             if (scheduleBuilder.add() == null) {
-            	// something went wrong here
+                // something went wrong here, use scheduleBuilder.add(List<String>) instead to get further information about the error
             }
-        }        
+        }
     }