You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by bu...@apache.org on 2012/07/16 15:02:48 UTC
svn commit: r825985 [2/12] - in /websites/staging/stanbol/trunk/content: ./
stanbol/docs/trunk/ stanbol/docs/trunk/cmsadapter/
stanbol/docs/trunk/components/ stanbol/docs/trunk/components/cmsadapter/
stanbol/docs/trunk/components/contenthub/ stanbol/do...
Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/executionplan.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/executionplan.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/executionplan.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,194 @@
+<!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 Plan</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"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <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></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</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>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</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">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/enhancer/">Enhancer</a> » <a href="/stanbol/docs/trunk/components/enhancer/chains/">Chains</a>
+ </div>
+ <h1 class="title">Execution Plan</h1>
+ <p>The ExecutionPlan is represented as an RDF graph following the ExecutionPlan ontology. It needs to be provided by the <a href="index.html">Enhancement Chain</a> and is used by the <a href="../enhancementjobmanager.html">EnhancementJobManager</a> to enhance <a href="../contentitem.html">ContentItems</a> 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>
+<p><img alt="Execution Plan" src="executionplan.png" title="Overview of the Execution Plan Ontology" /></p>
+<ul>
+<li>Namespace: ep : http://stanbol.apache.org/ontology/enhancer/executionplan#</li>
+<li><strong>ep:ExecutionPlan</strong> : Represents 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 is 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 <a href="../engines">EnhancementEngine</a> 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 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 a chain. Therefore, this information is typically added by the chain itself when the configuration is parsed and validated.</p>
+<h3 id="example">Example</h3>
+<p>This example shows an ExecutionPlan with the nodes for the "langId", "ner", "dbpediaLinking" "geonamesLinking" and "zemanta" engine. Note that this names refer to actual <a href="../engines">EnhancementEngine</a> Services registered with the current OSGI Environment.</p>
+<p>This example assumes that</p>
+<ul>
+<li>"langId" is the singleton instance of <a href="../engines/langidengine.html">LangIdEnhancementEngine</a></li>
+<li>"ner" is the default instance of the <a href="../engines/namedentityextractionengine.html">NamedEntityExtractionEnhancementEngine</a></li>
+<li>"dbpediaLinking" is an instance of the <a href="../engines/namedentitytaggingengine.html">NamedEntityTaggingEngine</a> configured to use the dbpedia.org ReferencedSite of the Entityhub</li>
+<li>"geonamesLinking" is an instance of the <a href="../engines/namedentitytaggingengine.html">NamedEntityTaggingEngine</a> configured to use the geonames.org ReferencedSite</li>
+<li>"zemanta" is the singleton instance of the <a href="../engines/zemantaengine.html">ZemantaEnhancementEngine</a></li>
+</ul>
+<p>The RDF graph of such a chain would look</p>
+<div class="codehilite"><pre>urn:execPlan
+ rdf:type ep:ExecutionPlan
+ ep:hasExecutionNode urn:node1, urn:node2, urn:node3, urn:node4, urn:node5
+ ep:chain "demoChain"
+
+urn:node1
+ rdf:type stanbol:ExecutionNode
+ ep:inExecutionPlan urn:execPlan
+ ep:engine langId
+
+urn:node2
+ rdf:type ep:ExecutionNode
+ ep:inExecutionPlan urn:execPlan
+ ep:dependsOn urn:node1
+ ep:engine ner
+
+urn:node3
+ rdf:type ep:ExecutionNode
+ ep:inExecutionPlan urn:execPlan
+ ep:dependsOn urn:node1
+ ep:engine dbpediaLinking
+
+urn:node4
+ rdf:type ep:ExecutionNode
+ ep:inExecutionPlan urn:execPlan
+ ep:dependsOn urn:node1
+ ep:engine geonamesLinking
+
+urn:node5
+ rdf:type ep:ExecutionNode
+ ep:inExecutionPlan urn:execPlan
+ ep:engine zemanta
+ ep:optional "true"^^xsd:boolean
+</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 of these 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>
+<h2 id="executionplan-utility">ExecutionPlan Utility</h2>
+<p>The Enhancer MUST also define an utility that provides the following:</p>
+<div class="codehilite"><pre><span class="cm">/** Getter for the list of executable ep:ExecutionNodes */</span>
+<span class="o">+</span> <span class="n">getExecuteable</span><span class="o">(</span><span class="n">Graph</span> <span class="n">executionPlan</span><span class="o">,</span> <span class="n">Set</span><span class="o"><</span><span class="n">NonLiteral</span><span class="o">></span> <span class="n">completed</span><span class="o">)</span> <span class="o">:</span> <span class="n">Collection</span><span class="o"><</span><span class="n">NonLiteral</span><span class="o">></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:ExecutionNodes returned by this method.</p>
+<p>The 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="na">getExecuctionPlan</span><span class="o">();</span>
+<span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</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="na">getActiveEngines</span><span class="o">(</span><span class="n">chain</span><span class="o">);</span>
+<span class="n">Collection</span><span class="o"><</span><span class="n">NonLiteral</span><span class="o">></span> <span class="n">executed</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashSet</span><span class="o"><</span><span class="n">NonLiteral</span><span class="o">>();</span>
+<span class="n">Collection</span><span class="o"><</span><span class="n">NonLiteral</span><span class="o">></span> <span class="n">next</span><span class="o">;</span>
+<span class="k">while</span><span class="o">(!(</span><span class="n">next</span> <span class="o">=</span> <span class="n">ExecutionPlanUtils</span><span class="o">.</span><span class="na">getExecuteable</span><span class="o">(</span><span class="n">plan</span><span class="o">,</span> <span class="n">executed</span><span class="o">)).</span><span class="na">isEmpty</span><span class="o">()){</span>
+ <span class="k">for</span><span class="o">(</span><span class="n">NonLiteral</span> <span class="n">node</span> <span class="o">:</span> <span class="n">next</span><span class="o">){</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="na">get</span><span class="o">(</span>
+ <span class="n">EnhancementEngineHelper</span><span class="o">.</span><span class="na">getString</span><span class="o">(</span><span class="n">executionPlan</span><span class="o">,</span><span class="n">node</span><span class="o">,</span> <span class="n">EX_ENGINE</span><span class="o">));</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="na">get</span><span class="o">(</span>
+ <span class="n">executionPlan</span><span class="o">,</span><span class="n">node</span><span class="o">,</span><span class="n">EX_OPTIONAL</span><span class="o">,</span><span class="n">Boolean</span><span class="o">.</span><span class="na">class</span><span class="o">,</span><span class="n">literalFactory</span><span class="o">);</span>
+ <span class="cm">/* Execute the Engine */</span>
+ <span class="n">completed</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">node</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</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/components/enhancer/chains/executionplan.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/executionplan.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/graphchain.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/graphchain.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/graphchain.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,160 @@
+<!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 - Graph Chain</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"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <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></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</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>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</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">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/enhancer/">Enhancer</a> » <a href="/stanbol/docs/trunk/components/enhancer/chains/">Chains</a>
+ </div>
+ <h1 class="title">Graph Chain</h1>
+ <p>The GraphChain allows to directly configure the ExecutionPlan returned by the Chain.getExecutionPlan() method. This means on the one hand that it allows to configure any kind of execution process on the other hand its usage also requires a lot of knowledge about the <a href="../engines">EnhancementEngine</a>s and the ExecutionPlan model.</p>
+<p>Typically it is a good practice to start with other - more simple to use - Chain implementation such as the <a href="weightedchain.html">Weighted Chain</a> and only afterwards convert this configuration to a GraphChain to configure optimizations to the enhancement process such as to allow more engines to be executed in parallel.</p>
+<h2 id="configuration">Configuration</h2>
+<p>The GraphChain supports two variants to configure the ExecutionPlan.</p>
+<h3 id="graphresource">GraphResource</h3>
+<p>A GraphResource is an RDF file available via the DataFileProvider. The easiest way is to copy the RDF file defining the ExecutionPlan to the "/sling/datafile" directory within the Stanbol home directory. The configuration of the GraphChain needs then only to refer to that file such as:</p>
+<div class="codehilite"><pre><span class="na">stanbol.enhancer.chain.graph.graphresource</span><span class="o">=</span><span class="s">myExecutionPlan.rdf</span>
+</pre></div>
+
+
+<p>The used RDF encoding is guessed by the file extension. If the extension is not recognized, the format can be also parsed as additional parameter</p>
+<div class="codehilite"><pre><span class="na">stanbol.enhancer.chain.graph.graphresource</span><span class="o">=</span><span class="s">myExecutionPlan.something;format=application/rdf+xml</span>
+</pre></div>
+
+
+<p>The GraphCain will track for that file and activate itself as soon as the file gets available. Removing the file, waiting some seconds and providing the new version afterwards should also work. Just replacing the file will not work, because the DataFileProvider does not have support for updates. In such cases it might be needed to deactivate/activate the GraphChain.</p>
+<h3 id="chainlist">ChainList</h3>
+<p>This allows to directly configure the ExecutionPlan as value of the "stanbol.enhancer.chain.graph.chainlist" property. Both arrays and collections are supported. </p>
+<p><em>Note:</em> As soon as a graph resource is configured the ChainList will be ignored. This is even true if the configured GraphResource is currently not available!</p>
+<p>The syntax is defined as follows:</p>
+<div class="codehilite"><pre>{engine-name};[optional];[dependsOn={engine-name1},{engine-name2}]
+</pre></div>
+
+
+<p>The following example shows how this syntax can be used to define an ExecutionPlan.</p>
+<div class="codehilite"><pre>metaxa;optional
+langId;dependsOn=metaxa
+ner;dependsOn=langId
+zemanta;optional
+dbpedia-linking;dependsOn=ner
+geonames;optional;dependsOn=ner
+refactor;dependsOn=geonames,dbpedia-linking,zemanta
+</pre></div>
+
+
+<p><em>Note:</em> The internal oder of the list does not influence the resulting ExecutionPlan. Only the "dependsOn" properties are used to determine the execution order of the engines and if engines can be executed in parallel.</p>
+<p>Within an OSGI configuration file (org.apache.stanbol.enhancer.chain.graph.impl.GraphChain-myGraphChain.config) this would look like</p>
+<div class="codehilite"><pre><span class="na">stanbol.enhancer.chain.graph.chainlist</span><span class="o">=</span><span class="s">[</span>
+ <span class="na">"metaxa;optional","langId;dependsOn\</span><span class="o">=</span><span class="s">metaxa","ner;dependsOn\=langId",</span>
+ <span class="na">"zemanta;optional","dbpedia-linking;dependsOn\</span><span class="o">=</span><span class="s">ner",</span>
+ <span class="na">"geonames;optional;dependsOn\</span><span class="o">=</span><span class="s">ner",</span>
+ <span class="na">"refactor;dependsOn\</span><span class="o">=</span><span class="s">geonames,dbpedia-linking,zemanta"]</span>
+</pre></div>
+
+
+<p><em>Note:</em> The whole test MUST BE in a single line within the .config file.</p>
+<p>A better visual expression provides this screenshot of the Apache Felix web console showing the dialog for the above configuration</p>
+<p><img alt="GraphChain configuration dialog with configured ChainList" src="enhancer-graphchain-config.png" title="A ChainList allows to define one ExecutionNode per line. The ExecutionPlan is calculated based on the dependsOn properties. The ordering of the list element has no influence on the ExecutionPlan." /></p>
+<h2 id="execution">Execution</h2>
+<p>In contrast to other chain implementations the ExecutionPlan must not be calculated but is directly parsed by the user. This provides the most possible freedom in defining how the execution should take place.</p>
+<h3 id="optional-engines">Optional Engines</h3>
+<p>The execution of optional engines is not mandatory. The enhancement process will continue, even if they are not active or their execution fail. For users it is important to know, that even engines that depend on an optional engine that was not executed will be called.</p>
+<p>Given the above example this means that even if the 'metaxa' engine can not be executed the 'langId' will be called by the EnhancementJobManager.</p>
+<h3 id="parallel-execution">Parallel Execution</h3>
+<p>Engines are executed as soon as all engines they depend on have completed. This also includes if optional engines were skipped (because they are not active) or failed. This means that in most cases several EnhancementEngines can be executed in parallel.</p>
+<p>Given the above example, both the 'zemanta' and the 'metaxa' engine are executed as soon as the enhancement process starts.
+When 'metaxa' is finished, the 'langid' engine is called. After the 'langid' finishes its work, the EnhancementJobManager calls the 'ner' engine. After that both the 'dbpedia-linking' and the 'geonames' engine are called. At this time three engines might run simultaneously assuming that 'zemanta' has not finished yet. Before the 'refactor' engine can be executed it need to wait for all these engines to complete.</p>
+<p>Note that for parallel execution to be activated both the used EnhancementJobManager and the different engines must support asynchronous enhancement.</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/components/enhancer/chains/index.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/index.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/index.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,192 @@
+<!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"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <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></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</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>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</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">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/enhancer/">Enhancer</a> » <a href="/stanbol/docs/trunk/components/enhancer/chains/">Chains</a>
+ </div>
+ <h1 class="title">Enhancement Chains</h1>
+ <p>An Enhancement Chain defines how content parsed to the Stanbol Enhancer is processed. More concretely it defines which <a href="../engines">EnhancementEngines</a> and in what order are used to process <a href="../contentitem.html">ContentItems</a>. 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 their name under</p>
+<div class="codehilite"><pre>http://{host}:{port}/{stanbol-path}/enhancer/chain/{chain-name}
+</pre></div>
+
+
+<p>Enhancement requests issued to </p>
+<div class="codehilite"><pre>http://{host}:{port}/{stanbol-path}/enhancer
+http://{host}:{port}/{stanbol-path}/engines
+</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 <a href="chainmanager.html">ChainManager</a> service is designed to ease this by providing an 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="nd">@Reference</span>
+<span class="n">EnhancementJobManager</span> <span class="n">jobManager</span><span class="o">;</span>
+
+<span class="nd">@Reference</span>
+<span class="n">ChainManager</span> <span class="n">chainManager</span><span class="o">;</span>
+
+<span class="c1">//enhance a ContentItem ci </span>
+<span class="n">ContentItem</span> <span class="n">ci</span><span class="o">;</span>
+<span class="c1">//by using the Chain "demo"</span>
+<span class="n">String</span> <span class="n">chainName</span><span class="o">;</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="na">getChain</span><span class="o">(</span><span class="n">chainName</span><span class="o">);</span>
+<span class="k">if</span><span class="o">(</span><span class="n">chain</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">){</span>
+ <span class="n">jobManager</span><span class="o">.</span><span class="na">enhanceContent</span><span class="o">(</span><span class="n">ci</span><span class="o">,</span><span class="n">chain</span><span class="o">);</span>
+<span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
+ <span class="c1">//Chain with name "demo" is not active</span>
+<span class="o">}</span>
+<span class="c1">//the enhancement results are now available in the 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="na">getMetadata</span><span class="o">();</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 defines just the following three methods:</p>
+<div class="codehilite"><pre><span class="cm">/** Getter for the name of the Chain */</span>
+<span class="o">+</span> <span class="n">getName</span><span class="o">()</span> <span class="o">:</span> <span class="n">String</span>
+<span class="cm">/** Getter for the execution plan */</span>
+<span class="o">+</span> <span class="n">getExecutionPlan</span><span class="o">()</span> <span class="o">:</span> <span class="n">Graph</span>
+<span class="cm">/** Getter for the name of the Engines referenced by this Chain */</span>
+<span class="o">+</span> <span class="n">getEngines</span><span class="o">()</span> <span class="o">:</span> <span class="n">Set</span><span class="o"><</span><span class="n">String</span><span class="o">></span>
+<span class="cm">/** 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="o">:</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 be 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 by calling</p>
+<div class="codehilite"><pre><span class="k">this</span><span class="o">.</span><span class="na">name</span> <span class="o">=</span> <span class="o">(</span><span class="n">String</span><span class="o">)</span><span class="n">ComponentContext</span><span class="o">.</span><span class="na">getProperties</span><span class="o">(</span><span class="n">Chain</span><span class="o">.</span><span class="na">PROPERTY_NAME</span><span class="o">);</span>
+</pre></div>
+
+
+<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 <a href="../engines">EnhancementEngines</a> 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 <code>getExecutionPlan()</code> 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 any Chain implementation it is important that the returned Graph holding the execution plan MUST BE read-only AND final. This means, 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, the EnhancementJobManager implementation MUST retrieve the execution plan once and then use this instance for the whole enhancement process. Because of the above requirement that the execution plan is stored in a 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 the ongoing enhancement processes.</p>
+<h2 id="enhancement-chain-management">Enhancement Chain Management</h2>
+<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 requests 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, then 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 Chain 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 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 considers all currently active <a href="../engines">EnhancementEngines</a> and sorts them based on their 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-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 their name. It also provides a getter for the default chain. There is also an 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>: This implementation includes all currently active EnhancementEngines. 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 as configuration.</li>
+<li><strong>SingleEngineChain</strong>: An Adapter to execute a single EnhancementEngine within a Chain. This type of Chain 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>
+
+ <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/components/enhancer/chains/listchain.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/listchain.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/listchain.html Mon Jul 16 13:02:45 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 - List Chain</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"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <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></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</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>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</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">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/enhancer/">Enhancer</a> » <a href="/stanbol/docs/trunk/components/enhancer/chains/">Chains</a>
+ </div>
+ <h1 class="title">List Chain</h1>
+ <p>The ListChain creates the ExecutionPlan based on the exact order of the configured <a href="../engines">EnhancementEngines</a>. This provides users with a simple possibility to configure the exact oder in which 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 <a href="graphchain.html">GraphChain</a>.</p>
+<h2 id="configuration">Configuration</h2>
+<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 of the configured entries is essential 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 below <em>(Both variants make the execution of the engine with the name <name> optional.)</em>:</p>
+<div class="codehilite"><pre><name>;optional
+<name>;optional=true
+</pre></div>
+
+
+<p>The following figure shows the configuration dialog for ListChains as provided by the Apache Felix Web Console.</p>
+<p><img alt="Configuration dialog for the ListChain" src="enhancer-listchain-config.png" title="Screenshot 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 configurations 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="na">stanbol.enhancer.chain.name</span><span class="o">=</span><span class="s">"list"</span>
+<span class="na">stanbol.enhancer.chain.list.enginelist</span><span class="o">=</span><span class="s">["metaxa;optional","langid","ner","dbpediaLinking"]</span>
+</pre></div>
+
+
+<h2 id="calculation-of-the-executionplan">Calculation of the ExecutionPlan</h2>
+<p>The ExecutionPlan is created based on the exact order of the <a href="../engines">EnhancementEngines</a> 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>
Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/weightedchain.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/weightedchain.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/chains/weightedchain.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,128 @@
+<!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 - Weighted Chain</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"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <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></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</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>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</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">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/enhancer/">Enhancer</a> » <a href="/stanbol/docs/trunk/components/enhancer/chains/">Chains</a>
+ </div>
+ <h1 class="title">Weighted Chain</h1>
+ <p>The WeightedChain takes a list of <a href="../engines">EnhancementEngine</a> names as input and uses the "org.apache.stanbol.enhancer.engine.order" metadata of the configured Engines to calculate an ExecutionPlan.</p>
+<p>This chain is designed for easy configuration - just a list of the engine names - but has limited possibilities to control the execution order.</p>
+<h2 id="configuration">Configuration</h2>
+<p>The property "stanbol.enhancer.chain.weighted.chain" is used to provide the list of engine names. Both arrays and collections are supported as values.</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 <em>(Both variants make the execution of the engine with the name <name> optional.)</em>:</p>
+<div class="codehilite"><pre><name>;optional
+<name>;optional=true
+</pre></div>
+
+
+<p><img alt="Configuration dialog for the WeightedCahin" src="enhancer-weightedchain-config.png" title="Screenshot of the configuration dialog for a WeightedChain with two required and one optional engine" /></p>
+<h2 id="calculation-of-the-executionplan">Calculation of the ExecutionPlan</h2>
+<p>It is important to note that the ordering of the list has no influence on the ExecutionPlan because the order of execution of the configured <a href="../engines">EnhancementEngines</a> is calculated only by using the value of the "org.apache.stanbol.enhancer.engine.order" property provided by the EnhancementEngine:</p>
+<ul>
+<li>Engines with a lower order are executed before engines with a higher value</li>
+<li>Engines with the same order may be executed simultaneously if the EnhancementJobManager and the EnhancementEngine do support this feature.</li>
+</ul>
+<p>The WeightedCahin follows exactly the same algorithm as the WeightedJobManager used to decide the execution order of all active EnhancementEngines. However the WeightedChain will only consider configured chains and ignore others.</p>
+<p>The following image shows the ExecutionPlan as calculated based on the above configuration.</p>
+<p><img alt="ExecutionPlan for the keyword chain" src="enhancer-weightedchain-allactive.png" title="The ExecutionPlan is calculated based on the 'order' information of the Enhancement Engines. In this case first 'metaxa' is used to convert any type of content to plain text; second the 'langid' engine is used to detect the language and third the words mentioned in the text are used to lookup entities in DBpedia.org" /></p>
+<p>If some of the Enhancement Engines are not available this will be visualized as follows. If you parse content by using the RESTful interface similar information will be available via the the Execution Metadata included in the metadata of the enhanced content item.</p>
+<p><img alt="Optional Engine is inactive" src="enhancer-weightedchain-optionalinactive.png" title="The optional 'metaxa' engine is inactive. The engines can still be executed however content other than plain text will bot get enhanced" /></p>
+<p>This shows that the optional engine 'metaxa' is currently not available. The chain can be still used however the functionality provided by this optional engine will not be available. In this case only requests for plain text files could be processed.</p>
+<p>The next figure shows a situation where a required engine is not active. Requests to this chain will fail until all required engines are active.</p>
+<p><img alt="Required Engine is inactive" src="enhancer-weightedchain-requiredinactive.png" title="The required 'langid' engine is not active. Because of this requests to this chain will fail." /></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/components/enhancer/contentitem.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/contentitem.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/enhancer/contentitem.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,228 @@
+<!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 - Content Item</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"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <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></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</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>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</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">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/enhancer/">Enhancer</a>
+ </div>
+ <h1 class="title">Content Item</h1>
+ <p><span style="float:right"> <img alt="Content Item Overview" src="contentitemoverview.png" title="The ContentItem can contain several ContentParts and the Enhancement Metadata - an RDF Graph" /></span> </p>
+<p>The ContentItem is the object which represents the content to be enhanced by Apache Stanbol. It is created based on the data provided by the enhancement request and used throughout the enhancement process to store results. Therefore, after the enhancement process has finished, the ContentItem represents the result of the Apache Stanbol enhancement process. ContentItem instances are created by using the <a href="contentitemfactory.html">ContentItemFactory</a> service.</p>
+<p>The following section describes the interface of the ContentItem in detail:</p>
+<h3 id="content-parts">Content Parts</h3>
+<p>Content parts are used to represent the original content as well as transformations of the original content (typically created by pre-processing <a href="engines/list.html">enhancement engines</a> such as the <a href="engines/metaxaengine.html">Metaxa engine</a>). </p>
+<p>The ContentItem provides the following API to work with content parts:</p>
+<div class="codehilite"><pre><span class="cm">/** Getter for the ContentPart based on the index */</span>
+<span class="n">getPart</span><span class="o">(</span><span class="kt">int</span> <span class="n">index</span><span class="o">,</span> <span class="n">Class</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">type</span><span class="o">)</span> <span class="o">:</span> <span class="n">T</span>
+<span class="cm">/** Getter for the ContentPart based on its ID */</span>
+<span class="n">getPart</span><span class="o">(</span><span class="n">UriRef</span> <span class="n">uri</span><span class="o">,</span> <span class="n">Class</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">type</span><span class="o">)</span> <span class="o">:</span> <span class="n">T</span>
+<span class="cm">/** Getter for the ID based on the index */</span>
+<span class="n">getPartUri</span><span class="o">(</span><span class="n">index</span> <span class="n">index</span><span class="o">)</span> <span class="o">:</span> <span class="n">UriRef</span>
+<span class="cm">/** Adds a new ContentPart to the content item */</span>
+<span class="n">addPart</span><span class="o">(</span><span class="n">UriRef</span> <span class="n">uri</span><span class="o">,</span> <span class="n">Object</span> <span class="n">part</span><span class="o">)</span> <span class="o">:</span> <span class="n">Object</span>
+</pre></div>
+
+
+<p>Content parts are accessible by the index <em>and</em> by their URI formatted ID. Re-adding a content part will replace the old one. The index will not be changed by this operation.</p>
+<p>There are two types of content parts:</p>
+<ol>
+<li>Content parts which have additional metadata provided within the metadata of the content item. Such content parts are typically used to store transformed versions of the original content. This allows e.g. engines which can only process plain text versions to query for the content part containing this version of the passed document.</li>
+<li>Content parts that are registered under a predefined URI. Such content parts are typically not mentioned within the metadata of the content item. This is used to share intermediate enhancement results between enhancement engines. An example would be tokens, sentences, POS tags and chunks that are extracted by some NLP engine. Engines which want to consume such data need to know the predefined URI of the content part holding this data. They will check within the <code>canEnhance(..)</code> method if a content part with an expected URI is present and if it has the correct type. </li>
+</ol>
+<h3 id="accessing-the-main-content-of-the-contentitem">Accessing the main content of the ContentItem</h3>
+<p>The main content of the ContentItem refers to the content passed by the enhancement request (or downloaded from the URL provided by a request). For accessing this content the following methods are available</p>
+<div class="codehilite"><pre><span class="cm">/** Getter for the InputStream of the content as passed</span>
+<span class="cm"> for the ContentItem */</span>
+<span class="o">+</span> <span class="n">getStream</span><span class="o">()</span> <span class="o">:</span> <span class="n">InputStream</span>
+<span class="cm">/** Getter for the mime type of the content */</span>
+<span class="o">+</span> <span class="n">getMimeType</span><span class="o">()</span> <span class="o">:</span> <span class="n">String</span>
+<span class="cm">/** Getted for the Content as Blob */</span>
+<span class="o">+</span> <span class="n">getBlob</span><span class="o">()</span> <span class="o">:</span> <span class="n">Blob</span>
+</pre></div>
+
+
+<p>The <code>getStream()</code> and <code>getMimeType()</code> methods are shortcuts for the according methods of the content item's blob object. Calling <code>contentItem.getBlob.getStream()</code> will return an InputStream over the exact same content as directly calling <code>getStream()</code> on the content item. <em>Note that the blob interface also provides a <code>getParameter()</code> method which allows to retrieve mime-type parameters such as the charset of textual content.</em></p>
+<p>The content passed by the user is stored as content part at the index '0' with the URI of the content item in the form of a blob. Therefore, calling</p>
+<div class="codehilite"><pre><span class="n">contentItem</span><span class="o">.</span><span class="na">getPart</span><span class="o">(</span><span class="mi">0</span><span class="o">,</span><span class="n">Blob</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="n">contentItem</span><span class="o">.</span><span class="na">getPart</span><span class="o">(</span><span class="n">contentItem</span><span class="o">.</span><span class="na">getUri</span><span class="o">(),</span><span class="n">Blob</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="n">contentItem</span><span class="o">.</span><span class="na">getBlob</span><span class="o">()</span>
+</pre></div>
+
+
+<p>returns the same blob instance.</p>
+<h3 id="metadata-of-the-contentitem">Metadata of the ContentItem</h3>
+<p>The metadata of the ContentItem is managed by a lockable MGraph. This is basically a normal <code>java.util.Collections</code> for triples. The only RDF specific method is the support for filtered iterators which support wildcards for subjects, predicates and objects.</p>
+<p>This graph is used to store all <a href="enhancementstructure.html">enhancement results</a> as well as metadata about the content item (such as content parts) and the enhancement process (see <a href="executionmetadata.html">execution metadata</a>).</p>
+<h3 id="readwrite-locks">Read/Write locks</h3>
+<p>During the Apache Stanbol enhancement process as executed by the <a href="enhancementjobmanager.html">enhancement job manager</a> components running in multiple threads need to access the state of the <em>ContentItem</em>. Because of that the content item provides the possibility to acquire locks.</p>
+<div class="codehilite"><pre><span class="cm">/** Getter for the ReadWirteLock of a ContentItem */</span>
+<span class="o">+</span> <span class="n">getLock</span><span class="o">()</span> <span class="o">:</span> <span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">concurrent</span><span class="o">.</span><span class="na">ReadWriteLock</span>
+</pre></div>
+
+
+<p>Note also that</p>
+<div class="codehilite"><pre><span class="n">contentItem</span><span class="o">.</span><span class="na">getLock</span><span class="o">()</span>
+<span class="n">contentItem</span><span class="o">.</span><span class="na">getMetadata</span><span class="o">().</span><span class="na">getLock</span><span class="o">()</span>
+</pre></div>
+
+
+<p>will return the same <code>ReadWriteLock</code> instance.</p>
+<p>This lock can be used to request read/write locks on the content item. All methods of the content item and also the <code>MGraph</code> holding the metadata need to be protected by using the lock. This means that users which do not need to protect whole sections of code do not need to bother with the usage of locks. Typical examples are working with content parts, final classes like <code>Blob</code> or adding/removing a triple from the metadata.</p>
+<p>However, whenever components need to ensure that the data are not changed by other threads while performing some calculations read/write locks <em>must be</em> used. A typical example are iterations over data returned by the MGraph. In this case code iterating over the results should be protected against concurrent changes by</p>
+<div class="codehilite"><pre><span class="n">contentItem</span><span class="o">.</span><span class="na">getLock</span><span class="o">().</span><span class="na">readLock</span><span class="o">().</span><span class="na">lock</span><span class="o">();</span>
+<span class="k">try</span> <span class="o">{</span>
+ <span class="n">Iterator</span><span class="o"><</span><span class="n">Triple</span><span class="o">></span> <span class="n">it</span> <span class="o">=</span> <span class="n">contentItem</span><span class="o">.</span><span class="na">getMetadata</span><span class="o">().</span>
+ <span class="n">filter</span><span class="o">(</span><span class="kc">null</span><span class="o">,</span><span class="n">RDF</span><span class="o">.</span><span class="na">TYPE</span><span class="o">,</span><span class="n">TechnicalClasses</span><span class="o">.</span><span class="na">ENHANCER_TEXTANNOTATION</span><span class="o">);</span>
+ <span class="k">while</span><span class="o">(</span><span class="n">it</span><span class="o">.</span><span class="na">hasNext</span><span class="o">()){</span>
+ <span class="n">log</span><span class="o">.</span><span class="na">debug</span><span class="o">(</span><span class="err">"</span><span class="n">Process</span> <span class="nl">TextAnnotation:</span> <span class="o">{},</span><span class="n">it</span><span class="o">.</span><span class="na">next</span><span class="o">().</span><span class="na">getSubject</span><span class="o">());</span>
+ <span class="c1">//read the needed information</span>
+ <span class="o">}</span>
+<span class="o">}</span> <span class="k">finally</span> <span class="o">{</span>
+ <span class="n">contentItem</span><span class="o">.</span><span class="na">getLock</span><span class="o">().</span><span class="na">readLock</span><span class="o">().</span><span class="na">unlock</span><span class="o">()</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>While accessing content items within an <a href="engines">enhancement engine</a> there is an exception to this rule. If an engine declares that it only supports the <code>SYNCHRONOUS</code> enhancement mode, then the <a href="enhancementjobmanager.html">enhancement job manager</a> needs to take care that an engine has exclusive access to the <em>CotentItem</em>. In this case implementors of enhancement engines need not to care about using read/write locks.</p>
+<h3 id="contentitemfactory">ContentItemFactory</h3>
+<p>Since version 0.10.0 ContentItems and Blobs are created by using the <a href="contentitemfactory.html">ContentItemFactory</a>. ContentItemFactory implementation register themselves as OSGI service. By default the implementation with the highest "service.ranking" is used by the StanbolEnhancer to create instances. By default two implementations are available. The in-memory and a file-based one where the in-memory implementation is used as default.</p>
+<p>Most users will not need to change the default ContentItem implementation. However if the Enhancer is used to extract metadata from gib media files such as EXIF metadata from big images, ID3 from MP3 files ... than changing the default from the InMemoryContentItemFactory to the FileContentItemFactory might considerable reduce the memory footprint. </p>
+<p>With the introduction of the ContentItemFactory also all ContentItem implementation specific constructors to parse content where deprecated and replaced by the following three interfaces:</p>
+<ol>
+<li><strong>ContentSource</strong> allows to parse Content that is available as stream, byte array or string.</li>
+<li><strong>ContentReference</strong> allows to parse a Reference (e.g. a URL) to a ContentItem. The derefernce() method of this interface is used by the ContentItemFactory to convert a ContentReference to a ContentSource.</li>
+<li><strong>ContentSink</strong> allows to obtain an OutputStream to an initially empty Blob that can later be used to stream the content. This is intended to be used by EnhancementEngine that need to convert content from one format to an other because it allows to avoid caching the converted content in-memory.</li>
+</ol>
+<h3 id="multipart-mime-serialization">Multipart MIME serialization</h3>
+<p><span style="float:right"> <img alt="ContentItem Multipart MIME format" src="contentitemmultipartmime.png" title="This figure provides an overview how Content Items are serialized as MultiPart MIME" /></span></p>
+<p>Stanbol supports the serialization of content items as multipart MIME. This serialization is used by the RESTful API of the Stanbol Enhancer. This section provides details about how content items are represented using multipart MIME. For more information on how to send/receive multipart content items via the RESTful Services provided by the Stanbol Enhancer please see the documentation provided in the web interface (e.g. at http://localhost:8080/enhancer).</p>
+<p>The following figure provides an overview on how ContentItems are represented using MultiPart MIME.</p>
+<p><strong>ContentItem Container</strong></p>
+<ul>
+<li>ContentItems are contained within a "multipart/form-data" container</li>
+<li>Apache Stanbol uses "ContentItem" as "boundary", but users may use any other as long as the "boundary" parameter in the "Content-Type" header is set correctly.</li>
+<li>Stanbol uses UTF-8 as charset, but users might use any supported encoding as long as the "charset" parameter in the "Content-Type" header is set accordingly.</li>
+</ul>
+<p>The default Content-Type for serialized ContentItems is therefore "multipart/form-data; boundary=contentItem; charset=UTF-8"</p>
+<p><strong>Enhancement Metadata</strong></p>
+<ul>
+<li>If present this MUST BE the first MIME part within the "multipart/form-data" container representing the ContentItem.</li>
+<li>The "name" parameter of the "Content-Disposition" header MUST BE "metadata"</li>
+<li>If the "fileName" parameter of the "Content-Disposition" header is present it MUST BE the URI of the ContentItem. Users are typically required to set this header in case they want to parse existing metadata with enhancement requests. This is because is such cases it is important that the URI of the ContentItem created by the Stanbol Enhancer is equal to the URI used to describe the Content within the passed Metadata. The Stanbol Enhancer MUST set to "fileName" parameter of the metadata to the URI of the processed ContentItem.</li>
+<li>The "Content-Type" of the metadata can be any RDF serialization supported by Apache Stanbol. UTF-8 is used as default charset.</li>
+<li>The RDF data serialized in this MIME part represent the enhancement results.</li>
+</ul>
+<p><strong>Content</strong></p>
+<ul>
+<li>If present the MIME part representing the Content MUST directly follow the Metadata. If the Metadata are not present the Content MUST BE the first MIME part within the "multipart/form-data" container representing the ContentItem.</li>
+<li>Because multiple content variants can be included within a ContentItem a "multipart/alternate" container is used to represent the content.</li>
+<li>The "name" parameter of the "Content-Disposition" header MUST BE "content". The "fileName" parameter is not used and therefore not present/ignored. The Stanbol Enhancer uses "contentParts" as boundary but users may use any boundary as long as it is correctly set within the "Content-Type" header.</li>
+</ul>
+<p>The various content elements are contained within the "multipart/form-data" container. The ordering is important. For serialized ContentItems it is assumed that the first element is the original document for the ConentItem. All further MIME parts are considered alternate - e.g. transcoded/transformed - versions. For serialized ContentItems provided as response to requests to the Stanbol Enhancer the ordering of the MIME parts is the same as the indexes of the ContentParts in the ContentItem.</p>
+<ul>
+<li>the "name" parameter of the "Content-Disposition" is set to the URI of the ContentPart in the ContentItem.</li>
+<li>the "Content-Type" header must correspond to the media type of the content</li>
+</ul>
+<p>Note that users which want to send a single ContentPart AND Metadata to the Stanbol Enhancer can also directly add the content to the "multipart/form-data" container of the ContentItem. In this case the "name" parameter MUST BE still set to "content" but the "Content-Type" header needs to be directly set to the media type of the passed ContentPart. The Stanbol Enhancer does NOT use this option when serializing ContentItems. It will ALWAYS use a "multipart/alternate" container for the "content" even when only a single ContentPart is included in an Response.</p>
+<p><strong>Additional Metadata</strong></p>
+<p>The <a href="#content_parts">ContentPart API</a> of the Stanbol ContentItem allows to register content parts of any type. The MultiPart MIME serialization of ContentItems supports the serialization of such additional parts as long as they are encoded as RDF graphs (compatible to the Clerezza TripleCollection class). Additional ContentParts which are not encoded as RDF data are currently not supported by the Multipart MIME serialization.</p>
+<ul>
+<li>MimeParts representing such ContentParts MUST BE added after the MIME parts for the "metadata" AND the "content"</li>
+<li>The "name" parameter of the "Content-Disposition" MUST BE set to the URI of the ContentPart in the ContentItem.</li>
+<li>the "Content-Type" header must correspond to the media type of the content. The Stanbol Enhancer will always use the same RDF serialization as for the "metadata" when serializing additional Metadata. Users are free to use any supported serialization as long as they set the "Content-Type" header accordingly.</li>
+<li>The ordering of parts representing additional Metadata is the same as the ordering (index) of the ContentParts in the ContentItem.</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>