Author: buildbot
Date: Wed Jan 11 17:37:38 2012
New Revision: 802395
Log:
Staging update by buildbot for stanbol
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/STANBOL-414-specification.html
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/STANBOL-414-specification.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/STANBOL-414-specification.html
(original)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/STANBOL-414-specification.html
Wed Jan 11 17:37:38 2012
@@ -195,12 +195,77 @@ enhancement engines.</p>
</pre></div>
+<p>In addition to this I would propose to also include properties currently
only provided by engines via the ServiceProperties interface the the properties
of the service registration. By this it would be possible to access such
information also via the ServiceReference without the need to retrieve the
EnhancementEngine first.</p>
+<p>This would e.g. allow to determine the execution order of Enignes by
directly retrieving the ServiceProperties#ENHANCEMENT_ENGINE_ORDERING directly
+from the ServiceReference</p>
<h3 id="enhancementenginemanager">EnhancementEngineManager</h3>
-<p>New Utility that keeps track of all active EnhancementEngines and supports
lookup for Enhancement Engines based on the "stanbol.enhancer.engine.name"
property.</p>
-<div class="codehilite"><pre><span class="o">+</span> <span
class="n">getEngine</span><span class="p">(</span><span class="n">String</span>
<span class="n">name</span><span class="p">)</span> <span class="p">:</span>
<span class="n">EnhancementEngine</span>
-<span class="o">+</span> <span class="n">getEngines</span><span
class="p">(</span><span class="n">String</span> <span
class="n">name</span><span class="p">)</span> <span class="p">:</span> <span
class="n">List</span><span class="sr"><EnhancementEngine></span>
-<span class="o">+</span> <span class="n">isEngine</span><span
class="p">(</span><span class="n">String</span> <span
class="n">name</span><span class="p">)</span> <span class="p">:</span> <span
class="n">boolean</span>
-<span class="o">+</span> <span class="n">getActiveEngines</span><span
class="p">(</span><span class="n">Chain</span> <span
class="n">chain</span><span class="p">)</span> <span class="p">:</span> <span
class="n">Map</span><span class="sr"><String,EnhancementEngine></span>
+<p>With the addition of enhancement chains and the RESTful interfaces for
engines there will be much more components that will need to track active
Enhancement Engines by the "stanbol.enhancer.engine.name" property and sort
active engines by their service ranking. To satisfy this need one has two
possible solutions:</p>
+<ol>
+<li>EnhancementEngineManager Service: OSGI Service that keeps track of all
active engines.</li>
+<li>EngineTracker: Utility that implements EnhancementEngineManager but would
be used similar to the <a
href="http://www.osgi.org/javadoc/r4v42/org/osgi/util/tracker/ServiceTracker.html";>ServiceTracker</a>
to track a single-, a specific set or all active EnhancementEngines.</li>
+</ol>
+<p>First lets define the EnhancementEngineManager interface</p>
+<div class="codehilite"><pre><span class="sr">/** Getter for the reference to
the engine with the parsed name */</span>
+<span class="o">+</span> <span class="n">getReference</span><span
class="p">(</span><span class="n">String</span> <span
class="n">name</span><span class="p">)</span> <span class="p">:</span> <span
class="n">ServiceReference</span>
+<span class="sr">/** Getter for all references to active engines with the
parsed name */</span>
+<span class="o">+</span> <span class="n">getReferences</span><span
class="p">(</span><span class="n">String</span> <span
class="n">name</span><span class="p">)</span> <span class="p">:</span> <span
class="n">List</span><span class="sr"><ServiceReference></span>
+<span class="sr">/** Getter for the Engine for the given name */</span>
+<span class="o">+</span> <span class="n">getEngine</span><span
class="p">(</span><span class="n">String</span> <span
class="n">name</span><span class="p">)</span> <span class="p">:</span> <span
class="n">EnhancementEngine</span>
+</pre></div>
+
+
+<h4 id="enginetracker">EngineTracker</h4>
+<p>Utility that internally uses <a
href="http://www.osgi.org/javadoc/r4v42/org/osgi/util/tracker/ServiceTracker.html";>ServiceTracker</a>
to keep track of active EnhancementEngines there names and service rankings.
In addition to the implementation of the EnhancementEngineManager interface it
would define the following Methods to construct and start/stop the tracker.</p>
+<div class="codehilite"><pre><span class="sr">/** Constructs a tracker for the
parsed names. All if no names are parsed */</span>
+<span class="o">+</span> <span class="n">EnginesTracker</span><span
class="p">(</span><span class="n">BundleContext</span> <span
class="n">context</span><span class="p">,</span><span
class="n">String</span><span class="o">...</span><span
class="n">names</span><span class="p">)</span>
+<span class="sr">/** Constructs a tracker for the parsed names. all if names
is NULL or empty */</span>
+<span class="o">+</span> <span class="n">EnginesTracker</span><span
class="p">(</span><span class="n">BundleContext</span> <span
class="n">context</span><span class="p">,</span><span class="n">Set</span><span
class="sr"><String></span> <span class="n">names</span><span
class="p">,</span> <span class="n">ServiceTrackerCustomizer</span> <span
class="n">customizer</span><span class="p">)</span>
+<span class="sr">/** Starts the tracking */</span>
+<span class="o">+</span> <span class="nb">open</span><span class="p">()</span>
+<span class="sr">/** Stops tracking and closes the tracker */</span>
+<span class="o">+</span> <span class="nb">close</span><span class="p">()</span>
+<span class="sr">/** Getter for the list of tracked engine names. Empty if all
are tracked */</span>
+<span class="o">+</span> <span class="n">getTrackedEngines</span><span
class="p">()</span> <span class="p">:</span> <span class="n">Set</span><span
class="sr"><String></span>
+</pre></div>
+
+
+<p>This utility can be used by Components that need to track a specific set of
Engines. In addition it also allows users to provide an own
ServiceTrackerCustomizer. This can be e.g. used to perform special actions on
any change to an tracked Engine.</p>
+<p>A typically usage if this would be by the <em>WeightedChain</em>
implementation that needs to track changes in referenced EnhancementEgninges to
update the execution plan it needs to manage based on the
ServiceProperties#ENHANCEMENT_ENGINE_ORDERING values.</p>
+<h4 id="enhancementenginemanager_service">EnhancementEngineManager Service</h4>
+<p>A Component registered for the EnhancementEngineManager service.
Implementation could use an EngineTracker that tracks all EnhancementEngines.
This service will be typically used by using</p>
+<div class="codehilite"><pre><span class="nv">@Reference</span>
+<span class="n">EnhancementEngineManager</span> <span
class="n">engineManager</span><span class="p">;</span>
+</pre></div>
+
+
+<p>A typical use would be to retrieve the engines needed to asynchronously
execute a chain</p>
+<div class="codehilite"><pre><span class="sr">//</span><span
class="n">during</span> <span class="n">initialization</span> <span
class="n">of</span> <span class="n">the</span> <span class="n">execution</span>
+<span class="n">Set</span><span class="sr"><String></span> <span
class="n">engineNames</span> <span class="o">=</span> <span
class="n">chain</span><span class="o">.</span><span
class="n">getEngines</span><span class="p">();</span>
+<span class="sr">//</span><span class="n">actually</span> <span
class="n">this</span> <span class="n">should</span> <span class="ow">not</span>
<span class="n">check</span> <span class="n">engines</span> <span
class="n">referenced</span> <span class="n">by</span>
+<span class="sr">//o</span><span class="n">ptional</span> <span
class="n">ExecutionNodes</span>
+<span class="k">for</span><span class="p">(</span><span
class="n">String</span> <span class="n">engineName</span> <span
class="p">:</span> <span class="n">chain</span><span class="o">.</span><span
class="n">getEngines</span><span class="p">()){</span>
+ <span class="k">if</span><span class="p">(</span><span
class="n">engineManager</span><span class="o">.</span><span
class="n">getReference</span><span class="p">(</span><span
class="n">engineName</span><span class="p">)</span> <span class="o">==</span>
<span class="n">null</span><span class="p">){</span>
+ <span class="sr">//</span><span class="n">throw</span> <span
class="n">exception</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="sr">//</span><span class="n">this</span> <span
class="n">is</span> <span class="n">called</span> <span class="n">after</span>
<span class="n">an</span> <span class="n">engine</span> <span
class="n">completes</span> <span class="n">execution</span>
+<span class="sr">//</span><span class="ow">and</span> <span
class="n">assumes</span> <span class="n">the</span> <span
class="n">following</span> <span class="n">execution</span> <span
class="n">states:</span>
+<span class="n">Collection</span><span class="sr"><NonLiteral></span>
<span class="n">executed</span><span class="p">;</span> <span
class="sr">//</span><span class="n">already</span> <span
class="n">executed</span> <span class="n">Engines</span>
+<span class="n">Collection</span><span class="sr"><NonLiteral></span>
<span class="n">running</span><span class="p">;</span> <span
class="sr">//c</span><span class="n">urrently</span> <span
class="n">running</span> <span class="n">Engines</span>
+
+<span class="n">Collection</span><span class="sr"><NonLiteral></span>
<span class="k">next</span> <span class="o">=</span> <span
class="n">ExecutionPlanUtils</span><span class="o">.</span><span
class="n">getExecuteable</span><span class="p">(</span><span
class="n">plan</span><span class="p">,</span> <span
class="n">executed</span><span class="p">);</span>
+<span class="k">for</span><span class="p">(</span><span
class="n">NonLiteral</span> <span class="n">node</span> <span
class="p">:</span> <span class="k">next</span><span class="p">){</span>
+ <span class="k">if</span><span class="p">(</span><span
class="o">!</span><span class="n">running</span><span class="o">.</span><span
class="n">contains</span><span class="p">(</span><span
class="n">node</span><span class="p">)){</span>
+ <span class="n">String</span> <span class="n">engineName</span> <span
class="o">=</span> <span class="n">EnhancementEngineHelper</span><span
class="o">.</span><span class="n">getString</span><span class="p">(</span><span
class="n">executionPlan</span><span class="p">,</span><span
class="n">node</span><span class="p">,</span> <span
class="n">EX_ENGINE</span><span class="p">));</span>
+ <span class="n">EnhancementEngine</span> <span class="n">engine</span>
<span class="o">=</span> <span class="n">tracker</span><span
class="o">.</span><span class="n">getEngine</span><span class="p">(</span><span
class="n">engineName</span><span class="p">);</span>
+ <span class="k">if</span><span class="p">(</span><span
class="n">engine</span> <span class="o">!=</span> <span
class="n">null</span><span class="p">){</span>
+ <span class="sr">//</span> <span class="n">asynchronously</span>
<span class="n">call</span> <span class="n">this</span> <span
class="n">engine</span>
+ <span class="p">}</span> <span class="k">else</span> <span
class="p">{</span>
+ <span class="sr">//c</span><span class="n">heck</span> <span
class="k">if</span> <span class="n">optional</span> <span class="ow">and</span>
<span class="n">throw</span> <span class="n">error</span> <span
class="k">if</span> <span class="ow">not</span>
+ <span class="p">}</span>
+ <span class="p">}</span> <span class="sr">//</span> <span
class="k">else</span> <span class="n">already</span> <span
class="n">running</span> <span class="o">-></span> <span
class="n">ignore</span>
+<span class="p">}</span>
</pre></div>
