Author: buildbot
Date: Thu Jan 26 07:20:02 2012
New Revision: 803307
Log:
Staging update by buildbot for stanbol
Added:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/chainmanager.html
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.html
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancer-listchain-config.png
(with props)
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.html
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/listchain.html
Added:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/chainmanager.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/chainmanager.html
(added)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/chainmanager.html
Thu Jan 26 07:20:02 2012
@@ -0,0 +1,124 @@
+<!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 - ChainManager</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">ChainManager</h1>
+ <p>The ChainManager provides name based access to all active <a
href="enhancementchain.html">Enhancement Chain</a> and there ServiceReferences.
This interface is typically used by components that need to lookup Chains based
on there name. However the ChainsTracker implementation can also be used to
track specific Chains.</p>
+<h3 id="chainmanager_interface">ChainManager interface</h3>
+<p>This is the Java API providing access to registered Chains in the ways as
described above. This interface includes the following methods:</p>
+<div class="codehilite"><pre><span class="sr">/** Constant for the name of the
DefaultChain */</span>
+<span class="n">DEFAULT_CHAIN_NAME</span> <span class="p">:</span> <span
class="n">String</span>
+<span class="sr">/** Getter for all names with active Chains */</span>
+<span class="n">getActiveChainNames</span><span class="p">()</span> <span
class="p">:</span> <span class="n">Set</span><span
class="sr"><String></span>
+<span class="o">/**</span> <span class="n">Getter</span> <span
class="k">for</span> <span class="n">the</span> <span
class="n">ServiceReference</span> <span class="n">to</span> <span
class="n">the</span> <span class="n">Chain</span>
+ <span class="n">with</span> <span class="n">a</span> <span
class="n">given</span> <span class="n">name</span> <span
class="n">sorted</span> <span class="n">by</span> <span
class="n">service</span> <span class="n">ranking</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="o">/**</span> <span class="n">Getter</span> <span
class="k">for</span> <span class="n">all</span> <span
class="n">ServiceReferences</span> <span class="n">to</span> <span
class="n">Chains</span>
+ <span class="n">with</span> <span class="n">a</span> <span
class="n">given</span> <span class="n">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="sr">/** Getter for the Chain with a given name */</span>
+<span class="o">+</span> <span class="n">getChain</span><span
class="p">(</span><span class="n">Stirng</span> <span
class="n">name</span><span class="p">)</span> <span class="p">:</span> <span
class="n">Chain</span>
+<span class="o">/**</span> <span class="n">Getter</span> <span
class="k">for</span> <span class="n">all</span> <span class="n">Chains</span>
<span class="n">with</span> <span class="n">a</span> <span
class="n">given</span> <span class="n">name</span> <span
class="n">sorted</span>
+ <span class="n">by</span> <span class="n">service</span> <span
class="n">ranking</span> <span class="o">*/</span>
+<span class="o">+</span> <span class="n">getChains</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"><Chain></span>
+<span class="sr">/** Getter for a Chain based on a service reference */</span>
+<span class="o">+</span> <span class="n">getChain</span><span
class="p">(</span><span class="n">ServiceReference</span> <span
class="nb">ref</span><span class="p">)</span> <span class="p">:</span> <span
class="n">Chain</span>
+<span class="sr">/** Checks if there is a chain for the given name */</span>
+<span class="o">+</span> <span class="n">isChain</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="sr">/** Getter for the default chain */</span>
+<span class="o">+</span> <span class="n">getDefault</span><span
class="p">()</span> <span class="p">:</span> <span class="n">Chain</span>
+</pre></div>
+
+
+<p>There are two implementations of this interface available:</p>
+<h4 id="chainmanager_service">ChainManager Service</h4>
+<p>This is an implementation of the ChainManager interface that is registered
as OSGI service. It can be used e.g. by using the @Reference annotation</p>
+<div class="codehilite"><pre><span class="nv">@Reference</span>
+<span class="n">ChainManager</span> <span class="n">chainManager</span>
+</pre></div>
+
+
+<p>This service is provided by the "org.apache.stanbol.enhancer.chainmanger"
module and is included in all Stanbol launchers.</p>
+<h4 id="chainstracker">ChainsTracker</h4>
+<p>This is an Utility similar to the standard OSGI ServiceTracker that allows
to track some/all Chains. It also supports the usage of a
ServiceTrackerCustomizer so that users of that utility can directly react to
changes of tracked Chains.</p>
+<div class="codehilite"><pre><span class="sr">//</span><span
class="n">track</span> <span class="n">only</span> <span
class="s">"myChain"</span> <span class="ow">and</span> <span
class="s">"otherChain"</span>
+<span class="n">ChainsTracker</span> <span class="n">tracker</span> <span
class="o">=</span> <span class="k">new</span> <span
class="n">ChainsTracker</span><span class="p">(</span>
+ <span class="n">context</span><span class="p">,</span> <span
class="s">"myChain"</span><span class="p">,</span><span
class="s">"otherChain"</span><span class="p">);</span>
+<span class="n">tracker</span><span class="o">.</span><span
class="nb">open</span><span class="p">();</span> <span
class="sr">//s</span><span class="n">tart</span> <span class="n">tracking</span>
+
+<span class="sr">//</span><span class="n">the</span> <span
class="n">tracker</span> <span class="n">need</span> <span class="n">to</span>
<span class="n">be</span> <span class="n">closed</span> <span
class="k">if</span> <span class="nb">no</span> <span class="n">longer</span>
<span class="n">needed</span>
+<span class="n">tracker</span><span class="o">.</span><span
class="nb">close</span><span class="p">()</span>
+<span class="n">tracker</span> <span class="o">=</span> <span
class="n">null</span><span class="p">;</span>
+</pre></div>
+
+
+<p>For most users the ChainManager service is sufficient and preferable.
Direct use of the ChainTracker is only recommended if one needs only to track
some specific chains and especially if one needs to get notified an changes of
such chains.</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/chains/enhancementchain.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.html
(added)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.html
Thu Jan 26 07:20:02 2012
@@ -0,0 +1,162 @@
+<!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 - Enhancement Chains</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">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>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>
+
+
+<p>Enhancement requestes issued to </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="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">engines</span>
+</pre></div>
+
+
+<p>are processed by using the default enhancement chain.</p>
+<p>When using the Java API Chains can be looked up as OSGI services. The the
<a href="chainmanager.html">ChainManager</a> service is designed to ease this
by providing a API that allows to access Chains by their name. Because Chains
are not responsible to perform the actual execution but only provide the <a
href="executionplan.html">ExecutionPlan</a> one needs to also lookup an
EnhancementJobManager instance to enhance a contentItem</p>
+<div class="codehilite"><pre><span class="nv">@Reference</span>
+<span class="n">EnhancementJobManager</span> <span
class="n">jobManager</span><span class="p">;</span>
+
+<span class="nv">@Reference</span>
+<span class="n">ChainManager</span> <span class="n">chainManager</span><span
class="p">;</span>
+
+<span class="sr">//</span><span class="n">enhance</span> <span
class="n">a</span> <span class="n">ContentItem</span> <span class="n">ci</span>
+<span class="n">ContentItem</span> <span class="n">ci</span><span
class="p">;</span>
+<span class="sr">//</span><span class="n">by</span> <span
class="n">using</span> <span class="n">the</span> <span class="n">Chain</span>
<span class="s">"demo"</span>
+<span class="n">String</span> <span class="n">chainName</span><span
class="p">;</span>
+<span class="n">Chain</span> <span class="n">chain</span> <span
class="o">=</span> <span class="n">chainManager</span><span
class="o">.</span><span class="n">getChain</span><span class="p">(</span><span
class="n">chainName</span><span class="p">);</span>
+<span class="k">if</span><span class="p">(</span><span class="n">chain</span>
<span class="o">!=</span> <span class="n">null</span><span class="p">){</span>
+ <span class="n">jobManager</span><span class="o">.</span><span
class="n">enhanceContent</span><span class="p">(</span><span
class="n">ci</span><span class="p">,</span><span class="n">chain</span><span
class="p">);</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="sr">//</span><span class="n">Chain</span> <span
class="n">with</span> <span class="n">name</span> <span
class="s">"demo"</span> <span class="n">is</span> <span
class="ow">not</span> <span class="n">active</span>
+<span class="p">}</span>
+<span class="sr">//</span><span class="n">the</span> <span
class="n">enhancement</span> <span class="n">results</span> <span
class="n">are</span> <span class="n">now</span> <span
class="n">available</span> <span class="n">in</span> <span class="n">the</span>
<span class="n">metadata</span>
+<span class="n">MGraph</span> <span class="n">enhancementResults</span> <span
class="o">=</span> <span class="n">ci</span><span class="o">.</span><span
class="n">getMetadata</span><span class="p">();</span>
+</pre></div>
+
+
+<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>
+<span class="o">+</span> <span class="n">getName</span><span
class="p">()</span> <span class="p">:</span> <span class="n">String</span>
+<span class="sr">/** Getter for the execution plan */</span>
+<span class="o">+</span> <span class="n">getExecutionPlan</span><span
class="p">()</span> <span class="p">:</span> <span class="n">Graph</span>
+<span class="sr">/** Getter for the name of the Engines referenced by this
Chain */</span>
+<span class="o">+</span> <span class="n">getEngines</span><span
class="p">()</span> <span class="p">:</span> <span class="n">Set</span><span
class="sr"><String></span>
+<span class="sr">/** Constant for the property used to for the name of the
Chain */</span>
+<span class="o">+</span> <span class="n">PROPERTY_NAME</span> <span
class="p">:</span> <span class="n">String</span>
+</pre></div>
+
+
+<p>Each Chain has an name assigned. This is typically provided by the chain
configuration and MUST me set as value to the property
"stanbol.enhancer.chain.name" of the service registration. The getter for the
name MUST return the same value. Chain implementation will usually get the name
typically by calling</p>
+<p>this.name = (String)ComponentContext.getProperties(Chain.PROPERTY_NAME);</p>
+<p>within the activate method of the Chain. There is also an AbstractChain
implementation provided by the servicesapi module of the Stanbol Enhancer that
already implements this functionality.</p>
+<p>The getEngines method returns the name of all EnhancementEngines referenced
by a Chain. Note that this method returns a Set. This method is intended to
allow fast access to the referenced engines and does not provide any
information about the execution order.</p>
+<p>Components that need to know the details about a Chain need to process the
<a href="executionplan.html">ExecutionPlan</a> returned by the
getExectuonPlan() method. The <a href="executionplan.html">ExecutionPlan</a> is
represented as an RDF graph following the ExecutionPlan Ontology. It formally
describes how a ContentItem must be processed by the EnhancementJobManager. For
details see the documentation for the <a
href="executionplan.html">ExecutionPlan</a>.</p>
+<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>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>
+<ol>
+<li>the Chain with the highest "service.ranking" and</li>
+<li>the Chain with the lowest "service.id"</li>
+</ol>
+<p>will be selected on requests for a given Chain name. Via the RESTful
service API there is no possibility to call the other chains for a given name.
However the ChainManager interface allows to access all registered services for
a given name.</p>
+<h3 id="default_chain">Default Chain</h3>
+<p>The second important concept of the Chain management is the definition of
the "default chain". The default Chin is used for enhancement requests that do
not specify a Chain. This is true for requests to the "/engines" and
"/enhancer" RESTful services as well as API calls to the
"EnhancementJobManager.enhanceContent(ContentItem ci)" method.</p>
+<p>The default Chain is determined by the following rules:</p>
+<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>
+</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>
+<h2 id="chain_implementations">Chain implementations</h2>
+<p>The following Chain implementations are included within the default Stanbol
Enhancer distribution:</p>
+<ul>
+<li><strong><a href="defaultchain.html">DefaultChain</a></strong>:
Implementation that includes all currently active EnhancementEngine. If enabled
it registers itself under the name "default" with the service ranking
Integer.MIN_VALUE. This makes this chain to the default chain as long users do
not deactivate it or register an other chain with the name "default".</li>
+<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>
+</ul>
+ </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/chains/enhancer-listchain-config.png
==============================================================================
Binary file - no diff available.
Propchange:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancer-listchain-config.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.html
(added)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.html
Thu Jan 26 07:20:02 2012
@@ -0,0 +1,165 @@
+<!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 - ExecutionPlan</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">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>
+<h2 id="executionplan_ontology">ExecutionPlan Ontology</h2>
+<p>The RDFS schema used for the execution plan is defined as follows.</p>
+<ul>
+<li>Namespace: ep :
http://stanbol.apache.org/ontology/enhancer/executionplan#</li>
+<li><strong>ep:ExecutionPlan</strong> : Represent an execution plan defined by
all linked execution nodes.<ul>
+<li><strong>ep:hasExecutionNode</strong> (domain: ep:ExecutionPlan; range:
ep:ExecutionNode; inverseOf: ep:inExecutionPlan): links the execution plan with
all the execution nodes.</li>
+<li><strong>ep:chain</strong> (domain: ep:ExecutionPlan; range: xsd:string):
The name of the Chain this execution plan is used for.</li>
+</ul>
+</li>
+<li><strong>ep:ExecutionNode</strong> : Class used for all Nodes representing
the execution of an Enhancement Engine.<ul>
+<li><strong>ep:inExecutionPlan</strong> (domain: ep:ExecutionNode; range:
ep:ExecutionPlan ;inverseOf: ep:hasExecutionNode): functional property that
links the execution node with an execution plan</li>
+<li><strong>ep:engine</strong> (domain: ep:ExecutionNode; range: xsd:string):
The property used to link to the Enhancement Engine by the name of the
engine.</li>
+<li><strong>ep:dependsOn</strong> (domain: ep:ExecutionNode; range:
ep:ExecutionNode) Defines that the execution of this node depends on the
completion of the referenced one.</li>
+<li><strong>ep:optional</strong> (domain: ep:ExecutionNode; range:
xsd:boolean) Can be used to specify that the execution of this
EnhancementEngine is optional. If this property is set to TRUE an engine will
be marked as executed even if it execution was not possible (e.g. because an
engine with this name was not active) or the execution failed (e.g. because of
the Exception). </li>
+</ul>
+</li>
+</ul>
+<p>Note the the data for the ep:ExecutionPlan and the
ep:hasExecutionNode/ep:inExecutionPlan typically need not to be parsed as
configuration of a Chain. This information are typically automatically added
based on the assumption that all ep:ExecutionNode parsed in the configuration
for a chain are member of the execution plan for such chain. Therefore this
information is typically added by the Chain itself when the configuration is
parsed and validated.</p>
+<h4 id="example">Example:</h4>
+<p>This example shows an ExecutionPlan with three nodes for the "langId",
"ner", "dbpediaLinking" "geonamesLinking" and "zemanta" engine. Note that this
names refer to actual EnhancementEngine Services registered with the current
OSGI Environment.</p>
+<p>This example assumes that</p>
+<ul>
+<li>"langId" is the singleton instance of LangIdEnhancementEngine</li>
+<li>"ner" is the default instance of the
NamedEntityExtractionEnhancementEngine engine</li>
+<li>"dbpediaLinking" is an instance of the NamedEntityTaggingEngine configured
to use the dbpedia.org ReferencedSite of the Entityhub</li>
+<li>"geonamesLinking" is an instance of the NamedEntityTaggingEngine
configured to use the geonames.org ReferencedSite</li>
+<li>"zemanta" is the singleton instance of the ZemantaEnhancementEngine</li>
+</ul>
+<p>The RDF graph of such a chain would look:</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>This plan defines that the "langId" and the "zemanta" engine do not depend
on anything and can therefore be executed from the start (even in parallel if
the JobManager execution this chains supports this). The execution of the "ner"
engine depends on the extraction of the language and the execution of the
entity linking to dbpedia and geonames depends on the "ner" engine. Note that
the execution of the "dbpediaLinking" and "geonamesLinking" could be also
processed in parallel.</p>
+<h4 id="executionplan_utility">ExecutionPlan Utility:</h4>
+<p>The Enhancer MUST also define an Utility that provides the following
utility</p>
+<div class="codehilite"><pre><span class="sr">/** Getter for the list of
executable ep:ExecutionNodes */</span>
+<span class="o">+</span> <span class="n">getExecuteable</span><span
class="p">(</span><span class="n">Graph</span> <span
class="n">executionPlan</span><span class="p">,</span> <span
class="n">Set</span><span class="sr"><NonLiteral></span> <span
class="n">completed</span><span class="p">)</span> <span class="p">:</span>
<span class="n">Collection</span><span class="sr"><NonLiteral></span>
+</pre></div>
+
+
+<p>This method takes an execution plan and the list of already executed nodes
as input and return the list of ExecutionNodes that can be executed next. The
existing utility methods within the EnhancementEngineHelper can be used to
retrieve further information from the ex:ExecutionNode's returned by this
method.</p>
+<p>Typically code using this utility will look like this (pseudo code)</p>
+<div class="codehilite"><pre><span class="n">Graph</span> <span
class="n">executionPlan</span> <span class="o">=</span> <span
class="n">chain</span><span class="o">.</span><span
class="n">getExecuctionPlan</span><span class="p">();</span>
+<span class="n">Map</span><span class="o"><</span><span
class="n">String</span><span class="p">,</span> <span
class="n">EnhancementEngine</span><span class="o">></span> <span
class="n">engines</span> <span class="o">=</span> <span
class="n">enhancementEngineManager</span><span class="o">.</span><span
class="n">getActiveEngines</span><span class="p">(</span><span
class="n">chain</span><span class="p">);</span>
+<span class="n">Collection</span><span class="sr"><NonLiteral></span>
<span class="n">executed</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">HashSet</span><span
class="sr"><NonLiteral></span><span class="p">();</span>
+<span class="n">Collection</span><span class="sr"><NonLiteral></span>
<span class="k">next</span><span class="p">;</span>
+<span class="k">while</span><span class="p">(</span><span
class="o">!</span><span class="p">(</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="o">.</span><span
class="n">isEmpty</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="n">EnhancementEngine</span> <span class="n">engine</span>
<span class="o">=</span> <span class="n">engines</span><span
class="o">.</span><span class="n">get</span><span class="p">(</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">Boolean</span> <span class="n">optional</span> <span
class="o">=</span> <span class="n">EnhancementEngineHelper</span><span
class="o">.</span><span class="n">get</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_OPTIONAL</span><span class="p">,</span><span
class="n">Boolean</span><span class="o">.</span><span
class="n">class</span><span class="p">,</span><span
class="n">literalFactory</span><span class="p">);</span>
+ <span class="sr">/* Execute the Engine */</span>
+ <span class="n">completed</span><span class="o">.</span><span
class="n">add</span><span class="p">(</span><span class="n">node</span><span
class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+ </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/chains/listchain.html
==============================================================================
---
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/listchain.html
(added)
+++
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/chains/listchain.html
Thu Jan 26 07:20:02 2012
@@ -0,0 +1,97 @@
+<!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 - ListChain</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">ListChain</h1>
+ <p>The List Chain creates the ExecutionPlan based on the exact order of
the configured EnhancementEngines. This provides users with a simple
possibility configure the exact oder in that the referenced EnhancementEngines
are called during the enhancement process of a content item. However the
ListChain can not support parallel execution of engines a considerable
disadvantage in contrast to the <a href="graphchain.html">GraphChain</a>.</p>
+<p>A typical usage scenario would be that users start of with configuring a
ListChain and later optimize the execution by migrating functional
configuration to <a href="graphchain.html">GraphChain</a>s.</p>
+<h3 id="configuration">Configuration</h3>
+<p>The property "stanbol.enhancer.chain.list.enginelist" is used to provide
the list of engine names. This configuration MUST BE parsed as an Array as
string because the ordering if the configured entries is central for the
configuration.</p>
+<p>In addition it is possible to define Engines as optional. This allows to
specify that the enhancement process should not fail if an Engine is not active
or fails while processing a content item.</p>
+<p>The syntax to define an Engine as optional is as follows</p>
+<div class="codehilite"><pre><span class="sr"><name></span><span
class="p">;</span><span class="n">optional</span>
+<span class="sr"><name></span><span class="p">;</span><span
class="n">optional</span><span class="o">=</span><span class="n">true</span>
+</pre></div>
+
+
+<p>both variants result that the execution of the engine with the name <name>
is optional.</p>
+<p>The following figure shows the configuration dialog for ListCahins as
provided by the Apache Felix Web Console.</p>
+<p><img alt="Configuration Dialog for the ListChain"
src="enhancer-listchain-config.png" title="Sceenshot of the Configuration
Dialog for a ListChain with required and optional Engines" /></p>
+<p>It is also possible to configure a ListChain by directly installing a
configuration with the name "{classname}-{configName}.config". Note that the
{configName} needs not to be the same as the name of the chain. The
{configName} is just used by the OSGI environment to distinguish different
configuration for {classname}.</p>
+<p>To create the same configuration as in the above screenshot the file would
need to look like this:</p>
+<div class="codehilite"><pre><span class="n">stanbol</span><span
class="o">.</span><span class="n">enhancer</span><span class="o">.</span><span
class="n">chain</span><span class="o">.</span><span class="n">name</span><span
class="o">=</span><span class="s">"list"</span>
+<span class="n">stanbol</span><span class="o">.</span><span
class="n">enhancer</span><span class="o">.</span><span
class="n">chain</span><span class="o">.</span><span class="n">list</span><span
class="o">.</span><span class="n">enginelist</span><span
class="o">=</span><span class="p">[</span><span
class="s">"metaxa;optional"</span><span class="p">,</span><span
class="s">"langid"</span><span class="p">,</span><span
class="s">"ner"</span><span class="p">,</span><span
class="s">"dbpediaLinking"</span><span class="p">]</span>
+</pre></div>
+
+
+<h3 id="calculation_of_the_executionplan">Calculation of the ExecutionPlan</h3>
+<p>The ExecutionPlan is created based on the exact order of the
EnhancementEngines provided by the "stanbol.enhancer.chain.list.enginelist"
property. The configuration MUST contain at least a single engine. In addition
no engine MUST be mentioned twice.</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>
