svn commit: r985289 - in /websites/staging/sling/trunk/content: ./ documentation/bundles/apache-sling-eventing-and-job-handling.html

[bu...@apache.org]

Author: buildbot
Date: Sun Apr 10 18:52:29 2016
New Revision: 985289

Log:
Staging update by buildbot for sling

Modified:
    websites/staging/sling/trunk/content/   (props changed)
    websites/staging/sling/trunk/content/documentation/bundles/apache-sling-eventing-and-job-handling.html

Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sun Apr 10 18:52:29 2016
@@ -1 +1 @@
-1738424
+1738459

Modified: websites/staging/sling/trunk/content/documentation/bundles/apache-sling-eventing-and-job-handling.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/apache-sling-eventing-and-job-handling.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles/apache-sling-eventing-and-job-handling.html Sun Apr 10 18:52:29 2016
@@ -122,9 +122,11 @@ h2:hover > .headerlink, h3:hover > .head
 <li><a href="#distributed-events">Distributed Events</a></li>
 <li><a href="#sending-scheduled-events">Scheduled Events</a></li>
 </ul>
-<p>To get some hands on code, you can refer to the following tutorials:
-<em> <a href="/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html">How to Manage Events in Sling</a>
-</em> <a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Scheduler Service (commons scheduler)</a></p>
+<p>To get some hands on code, you can refer to the following tutorials:</p>
+<ul>
+<li><a href="/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html">How to Manage Events in Sling</a></li>
+<li><a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Scheduler Service (commons scheduler)</a></li>
+</ul>
 <h2 id="jobs-guarantee-of-processing">Jobs (Guarantee of Processing)<a class="headerlink" href="#jobs-guarantee-of-processing" title="Permanent link">&para;</a></h2>
 <p>In general, the eventing mechanism (OSGi EventAdmin) has no knowledge about the contents of an event. Therefore, it can't decide if an event is important and should be processed by someone. As the event mechanism is a "fire event and forget about it" algorithm, there is no way for an event admin to tell if someone has really processed the event. Processing of an event could fail, the server or bundle could be stopped etc.</p>
 <p>On the other hand, there are use cases where the guarantee of processing is a must and usually this comes with the requirement of processing exactly once. Typical examples are sending notification emails (or sms), post processing of content (like thumbnail generation of images or documents), workflow steps etc.</p>
@@ -156,6 +158,36 @@ h2:hover > .headerlink, h3:hover > .head
 
 <p>The job topic follows the conventions for the topic of an OSGi event. All objects in the payload must be serializable and publically available (exported by a bundle). This is required as the job is persisted and unmarshalled before processing.</p>
 <p>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.</p>
