Author: buildbot
Date: Tue Jan 31 09:03:55 2012
New Revision: 803630
Log:
Staging update by buildbot for stanbol
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.html
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.html
(original)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.html
Tue Jan 31 09:03:55 2012
@@ -70,16 +70,16 @@
<p>Note that the parsed ContentItem will be changed during the enhancement
process. <a href="engines/enhancementengine.html">EnhancementEngine</a>s will
add extracted knowledge to the metadata of the content item. Also additional
content parts may be added to the content item.</p>
<h2 id="enhancement_process">Enhancement Process</h2>
<p>While the <a href="chains/executionplan.html">ExecutionPlan</a> defines
what EnhancementEgnies are used and how they depend on each the
EnhancementJobManager is responsible for the actual execution of the
enhancement process based on this plan. This section provides detailed
information about requirements and expectations that MUST BE considered.</p>
-<p>The EnhancementJobManager is also responsible to create and update the <a
href="executionmetadata.html">ExecutionMetadata</a> in the metadata of the
processed <a href="contentitem.html">ContentItem</a>.</p>
-<h3 id="retrieving_the_executionplan">Retrieving the ExecutionPlan</h3>
-<p>The <a href="chains/executionplan.html">ExecutionPlan</a> is provided by
the Chain in a final graph that is guaranteed to be not changed. However
because the configuration of a Chain might be change at any time the
EnhancementJobManager MUST retrieve the execution plan only once and used it
during the whole enhancement process.</p>
-<p>Before the start of the enhancement process the EnhancementJobManager needs
first to initialize the <a href="executionmetadata.html">ExecutionMetadata</a>
for the <a href="contentitem.html">ContentItem</a>. This includes</p>
+<p>The EnhancementJobManager is also responsible to create and update the <a
href="executionmetadata.html">ExecutionMetadata</a> in the metadata of the
processed <a href="contentitem.html">ContentItem</a>. Details about this are
provided in the section "<a
href="executionmetadata.html#creationmanagement_of_executionmetadata">Creation/Management
of ExecutionMetadata</a>" of the ExecutionMetadata documentation.</p>
+<h3 id="initializing_the_enhancement_process">Initializing the Enhancement
Process</h3>
+<p>Here one needs to distinguish two costs:</p>
<ol>
-<li>copying the execution plan as returned by the Chain to the metadata of the
content item</li>
-<li>create an 'em:ChainExecutin' instance and set the 'em:enhances' property
to the URI of the ContentItem</li>
-<li>creating 'em:EngineExecution' instances for all 'ep:ExecutionNodes' and
set the 'em:status' of those to 'em:StatusSheduled'. Also define such instances
as 'em:executionPart' to the chain execution and link them to the according
execution node of the execution plan.</li>
+<li>Initialisation of an new Enhancement process and</li>
+<li>Continuation of an existing Enhancement process.</li>
</ol>
-<p>See the documentation of the <a
href="executionmetadata.html">ExecutionMetadata</a> for more information.</p>
+<p>The two cases can be easily detected by the EnhancementJobManager by
evaluating if a content part with the URI
"http://stanbol.apache.org/ontology/enhancer/executionMetadata#ChainExecution";
is present within the parsed <a href="contentitem.html">ContentItem</a>.</p>
+<p>In the first case the <a href="chains/executionplan.html">ExecutionPlan</a>
to be used by for the enhancement process is provided by the Chain in a final
graph that is guaranteed to be not changed. However because the configuration
of a Chain might be change at any time the EnhancementJobManager MUST retrieve
the execution plan only once and used it during the whole enhancement process.
In addition the ExecutionPlan MUST BE also added to the graph containing the <a
href="executionmetadata.html">EnahcementMetadata</a>. In case of continuing on
an previously aborted enhancement process the ExecutionPlan MUST BE initialized
from the ExecutionMetadata provided by the ContentItem.</p>
+<p>For details on how to initialize/load the execution metadata see the
section "<a
href="executionmetadata.html#creationmanagement_of_executionmetadata">Creation/Management
of ExecutionMetadata</a>" of the ExecutionMetadata documentation.</p>
<h3 id="engine_execution">Engine Execution</h3>
<p>The ExecutionPlan provides the necessary information what <a
href="engines/enhancementengine.html">EnhancementEngine</a>s can be executed at
any given state. The following code shows how to determine executable engines.
This code snippet assumes to be called after the execution of an
EnhancementEngine has completed. Note that in a multi threaded environment
access to the list of executed and running engines need to be synchronized.</p>
@@ -101,14 +101,16 @@ This code snippet assumes to be called a
</pre></div>
+<p><em>NOTE</em> that the NonLiterals contained in the two collections are
'ep:ExecutionNode' instances and NOT 'em:EngineExecution' instances. Each
'em:EngineExecution' instance in the the ExecutionMetadata' is linked by the
'em:executionNode' property to the corresponding 'ep:ExecutionNode' of the
ExecutionPlan.</p>
<p>Before executing an <a
href="engines/enhancementengine.html">EnhancementEngine</a> the
EnhancementJobManager needs to check if and how the engine can enhance a
content item. This is indicated by the integer returned by the
"canEnhance(ContentItem ci)" method:</p>
<ul>
-<li><strong>CANNOT_ENHANCE</strong>: Indicates that this engines can not
process the parsed content item. In this case the EnhancementJobManager needs
to skip this engine and mark the EngineExectuion as skipt with a status message
that the EnhancementEngine was unable to process the content item. If this
engine is marked as optional the enhancement process can continue if not, than
the execution MUST be marked as failed and an according Exception needs to be
thrown.</li>
+<li><strong>CANNOT_ENHANCE</strong>: Indicates that this engines can not
process the parsed content item. In this case the EnhancementJobManager needs
to skip this engine and mark the EngineExectuion as skipped with a status
message that the EnhancementEngine was unable to process the content item. If
this engine is marked as optional the enhancement process can continue if not,
than the execution MUST be marked as failed and an according Exception needs to
be thrown.</li>
<li><strong>ENHANCE_SYNCHRONOUS</strong>: Indicates that the engines needs
exclusive access to the parsed content item. The EnhancementJobManager needs to
ensure that in some way. Typically by calling the
"computeEnhancement(ContentItem ci)" method within an write lock.</li>
<li><strong>ENHANCE_ASYNC</strong>: Indicates that this engine supports
asynchronous execution and takes itself care to acquire read and write locks on
the parsed content item. However this does not require the JobManager to
execute the engine asynchronously.</li>
</ul>
-<p>If the execution of an EnhancementEngine completes the JobManager needs to
set the state of the execution to completed and update the other metadata
accordingly.</p>
+<p>If the execution of an EnhancementEngine completes the JobManager needs to
set the state of the execution to completed and update the execution metadata
accordingly.</p>
<p>If a call to "computeEnhancement(ContentItem ci)" results in an Exception
the EnhancementJobManager must mark the execution of the engine as failed with
a decryption of the occurred exception. If the the execution of the affected
engine was optional the enhancement process is continued. Otherwise the
enhancement process needs to be stopped and the Error needs to rethrown by the
"enhanceContent(..)" method.</p>
+<p>For all the details on how to reflect state changes in the Execution
metadata see <a href="executionmetadata.html#execution_state_management">this
section</a> of the documentation of the ExecutionMetadata.</p>
<h3 id="multi_threaded_enhancement_processes">Multi Threaded enhancement
processes</h3>
<p>In case the EnhancementJobManager supports to simultaneously call <a
href="engines/enhancementengine.html">EnhancementEngine</a>s for the same
content item in multiple threads it is important to correctly use the
ReadWriteLock as provided by the ContentItem.getLock() method.</p>
<p>There are manny good examples on how to correctly use
"java.util.concurrent.ReadWriteLock" available on the web.</p>
