Author: buildbot
Date: Thu Jan 26 15:30:25 2012
New Revision: 803341
Log:
Staging update by buildbot for stanbol
Added:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.html
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.html
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.html
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.html
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.html
(original)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.html
Thu Jan 26 15:30:25 2012
@@ -57,7 +57,7 @@
<div id="content">
<h1 class="title">Enhancement Chains</h1>
- <p>An Enhancement Chain defines how Content parsed to the Stanbol Enhancer
is processed. More concrete it defines what engines and in what order are used
to process ContentItems. Chains are not responsible for the actual processing
of ContentItems. They provide the <a
href="executionplan.html">ExecutionPlan</a> to the EnhancementJobManger that
does the actual processing of the ContentItem.</p>
+ <p>An Enhancement Chain defines how Content parsed to the Stanbol Enhancer
is processed. More concrete it defines what engines and in what order are used
to process ContentItems. Chains are not responsible for the actual processing
of ContentItems. They provide the <a
href="executionplan.html">ExecutionPlan</a> to the <a
href="../enhancementjobmanager.html">EnhancementJobManger</a> that does the
actual processing of the ContentItem.</p>
<p>In the RESTful API enhancement chains can be accessed by there name
under</p>
<div class="codehilite"><pre><span class="n">http:</span><span
class="sr">//</span><span class="p">{</span><span class="n">host</span><span
class="p">}:{</span><span class="n">port</span><span class="p">}</span><span
class="sr">/{stanbol-path}/</span><span class="n">enhancer</span><span
class="sr">/chain/</span><span class="p">{</span><span
class="n">chain</span><span class="o">-</span><span class="n">name</span><span
class="p">}</span>
</pre></div>
@@ -92,8 +92,7 @@
</pre></div>
-<p>To enhance a ContentItem with the default chain the
"enhanceContent(ContentItem ci)" can be used.
-<</p>
+<p>To enhance a ContentItem with the default chain the
"enhanceContent(ContentItem ci)" can be used.</p>
<h2 id="chain_interface">Chain Interface</h2>
<p>The Chain interface is very simplistic. It only defines three methods.</p>
<div class="codehilite"><pre><span class="sr">/** Getter for the name of the
Chain */</span>
@@ -115,7 +114,7 @@
<p>For Chain implementation it is important that the returned Graph holding
the execution plan MUST BE read-only AND final. Meaning that a change in the
configuration of a Chain MUST NOT change the graph returned by calls to the
getExecutionPlan method.</p>
<p>Because the configuration of a Chain might change at any time
EnhancementJobManager implementation MUST retrieve the execution plan once and
than use this instance for the whole enhancement process. Because of the above
requirement that the execution plan is stored in an read-only and final Graph
this ensures that the plan can not change even for long lasting enhancement
processes. Therefore any change to the configuration of a chain will not
influence ongoing enhancement processes.</p>
<h2 id="enhancement_chain_management">Enhancement Chain Management</h2>
-<p>This section describes how Enhancement Cahins are managed by the Stanbol
Enhancer and how they can be selected/accessed. It also describes how the
"default" Chain is determined.</p>
+<p>This section describes how Enhancement Chains are managed by the Stanbol
Enhancer and how they can be selected/accessed. It also describes how the
"default" Chain is determined.</p>
<p>For every Stanbol Enhancer a single Chain MUST BE present. If this is not
the case enhance request MUST throw a ChainException with an according error
message. However typically multiple EnhancementChains will be configured. </p>
<h3 id="chain_name_conflicts">Chain Name Conflicts</h3>
<p>Chains are identified by the value of the "stanbol.enhancer.chain.name"
property - the name of the chain. If more than one Chain do use the same name,
than the normal OSGI procedure to select the default service is used. This
means that</p>
@@ -130,12 +129,12 @@
<ol>
<li>the Chain with the name "default". If more than one Chain is present with
that name, than the above rules for resolving name conflicts apply. If none</li>
<li>the Chain with the highest "service.ranking". If several have the same
ranking</li>
-<li>the Cahin with the lowest "service.id"</li>
+<li>the Chain with the lowest "service.id"</li>
</ol>
<p>If no chain is active a ChainException with an according message MUST BE
thrown.</p>
<p>All Stanbol launchers are configured with the <a
href="defaultchain.html">Default Chain</a> enabled. This registers itself with
the name "default" and the lowest possible service ranking - Integer.MIN_VALUE.
This default provides a Chain that considered all currently active
EnhancementEngines and sorts them based on there ordering information (see the
<a href="weightedchain.html#calculation_of_the_executionplan">Calculation of
the Execution Plan based on the EnhancementEngine Ordering</a> for details).</p>
-<h3 id="chainmanager_interfacechainmanagerhtml"><a
href="chainmanager.html">ChainManager interface</a></h3>
-<p>This is the management interface for EnhancementChains that can be used by
components to lookup chains based on there name. It also provides a getter for
the default chain. There is also OSGI ServiceTracker like implementation that
can be used to track only chains with specific names and to get even notified
on any change of such chains.</p>
+<h3 id="chainmanager_interface">ChainManager interface</h3>
+<p>The <a href="chainmanager.html">ChainManager</a> is the management
interface for EnhancementChains that can be used by components to lookup chains
based on there name. It also provides a getter for the default chain. There is
also OSGI ServiceTracker like implementation that can be used to track only
chains with specific names and to get even notified on any change of such
chains.</p>
<h2 id="chain_implementations">Chain implementations</h2>
<p>The following Chain implementations are included within the default Stanbol
Enhancer distribution:</p>
<ul>
@@ -143,7 +142,7 @@
<li><strong><a href="listchain.html">ListChain</a></strong>: Implementation
that creates the ExecutionPlan by chaining the EnhancementEngines in the exact
order as specified by the parsed list. This Chain does not support parallel
execution of engines.</li>
<li><strong><a href="weightedchain.html">WeightedChain</a></strong>: This
Chain implementation takes a List of Engines names as input and uses the
"org.apache.stanbol.enhancer.engine.order " metadata provided by such engines
to calculate the ExecutionGraph.</li>
<li><strong><a href="graphchain.html">GraphChain</a></strong>: This Chain
implementation is based on a ExecutionGraph parsed os configuration.</li>
-<li><strong>SingleEngineChain</strong>: An Adapter that allows to execute a
single EnhancementEngine within a Chain. This types of Chains will not be
registered as OSGI service. Instances will be created on request for single
EnhancementEngines and directly parsed to the EnhancementJobManager
implementation. </li>
+<li><strong>SingleEngineChain</strong>: An Adapter that allows to execute a
single EnhancementEngine within a Chain. This types of Chains will not be
registered as OSGI service. Instances will be created on request for single
EnhancementEngines and directly parsed to the <a
href="../enhancementjobmanager.html">EnhancementJobManager</a> implementation.
</li>
</ul>
</div>
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.html
(original)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.html
Thu Jan 26 15:30:25 2012
@@ -57,7 +57,7 @@
<div id="content">
<h1 class="title">ExecutionPlan</h1>
- <p>The ExecutionPlan is represented as an RDF graph following the
ExecutionPlan Ontology. It needs to be provided by the <a
href="enhancementchain.html">Enhancement Chain</a> and is used by the
EnhancementJobManager to enhance ContentItems.</p>
+ <p>The ExecutionPlan is represented as an RDF graph following the
ExecutionPlan Ontology. It needs to be provided by the <a
href="enhancementchain.html">Enhancement Chain</a> and is used by the <a
href="../enhancementjobmanager.html">EnhancementJobManager</a> to enhance
ContentItems and to write the <a
href="../executionmetadata.html">ExecutionMetadata</a>.</p>
<h2 id="executionplan_ontology">ExecutionPlan Ontology</h2>
<p>The RDFS schema used for the execution plan is defined as follows.</p>
<ul>
Added:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.html
(added)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.html
Thu Jan 26 15:30:25 2012
@@ -0,0 +1,139 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+ <title>Apache Stanbol - EnhancementJobManager</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png"
href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220"
height="101" border="0"
src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a>
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Tutorial</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a></li>
+<li><a href="/stanbol/docs/trunk/building.html">Building</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL";>Issue
Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="http://dev.iks-project.eu/downloads/stanbol-launchers/";>Pre-built
Launchers</a></li>
+</ul>
+<h1 id="the_asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org";>Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html";>Become a
Sponsor</a></li>
+<li><a href="http://www.apache.org/security/";>Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">EnhancementJobManager</h1>
+ <p>The EnhancementJobManager is component responsible for the execution of
the <a href="../chains/executionplan.html">ExecutionPlan</a> as provided by the
<a href="../chains/enhancementchain.html">Enhancement Chain</a> on the
ContentItem.</p>
+<h2 id="enhancementjobmanager_interface">EnhancementJobManager interface</h2>
+<p>The interface of the EnhancementJobManager is very simple:</p>
+<div class="codehilite"><pre><span class="sr">/** Enhances the content item by
using the default Chain */</span>
+<span class="o">+</span> <span class="n">enhanceContent</span><span
class="p">(</span><span class="n">ContentItem</span> <span
class="n">ci</span><span class="p">)</span>
+<span class="sr">/** Enhances the content item by using the parsed Chain
*/</span>
+<span class="o">+</span> <span class="n">enhanceContent</span><span
class="p">(</span><span class="n">ContentItem</span> <span
class="n">ci</span><span class="p">,</span> <span class="n">Chain</span> <span
class="n">chain</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Note that the parsed ContentItem will be changed during the enhancement
process. EnhancementEngines 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 ContentItem.</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 ContentItem. This includes</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>
+</ol>
+<p>See the documentation of the <a
href="executionmetadata.html">ExecutionMetadata</a> for more information.</p>
+<h3 id="engine_execution">Engine Execution</h3>
+<p>The ExecutionPlan provides the necessary information what engines 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>
+<div class="codehilite"><pre><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">execute</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>
+
+
+<p>Before executing an EnhancementEngine 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>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 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>
+<h3 id="multi_threaded_enhancement_processes">Multi Threaded enhancement
processes</h3>
+<p>In case the EnhancementJobManager supports to simultaneously call
EnhancementEngines 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>
+<h3 id="finalizing_the_enhancementprocess">Finalizing the
EnhancementProcess</h3>
+<p>After the execution is completed (successfully or failed) the
EnhancementJobManager need to ensure that the 'em:status' and the
'em:completed' of the 'em:ChainExecution' instance are set. If the execution
failed also the 'em:statusMessage' should be available and contain a message
that describes the problem.</p>
+<h2 id="enhancementjobmanager_implementations">EnhancementJobManager
implementations</h2>
+<p>EnhancementJobManager implementations need to register itself as OSGI
services. By default the Stanbol Enhancer will use the implementation with the
highest service ranking. The service ranking can be set by providing a
configuration defining an integer value for the property "service.ranking"</p>
+<h3 id="eventjabmanager">EventJabManager</h3>
+<p>This implementation is provided by the
"org.apache.stanbol.enhancer.jobmanager.event" module and is currently used as
default. It registers itself (by default) with a service ranking of '0'.</p>
+<p>This implementation supports an asynchronous enhancement process by using
the <a
href="http://www.osgi.org/javadoc/r4v42/org/osgi/service/event/package-summary.html";>"org.osgi.serivce.event"</a>
framework. </p>
+<h3 id="weightedjobmanager">WeightedJobManager</h3>
+<p>This JobManager was used as default before the introduction of
EnhancementChains. It does not support EnhancementChains and will enhance
parsed ContentItems by calling all currently active EnhancementEngines in a
sequential manner. It does also not have support for EnhancementMetadata.</p>
+<p>This implementation is provided by the
"org.apache.stanbol.enhancer.jobmanager.weightedjobmanager" module and is no
longer included within the Apache Stanbol launchers. This JobManager registers
itself with a service ranking of "-1000". Users that want to use this job
manager need to manually install this bundle and either deactivate other
EnhancementJobManager implementation or reconfigure the service ranking of this
one to an value > 0.</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0";>Apache
License, Version 2.0</a>.
+ <br />
+ Apache, Stanbol and the Apache feather and Stanbol logos are
trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.html
(added)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.html
Thu Jan 26 15:30:25 2012
@@ -0,0 +1,197 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+ <title>Apache Stanbol - Execution Metadata</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png"
href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220"
height="101" border="0"
src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a>
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Tutorial</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a></li>
+<li><a href="/stanbol/docs/trunk/building.html">Building</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL";>Issue
Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="http://dev.iks-project.eu/downloads/stanbol-launchers/";>Pre-built
Launchers</a></li>
+</ul>
+<h1 id="the_asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org";>Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html";>Become a
Sponsor</a></li>
+<li><a href="http://www.apache.org/security/";>Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Execution Metadata</h1>
+ <p>The execution metadata are added by the <a
href="enhancementjobmanager.html">EnhancementJobManager</a> to the metadata of
the ContentItem. This metadata provide information about the execution of the
<a href="chains/executionplan.html">ExecutionPlan</a> provided by the <a
href="chains/enhancementchain.html">Chain</a> and can be used by clients to get
detailed information about the enhancement process of a content item.</p>
+<p>In the case of asynchronous calls to the enhancers RESTful interface
(requests that immediately return and do not wait for the enhancement process
to complete) this information might also be useful to provide information about
the current state of the enhancement process.</p>
+<h3 id="exection_metadata_ontology">Exection Metadata Ontology</h3>
+<p>The RDFS schema used for the execution plan is defined as follows.</p>
+<ul>
+<li>Namespace: em :
http://stanbol.apache.org/ontology/enhancer/executionMetadata#</li>
+<li><strong>em:Execution</strong> : Super class for all Executions<ul>
+<li><strong>em:executionPart</strong> (domain:Execution, range:
em:ChainExecution): Defines that this execution was part of the execution of a
chain</li>
+<li><strong>em:status</strong>(domain: em:Execution; range:
em:ExecutionStatus): The status of an Execution (used for both
em:EngineExection and em:ChainExecution</li>
+<li><strong>em:started</strong> (domain: em:Execution; range: xsd:dateTime):
Marks the start the the execution</li>
+<li><strong>em:completed</strong> (domain: em:Execution; range: xsd:dateTime):
Marks the completion of the execution</li>
+<li><strong>em:statusMessage</strong> (domain: em:Excecution; range:
xsd:string): A natural language description providing further information about
the status of this execution. Typically used to parse error messages if the
execution fails (em:status is set to em:StatusFailed).</li>
+</ul>
+</li>
+<li><strong>em:ChainExecution</strong> : Class used to describe the execution
of an enhancement Chain.<ul>
+<li><strong>em:defualtChain</strong> (domain: em:ChainExecution; range:
xsd:boolean): If the executed Chain is currently the default Chain of the
Stanbol Enhancer.</li>
+<li><strong>em:executionPlan</strong> (domain:ChainExecution; range:
ep:ExecutionPlan): Links to the execution plan as provided by the chain.</li>
+<li><strong>em:enhances</strong>(domain: em:ChainExecution; range:
rdf:Resource) : links the em:ChainExection with the URI of the processed
content item. The range needs to be updated as soon as the Stanbol Enhancement
Structure is defined.</li>
+<li><strong>em:enhancedBy</strong> (domain: rdf:Resource; range:
em:ChainExecution) : links the URI of the content item with the metadata about
the enhancement process. The range needs to be updated as soon as the Stanbol
Enhancement Structure is defined.</li>
+</ul>
+</li>
+<li><strong>em:EngineExecution</strong> : Class used to describe the execution
of an EnhancementEngine.<ul>
+<li><strong>em:executionNode</strong> (domain: em:EngineExecution; range:
ep:ExecutionNode): The node within the ExecutionPlan</li>
+</ul>
+</li>
+<li><strong>em:ExecutionStatus</strong> : Class describing the status of an
EngineExecution<ul>
+<li><strong>em:StatusSheduled</strong> : ExecutionStatis instance that
described that an execution is scheduled but has not yet started</li>
+<li><strong>em:StatusInProgress</strong> : ExecutuinStatus instance that
describes that the execution of the linked EngineExecution is in progress</li>
+<li><strong>em:StatusCompleted</strong> : ExecutionStatus instance describing
that the execution has already completed successfully</li>
+<li><strong>em:StatusFailed</strong> : ExecutionStatus indicating that the
execution has failed. Typically a em:statusMessage describing the reason for
the failed execution is provided for em:Executions with that state.</li>
+<li><strong>em:StatusSkiped</strong> : ExecutionStatus indicating that the
execution if an sp:ExecutionNode was skipped. This is only allowed for
execution nodes that are marked as optional. Typically also a em:statusMessage
with the reason should be provided.</li>
+</ul>
+</li>
+</ul>
+<h3 id="example">Example:</h3>
+<p>The following example uses the same example as used within the <a
href="chains/executionplan.html">ExecutionPlan</a> section. To make the
relations between the execution metadata and the execution plan easier to see
the triples of the execution plan are included at the end of this example.</p>
+<p>This example describes the following situation:</p>
+<ul>
+<li>the execution of the content item with the URI 'urn:contentItem1' with the
default chain</li>
+<li>the default chain is represented by a Chain with the name "demoChain" the
ExecutionPlan has the URI 'urn:execPlan'</li>
+<li>the successful execution of the 'langid' engine (execution: 'urn:exec1',
node: 'urn:node1')</li>
+<li>the failed execution of the 'ner' engine (execution: 'urn:exec2', node:
'urn:node2'): As reason for the failure a message is provided that the NER
model for the language 'de' is not available</li>
+<li>the successful execution of the 'zemanta' engine (execution: 'urn:exec3',
node: 'urn:node5'): This engine was started in parallel to the 'ner' egine -
therefore before the chain failed.</li>
+<li>There is no execution of the dbpediaLinking (node: '') and geonamesLinking
(node: '') engines because the chain failed before such engines where
scheduled. This assumes the the EnhancementJobManagers does only add
em:EngineExecution resources when it starts the processing of an
ep:ExecutionNode defined in the execution plan. However EnhancementJobManager
can also create ep:Execution resources for all execution nodes. In that case
there would be also em:EngineExecution resources for the dbpediaLinking and
geonamesLinking engines with the em:status set to 'em:StatusSheduled'. </li>
+</ul>
+<p>The RDF graph with the Execution Metadata:</p>
+<div class="codehilite"><pre><span class="err">urn:exec</span>
+ <span class="err">rdf:type</span> <span
class="err">em:ChainExecution</span>
+ <span class="err">em:executionPlan</span> <span
class="err">urn:execPlan</span>
+ <span class="err">em:enhances</span> <span
class="err">urn:contentItem1</span>
+ <span class="err">em:defaultChain</span> <span
class="err">"true"</span>
+ <span class="err">em:started</span> <span
class="err">2012-01-11T12.13.14.156</span>
+ <span class="err">em:completed</span> <span
class="err">2012-01-11T12.13.15.157</span>
+ <span class="err">em:status</span> <span class="err">em:StatusFailed</span>
+ <span class="err">em:statusMessage</span> <span
class="err">"Unable</span> <span class="err">to</span> <span
class="err">execute</span> <span class="err">EnhancementEngine</span> <span
class="err">'new'</span> <span class="err">\</span>
+ <span class="err">(Message:</span> <span class="err">No</span> <span
class="err">NER</span> <span class="err">model</span> <span
class="err">for</span> <span class="err">language</span> <span
class="err">'de'</span> <span class="err">is</span> <span
class="err">available)."</span>
+ <span class="err">em:executionPart</span> <span
class="err">urn:exec1,</span> <span class="err">urn:exec2,</span> <span
class="err">urn:exec3,</span> <span class="err">urn:exec4,</span> <span
class="err">urn:exec5</span>
+
+<span class="err">urn:exec1</span>
+ <span class="err">rdf:type</span> <span
class="err">em:EngineExecution</span>
+ <span class="err">em:executionPart</span> <span class="err">urn:exec</span>
+ <span class="err">em:executionNode</span> <span
class="err">urn:node1</span>
+ <span class="err">em:status</span> <span
class="err">em:StatusCompleted</span>
+ <span class="err">em:started</span> <span
class="err">2012-01-11T12.13.14.160</span>
+ <span class="err">em:completed</span> <span
class="err">2012-01-11T12.13.14.250</span>
+
+<span class="err">urn:exec2</span>
+ <span class="err">rdf:type</span> <span
class="err">em:EngineExecution</span>
+ <span class="err">em:executionPart</span> <span class="err">urn:exec</span>
+ <span class="err">em:executionNode</span> <span
class="err">urn:node2</span>
+ <span class="err">em:status</span> <span class="err">StatusFailed</span>
+ <span class="err">em:statusMessage</span> <span
class="err">"No</span> <span class="err">NER</span> <span
class="err">model</span> <span class="err">for</span> <span
class="err">language</span> <span class="err">'de'</span> <span
class="err">is</span> <span class="err">available"</span>
+ <span class="err">em:started</span> <span
class="err">2012-01-11T12.13.14.253</span>
+ <span class="err">em:completed</span> <span
class="err">2012-01-11T12.13.14.289</span>
+
+<span class="err">urn:exec3</span>
+ <span class="err">rdf:type</span> <span
class="err">em:EngineExecution</span>
+ <span class="err">em:executionPart</span> <span class="err">urn:exec</span>
+ <span class="err">em:executionNode</span> <span
class="err">urn:node5</span>
+ <span class="err">em:status</span> <span class="err">StatusCompleted</span>
+ <span class="err">em:started</span> <span
class="err">2012-01-11T12.13.14.253</span>
+ <span class="err">em:completed</span> <span
class="err">2012-01-11T12.13.15.150</span>
+</pre></div>
+
+
+<p>The Execution Plan: (copy from the example provided in the ExecutionPlan
section)</p>
+<div class="codehilite"><pre><span class="err">urn:execPlan</span>
+ <span class="err">rdf:type</span> <span class="err">ep:ExecutionPlan</span>
+ <span class="err">ep:hasExecutionNode</span> <span
class="err">urn:node1,</span> <span class="err">urn:node2,</span> <span
class="err">urn:node3,</span> <span class="err">urn:node4,</span> <span
class="err">urn:node5</span>
+ <span class="err">ep:chain</span> <span
class="err">"demoChain"</span>
+
+<span class="err">urn:node1</span>
+ <span class="err">rdf:type</span> <span
class="err">stanbol:ExecutionNode</span>
+ <span class="err">ep:inExecutionPlan</span> <span
class="err">urn:execPlan</span>
+ <span class="err">stanbol:engine</span> <span class="err">langId</span>
+
+<span class="err">urn:node2</span>
+ <span class="err">rdf:type</span> <span class="err">ep:ExecutionNode</span>
+ <span class="err">ep:inExecutionPlan</span> <span
class="err">urn:execPlan</span>
+ <span class="err">ep:dependsOn</span> <span class="err">urn:node1</span>
+ <span class="err">ep:engine</span> <span class="err">ner</span>
+
+<span class="err">urn:node3</span>
+ <span class="err">rdf:type</span> <span class="err">ep:ExecutionNode</span>
+ <span class="err">ep:inExecutionPlan</span> <span
class="err">urn:execPlan</span>
+ <span class="err">ep:dependsOn</span> <span class="err">urn:node1</span>
+ <span class="err">ep:engine</span> <span class="err">dbpediaLinking</span>
+
+<span class="err">urn:node4</span>
+ <span class="err">rdf:type</span> <span class="err">ep:ExecutionNode</span>
+ <span class="err">ep:inExecutionPlan</span> <span
class="err">urn:execPlan</span>
+ <span class="err">ep:dependsOn</span> <span class="err">urn:node1</span>
+ <span class="err">ep:engine</span> <span class="err">geonamesLinking</span>
+
+<span class="err">urn:node5</span>
+ <span class="err">rdf:type</span> <span class="err">ep:ExecutionNode</span>
+ <span class="err">ep:inExecutionPlan</span> <span
class="err">urn:execPlan</span>
+ <span class="err">ep:engine</span> <span class="err">zemanta</span>
+ <span class="err">ep:optional</span> <span
class="err">"true"^^xsd:boolean</span>
+</pre></div>
+
+
+<p>Note that both the Execution Metadata AND the Execution Plan need to be
contained within the metadata of the ContentItem</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0";>Apache
License, Version 2.0</a>.
+ <br />
+ Apache, Stanbol and the Apache feather and Stanbol logos are
trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
