You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2016/04/11 08:39:41 UTC
svn commit: r985337 - in /websites/staging/sling/trunk/content: ./
documentation/bundles/apache-sling-eventing-and-job-handling.html
Author: buildbot
Date: Mon Apr 11 06:39:41 2016
New Revision: 985337
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 Mon Apr 11 06:39:41 2016
@@ -1 +1 @@
-1738459
+1738515
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 Mon Apr 11 06:39:41 2016
@@ -131,6 +131,7 @@ h2:hover > .headerlink, h3:hover > .head
<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>
<p>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.</p>
+<p>The Sling Jobs Processing adds some overhead, so in some cases it might be better to use just the <a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Commons Scheduler Service</a> or the <a href="/documentation/bundles/apache-sling-commons-thread-pool.html">Commons Thread Pool</a> for asynchronous execution of code.</p>
<p>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.</p>
<p>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 <em>JobManager.addJob</em> method:</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>
@@ -159,16 +160,14 @@ 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">¶</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>
+<p>Instead of creating the jobs 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>. The last method being called on the <code>JobBuilder</code> must be <code>add(...)</code>, which finally adds the job to the queue.</p>
<h3 id="scheduled-jobs">Scheduled Jobs<a class="headerlink" href="#scheduled-jobs" title="Permanent link">¶</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>
+<p>An example code for scheduling a job 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>
@@ -180,9 +179,9 @@ h2:hover > .headerlink, h3:hover > .head
<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>"<span class="n">my</span><span class="o">/</span><span class="n">special</span><span class="o">/</span><span class="n">jobtopic</span>"<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="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="n">use</span> <span class="n">scheduleBuilder</span><span class="p">.</span><span class="n">add</span><span class="p">(</span><span class="n">List</span><span class="o"><</span><span class="n">String</span><span class="o">></span><span class="p">)</span> <span class="n">instead</span> <span class="n">to</span> <span class="n">get</span> <span class="n">further</span> <span class="n">information</span> <span class="n">about</span> <span class="n">the</span> <span class="n">error</span>
<span class="p">}</span>
- <span class="p">}</span>
+ <span class="p">}</span>
<span class="p">}</span>
</pre></div>
@@ -290,7 +289,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">¶</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. 1738459 by kwin on Sun, 10 Apr 2016 18:52:15 +0000
+ Rev. 1738515 by kwin on Mon, 11 Apr 2016 06:39:26 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project