+<h3 id="jobbuilder">JobBuilder<a class="headerlink" href="#jobbuilder" title="Permanent link">&para;</a></h3>
+<p>Instead of creating the jobs manually by calling <code>JobManager.addJob("my/special/jobtopic", props);</code> the <code>JobBuilder</code> can be used, which is retrieved via <code>JobManager.createJob("my/special/jobtopic")</code>.</p>
+<h3 id="scheduled-jobs">Scheduled Jobs<a class="headerlink" href="#scheduled-jobs" title="Permanent link">&para;</a></h3>
+<p>Scheduled Jobs are put in the queue at a specific time (optionally periodically). For that the <code>ScheduleBuilder</code> must be used which is retrieved via <code>JobBuilder.schedule()</code>.</p>
+<p>An example code for scheduling a jobs looks like this:</p>
+<div class="codehilite"><pre><span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">sling</span><span class="p">.</span><span class="n">jobs</span><span class="p">.</span><span class="n">JobManager</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">sling</span><span class="p">.</span><span class="n">event</span><span class="p">.</span><span class="n">jobs</span><span class="p">.</span><span class="n">JobBuilder</span><span class="p">.</span><span class="n">ScheduleBuilder</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">scr</span><span class="p">.</span><span class="n">annotations</span><span class="p">.</span><span class="n">Component</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">scr</span><span class="p">.</span><span class="n">annotations</span><span class="p">.</span><span class="n">Reference</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">java</span><span class="p">.</span><span class="n">util</span><span class="p">.</span><span class="n">Map</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">java</span><span class="p">.</span><span class="n">util</span><span class="p">.</span><span class="n">HashMap</span><span class="p">;</span>
+
+<span class="p">@</span><span class="n">Component</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">MyComponent</span> <span class="p">{</span>
+
+    <span class="p">@</span><span class="n">Reference</span>
+    <span class="n">private</span> <span class="n">JobManager</span> <span class="n">jobManager</span><span class="p">;</span>
+
+    <span class="n">public</span> <span class="n">void</span> <span class="n">startScheduledJob</span><span class="p">()</span> <span class="p">{</span>
+        <span class="n">ScheduleBuilder</span> <span class="n">scheduleBuilder</span> <span class="p">=</span> <span class="n">jobManager</span><span class="p">.</span><span class="n">startJob</span><span class="p">(</span>&quot;<span class="n">my</span><span class="o">/</span><span class="n">special</span><span class="o">/</span><span class="n">jobtopic</span>&quot;<span class="p">).</span><span class="n">schedule</span><span class="p">();</span>
+        <span class="n">scheduleBuilder</span><span class="p">.</span><span class="n">daily</span><span class="p">(</span>0<span class="p">,</span>0<span class="p">);</span> <span class="o">//</span> <span class="n">execute</span> <span class="n">daily</span> <span class="n">at</span> <span class="n">midnight</span>
+        <span class="k">if</span> <span class="p">(</span><span class="n">scheduleBuilder</span><span class="p">.</span><span class="n">add</span><span class="p">()</span> <span class="o">==</span> <span class="n">null</span><span class="p">)</span> <span class="p">{</span>
+            <span class="o">//</span> <span class="n">something</span> <span class="n">went</span> <span class="n">wrong</span> <span class="n">here</span>
+        <span class="p">}</span>
+    <span class="p">}</span>        
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Internally the scheduled Jobs use the <a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Commons Scheduler Service</a>. But in addition they are persisted (by default below <code>/var/eventing/scheduled-jobs</code>) and survive therefore even server restarts. When the scheduled time is reached, the job is automatically added as regular Sling Job through the <code>JobManager</code>.</p>
 <h3 id="job-consumers">Job Consumers<a class="headerlink" href="#job-consumers" title="Permanent link">&para;</a></h3>
 <p>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:</p>
 <div class="codehilite"><pre>    <span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">scr</span><span class="p">.</span><span class="n">annotations</span><span class="p">.</span><span class="n">Component</span><span class="p">;</span>
@@ -179,7 +211,7 @@ h2:hover > .headerlink, h3:hover > .head
 <p>The <em>Job</em> interface allows to query the topic, the payload and additional information about the current job. The consumer can either return <em>JobResult.OK</em> indicating that the job has been processed, <em>JobResult.FAILED</em> indicating the processing failed, but can be retried or <em>JobResult.CANCEL</em> the processing has failed permanently.</p>
 <h3 id="job-handling">Job Handling<a class="headerlink" href="#job-handling" title="Permanent link">&para;</a></h3>
 <p>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.).</p>
-<p>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.</p>
+<p>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 <code>Apache Sling Job Default Queue</code> (which can be configured through OSGi as well).</p>
 <h4 id="queue-configurations">Queue Configurations<a class="headerlink" href="#queue-configurations" title="Permanent link">&para;</a></h4>
 <p>A queue configuration can have the following properties:</p>
 <table class="table">
@@ -208,7 +240,7 @@ h2:hover > .headerlink, h3:hover > .head
 </tr>
 <tr>
 <td><code>queue.retries</code></td>
-<td>How often should the job be retried. -1 for endless retries.</td>
+<td>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.</td>
 </tr>
 <tr>
 <td><code>queue.retrydelay</code></td>
@@ -258,7 +290,7 @@ h2:hover > .headerlink, h3:hover > .head
 <h2 id="sending-scheduled-events">Sending Scheduled Events<a class="headerlink" href="#sending-scheduled-events" title="Permanent link">&para;</a></h2>
 <p>Scheduled events are OSGi events that have been created by the environemnt. They are generated on each application node of the cluster through an own scheduler instance. Sending these events works the same as sending events based on JCR events (see above).</p>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1683618 by sseifert on Thu, 4 Jun 2015 19:50:02 +0000
+        Rev. 1738459 by kwin on Sun, 10 Apr 2016 18:52:15 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project