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/04/11 10:30:50 UTC
svn commit: r812318 [2/10] - in /websites/staging/stanbol/trunk/content: ./
stanbol/docs/0.9.0-incubating/ stanbol/docs/0.9.0-incubating/cmsadapter/
stanbol/docs/0.9.0-incubating/contenthub/
stanbol/docs/0.9.0-incubating/enhancer/ stanbol/docs/0.9.0-in...
Added: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/contenthub/index.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/contenthub/index.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/contenthub/index.html Wed Apr 11 08:30:47 2012
@@ -0,0 +1,126 @@
+<!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 - Contenthub (1 minute tutorial)</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="/stanbol/docs/trunk/downloads.html">Overview</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">Contenthub (1 minute tutorial)</h1>
+ <p>The Apache Stanbol Contenthub is an Apache Solr based document repository which enables
+storage of text-based documents and customizable semantic search facilities.
+Contenthub exposes an efficient Java API together with the corresponding RESTful services. </p>
+<p>Apache Stanbol comes with several launchers.
+If you build Stanbol from its source with the following command</p>
+<div class="codehilite"><pre><span class="n">mvn</span> <span class="n">clean</span> <span class="n">install</span>
+</pre></div>
+
+
+<p>You can find all launchers under the launchers directory. Contenthub is currently included in
+the full launcher of Apache Stanbol. That is, you can make use of Contenthub services if you
+run the full launcher. </p>
+<p>To run the full launcher of Apache Stanbol, go to the directory of full launcher and run the
+jar file under the target directory</p>
+<div class="codehilite"><pre><span class="n">cd</span> <span class="p">{</span><span class="n">stanbol</span><span class="p">}</span><span class="sr">/launchers/</span><span class="n">full</span>
+<span class="n">java</span> <span class="o">-</span><span class="n">Xmx1g</span> <span class="o">-</span><span class="n">jar</span> <span class="n">target</span><span class="o">/</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">stanbol</span><span class="o">.</span><span class="n">launchers</span><span class="o">.</span><span class="n">full</span><span class="o">-</span><span class="p">{</span><span class="n">snapshot</span><span class="o">-</span><span class="n">version</span><span class="p">}</span><span class="o">-</span><span class="n">incubating</span><span class="o">-</span><span class="n">SNAPSHOT</span><span class="o">.</span><span class="n">jar</span>
+</pre></div>
+
+
+<p>Your Stanbol instance is running under {stanbol}/launchers/full/sling and Contenthub is accessible at</p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="o">/</span><span class="n">contenthub</span>
+</pre></div>
+
+
+<p>Contenthub is divided into Store and Search subcomponents. The link above will be automatically redirected to </p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/contenthub/co</span><span class="n">ntenthub</span><span class="o">/</span><span class="n">store</span>
+</pre></div>
+
+
+<p>You can submit text content (sending in the payload of an HTTP POST request) with the following command</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">i</span> <span class="o">-</span><span class="n">X</span> <span class="n">POST</span> <span class="o">-</span><span class="n">H</span> <span class="s">"Content-Type:text/plain"</span> <span class="o">\</span>
+ <span class="o">--</span><span class="n">data</span> <span class="s">"I live in Istanbul."</span> <span class="o">\</span>
+ <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/contenthub/co</span><span class="n">ntenthub</span><span class="o">/</span><span class="n">store</span>
+</pre></div>
+
+
+<p>Contenthub provides different search interfaces. You can directly query the Solr backend as follows</p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/solr/</span><span class="n">default</span><span class="sr">/contenthub/s</span><span class="n">elect</span><span class="p">?</span><span class="sx">q=*:*</span>
+
+<span class="sx">http://localhost:8080/solr/default/contenthub/select?q=</span><span class="n">turkey</span>
+</pre></div>
+
+
+<p>You can obtain a Contenthub specific search result from the featured search service based on a keyword search. The results can be retrieved in JSON format as in the following command</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">i</span> <span class="o">-</span><span class="n">X</span> <span class="n">GET</span> <span class="o">-</span><span class="n">H</span> <span class="s">"Accept: application/json"</span> <span class="o">\</span>
+ <span class="o">-</span><span class="n">H</span> <span class="s">"Content-Type:text/plain"</span> <span class="o">\</span>
+ <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/contenthub/co</span><span class="n">ntenthub</span><span class="sr">/search/</span><span class="n">featured</span><span class="p">?</span><span class="n">queryTerm</span><span class="o">=</span><span class="n">turkey</span>
+</pre></div>
+
+
+<p>Featured search not only returns resulting documents, but also related keywords retrieved from various resources (if the resources are available within the running Stanbol instance)</p>
+<p><a href="contenthub5min">Here</a>, you can find a more detailed version (5 minutes tutorial) of the tutorial.</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/0.9.0-incubating/customvocabulary.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/customvocabulary.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/customvocabulary.html Wed Apr 11 08:30:47 2012
@@ -0,0 +1,161 @@
+<!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 - Using custom/local vocabularies with Apache Stanbol</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="/stanbol/docs/trunk/downloads.html">Overview</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">Using custom/local vocabularies with Apache Stanbol</h1>
+ <p>The ability to work with custom vocabularies is necessary for many organisations. Use cases range from being able to detect various types of named entities specific of a company or to detect and work with concepts from a specific domain.</p>
+<p>For text enhancement and linking to external sources, the Entityhub component of Apache Stanbol allows to work with local indexes of datasets for several reasons: </p>
+<ul>
+<li>do not want to rely on internet connectivity to these services, thus working offline with a huge set of entities</li>
+<li>want to manage local updates of these public repositories and </li>
+<li>want to work with local resources only, such as your LDAP directory or a specific and private enterprise vocabulary of a specific domain.</li>
+</ul>
+<p>Creating your custom indexes the preferred way of working with custom vocabularies. For small vocabularies, with Entithub one can also upload simple ontologies together instance data directly to the Entityhub and manage them - but as a major downside to this approach, one can only manage one ontology per installation.</p>
+<p>This document focuses on the main case: Creating and using a local SOLr indexes of a custom vocabularies e.g. a SKOS thesaurus or taxonomy of your domain.</p>
+<h2 id="creating-and-working-with-custom-local-indexes">Creating and working with custom local indexes</h2>
+<p>Stanbol provides the machinery to start with vocabularies in standard languages such as <a href="http://www.w3.org/2004/02/skos/">SKOS - Simple Knowledge Organization Systems</a> or more general <a href="http://www.w3.org/TR/rdf-primer/">RDF</a> encoded data sets. The respective Stanbol components, which are needed for this functionality are the Entityhub for creating and managing the index and several <a href="enhancer/engines/list.html">Enhancement Engines</a> to make use of the indexes during the enhancement process.</p>
+<h3 id="a-create-your-own-index">A. Create your own index</h3>
+<p><strong>Step 1 : Create the indexing tool</strong></p>
+<p>The indexing tool provides a default configuration for creating a SOLr index of RDF files (e.g. a SKOS export of a thesaurus or a set of foaf files).</p>
+<p>If not yet built during the Stanbol build process of the Entityhub call</p>
+<div class="codehilite"><pre><span class="n">mvn</span> <span class="n">install</span>
+</pre></div>
+
+
+<p>in the directory <code> {root}/entityhub/indexing/genericrdf/</code>and than</p>
+<div class="codehilite"><pre><span class="n">mvn</span> <span class="n">assembly:single</span>
+</pre></div>
+
+
+<p>Move the generated tool from</p>
+<div class="codehilite"><pre><span class="n">target</span><span class="o">/</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">stanbol</span><span class="o">.</span><span class="n">entityhub</span><span class="o">.</span><span class="n">indexing</span><span class="o">.</span><span class="n">genericrdf</span><span class="o">-*-</span><span class="n">jar</span><span class="o">-</span><span class="n">with</span><span class="o">-</span><span class="n">dependencies</span><span class="o">.</span><span class="n">jar</span>
+</pre></div>
+
+
+<p>into a custom directory, where you want to index your files.</p>
+<p><strong>Step 2 : Create the index</strong></p>
+<p>Initialize the tool with</p>
+<div class="codehilite"><pre><span class="n">java</span> <span class="o">-</span><span class="n">jar</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">stanbol</span><span class="o">.</span><span class="n">entityhub</span><span class="o">.</span><span class="n">indexing</span><span class="o">.</span><span class="n">genericrdf</span><span class="o">-*-</span><span class="n">jar</span><span class="o">-</span><span class="n">with</span><span class="o">-</span><span class="n">dependencies</span><span class="o">.</span><span class="n">jar</span> <span class="n">init</span>
+</pre></div>
+
+
+<p>You will get a directory with the default configuration files, one for the sources and a distribution directory for the resulting files. Make sure, that you adapt the default configuration with at least </p>
+<ul>
+<li>the id/name and license information of your data and </li>
+<li>namespaces and properties mapping you want to include to the index (see example of a <a href="examples/anl-mappings.txt">mappings.txt</a> including default and specific mappings for one dataset)</li>
+</ul>
+<p>Then, copy your source files into the respective directory <code>indexing/resources/rdfdata</code>. Several standard formats for RDF, multiple files and archives of them are supported. </p>
+<p><em>For more details of possible configurations, please consult the <a href="https://github.com/apache/stanbol/blob/trunk/entityhub/indexing/genericrdf/README.md">README</a>.</em></p>
+<p>Then, you can start the index by running</p>
+<div class="codehilite"><pre><span class="n">java</span> <span class="o">-</span><span class="n">Xmx1024m</span> <span class="o">-</span><span class="n">jar</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">stanbol</span><span class="o">.</span><span class="n">entityhub</span><span class="o">.</span><span class="n">indexing</span><span class="o">.</span><span class="n">dblp</span><span class="o">-*-</span><span class="n">jar</span><span class="o">-</span><span class="n">with</span><span class="o">-</span><span class="n">dependencies</span><span class="o">.</span><span class="n">jar</span> <span class="nb">index</span>
+</pre></div>
+
+
+<p>Depending on your hardware and on complexity and size of your sources, it may take several hours to built the index. As a result, you will get an archive of a <a href="http://lucene.apache.org/solr/">SOLr</a> index together with an OSGI bundle to work with the index in Stanbol.</p>
+<p><strong>Step 3 : Initialize the index within Stanbol</strong></p>
+<p>At your running Stanbol instance, copy the ZIP archive into <code>{root}/sling/datafiles</code>. Then, at the "Bundles" tab of the administration console add and start the <code>org.apache.stanbol.data.site.{name}-{version}.jar</code>.</p>
+<h3 id="b-configure-and-use-the-index-with-enhancement-engines">B. Configure and use the index with enhancement engines</h3>
+<p>Before you can make use of the custom vocabulary you need to decide, which kind of enhancements you want to support. If your enhancements are Named Entities in its strict sense (Persons, Locations, Organizations), then you may use the standard NER engine together with its EntityLinkingEngine to configure the destination of your links.</p>
+<p>In cases, where you want to match all kinds of named entities and concepts from your custom vocabulary, you should work with the <a href="enhancer/engines/keywordlinkingengine.html">KeywordLinkingEngine</a> to both, find occurrences and to link them to custom entities. In this case, you'll get only results, if there is a match, while in the case above, you even get entities, where you don't find exact links. This approach will have its advantages when you need to have a high recall rate on your custom entities.</p>
+<p>In the following the configuration options are described briefly.</p>
+<p><strong>Use the KeywordLinkingEngine only</strong></p>
+<p>(1) To make sure, that the enhancement process uses the KeywordLinkingEngine only, deactivate the "standard NLP" enhancement engines, especially the NamedEntityExtractionEnhancementEngine (NER) and the EntityLinkingEngine before to work with the TaxonomyLinkingEngine.</p>
+<p>(2) Open the configuration console at http://localhost:8080/system/console/configMgr and navigate to the KeywordLinkingEngine. Its main options are configurable via the UI.</p>
+<ul>
+<li>Referenced Site: {put the id/name of your index}</li>
+<li>Label Field: {the property to search for}</li>
+<li>Type Field: {types of matched entries} </li>
+<li>Redirect Field: {redirection links}</li>
+<li>Redirect Mode: {ignore, follow, add values}</li>
+<li>Min Token Length: {set minimal token length}</li>
+<li>Suggestions: {maximum number of suggestions}</li>
+<li>Languages: {languages to use}</li>
+</ul>
+<p><em>Full details on the engine and its configuration are available <a href="enhancer/engines/keywordlinkingengine.html">here</a>.</em></p>
+<p><strong>Use several instances of the KeywordLinkingEngine</strong></p>
+<p>To work at the same time with different instances of the KeywordLinkingEngine can be useful in cases, where you have two or more distinct custom vocabularies/indexes and/or if you want to combine your specific domain vocabulary with general purpose datasets such as dbpedia or others.</p>
+<p><strong>Use the KeywordLinkingEngine together with the NER engine and the EntityLinkingEngine</strong></p>
+<p>If your text corpus contains common entities and enterprise specific as well and you are interested getting enhancements for both, you may also use the KeywordLinkingEngine for your custom thesaurus and the NERengine together with the EntityLinkingEngine targeting at e.g. dbpedia at the same time. </p>
+<h2 id="examples">Examples</h2>
+<p>You can find guidance for the following indexers in the README files at <code>{root}/entityhub/indexing/{name-for-indexer}</code></p>
+<ul>
+<li><a href="http://dbpedia.org/">dbpedia</a> dataset (Wikipedia data)
+ For dbpedia, there is also a <a href="http://svn.apache.org/repos/asf/incubator/stanbol/trunk/entityhub/indexing/dbpedia/fetch_prepare.sh">script</a> available, which helps in generating your own dbpedia index.</li>
+<li><a href="http://www.geonames.org">geonames.org</a> dataset (geolocation data)</li>
+<li><a href="http://dblp.uni-trier.de/">DBLP</a> dataset (scientific bibliography data)</li>
+</ul>
+<h2 id="demos-and-resources">Demos and Resources</h2>
+<ul>
+<li>The full <a href="http://dev.iks-project.eu:8081/">demo</a> installation of Stanbol is configured to also work with an environmental thesaurus - if you test it with unstructured text from the domain, you should get enhancements with additional results for specific "concepts".</li>
+<li>Download custom test indexes and installer bundles for Stanbol from <a href="http://dev.iks-project.eu/downloads/stanbol-indices/">here</a> (e.g. for GEMET environmental thesaurus, or a big dbpedia index).</li>
+<li>A very concrete example using metadata from the Austrian National Library is described <a href="http://blog.iks-project.eu/using-custom-vocabularies-with-apache-stanbol/">here</a>.</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/0.9.0-incubating/downloads.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/downloads.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/downloads.html Wed Apr 11 08:30:47 2012
@@ -0,0 +1,76 @@
+<!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 - Downloads</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="/stanbol/docs/trunk/downloads.html">Overview</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">Downloads</h1>
+ <p>As there is no official release of Apache Stanbol so far, one needs to install and build the software from source. </p>
+<p>In the meantime, you may download and use pre-builts of Stanbol launchers served <a href="http://dev.iks-project.eu/downloads/stanbol-launchers/">here</a>.</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/0.9.0-incubating/enhancer/chains/chainmanager.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/chainmanager.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/chainmanager.html Wed Apr 11 08:30:47 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 - Chain Manager</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="/stanbol/docs/trunk/downloads.html">Overview</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">Chain Manager</h1>
+ <p>The ChainManager provides name based access to all active <a href="index.html">Enhancement Chains</a> and their ServiceReferences. This interface is typically used by components that need to lookup Chains based on their name. However the ChainsTracker implementation can also be used to track specific Chains.</p>
+<h2 id="chainmanager-interface">ChainManager interface</h2>
+<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="cm">/** Constant for the name of the DefaultChain */</span>
+<span class="n">DEFAULT_CHAIN_NAME</span> <span class="o">:</span> <span class="n">String</span>
+<span class="cm">/** Getter for all names with active Chains */</span>
+<span class="n">getActiveChainNames</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">/** Getter for the ServiceReference to the Chain </span>
+<span class="cm"> with a given name sorted by service ranking */</span>
+<span class="n">getReference</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">)</span> <span class="o">:</span> <span class="n">ServiceReference</span>
+<span class="cm">/** Getter for all ServiceReferences to Chains </span>
+<span class="cm"> with a given name */</span>
+<span class="n">getReferences</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">)</span>
+<span class="cm">/** Getter for the Chain with a given name */</span>
+<span class="o">+</span> <span class="n">getChain</span><span class="o">(</span><span class="n">Stirng</span> <span class="n">name</span><span class="o">)</span> <span class="o">:</span> <span class="n">Chain</span>
+<span class="cm">/** Getter for all Chains with a given name sorted </span>
+<span class="cm"> by service ranking */</span>
+<span class="o">+</span> <span class="n">getChains</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">)</span> <span class="o">:</span> <span class="n">List</span><span class="o"><</span><span class="n">Chain</span><span class="o">></span>
+<span class="cm">/** Getter for a Chain based on a service reference */</span>
+<span class="o">+</span> <span class="n">getChain</span><span class="o">(</span><span class="n">ServiceReference</span> <span class="n">ref</span><span class="o">)</span> <span class="o">:</span> <span class="n">Chain</span>
+<span class="cm">/** Checks if there is a chain for the given name */</span>
+<span class="o">+</span> <span class="n">isChain</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">)</span> <span class="o">:</span> <span class="kt">boolean</span>
+<span class="cm">/** Getter for the default chain */</span>
+<span class="o">+</span> <span class="n">getDefault</span><span class="o">()</span> <span class="o">:</span> <span class="n">Chain</span>
+</pre></div>
+
+
+<p>There are two implementations of this interface available:</p>
+<h3 id="chainmanager-service">ChainManager Service</h3>
+<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="nd">@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>
+<h3 id="chainstracker">ChainsTracker</h3>
+<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 this utility can directly react to changes of tracked chains.</p>
+<div class="codehilite"><pre><span class="c1">//track only "myChain" and "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="o">(</span>
+ <span class="n">context</span><span class="o">,</span> <span class="s">"myChain"</span><span class="o">,</span><span class="s">"otherChain"</span><span class="o">);</span>
+<span class="n">tracker</span><span class="o">.</span><span class="na">open</span><span class="o">();</span> <span class="c1">//start tracking</span>
+
+<span class="c1">//the tracker need to be closed if no longer needed</span>
+<span class="n">tracker</span><span class="o">.</span><span class="na">close</span><span class="o">()</span>
+<span class="n">tracker</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span>
+</pre></div>
+
+
+<p>For most users the ChainManager service is sufficient and preferable. Direct use of the ChainsTracker 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/0.9.0-incubating/enhancer/chains/defaultchain.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/defaultchain.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/defaultchain.html Wed Apr 11 08:30:47 2012
@@ -0,0 +1,95 @@
+<!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 - Default 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"/>
+</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="/stanbol/docs/trunk/downloads.html">Overview</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">Default Chain</h1>
+ <p>This implementation that keeps track of all currently active <a href="../engines">Enhancement Engines</a> and registers itself as a chain service with the "stanbol.enhancer.chain.name=default" and the service ranking of Integer.MIN_VALUE.</p>
+<p>This will cause this chain to be returned by the ChainManager.getDefault() method if users:</p>
+<ul>
+<li>do not deactivate this chain (see below)</li>
+<li>configure an other chain with the "stanbol.enhancer.chain.name=default" and a higher service ranking</li>
+</ul>
+<p>The Chain returned by ChainManager.getDefault() is the one used for requests that do not specify a chain. This are enhancement requests to the "/engines" and "/enhancer" endpoint.</p>
+<h2 id="configuration">Configuration</h2>
+<p>This chain can be enabled/disabled by using the "stanbol.enhancer.chain.default.enabled"</p>
+<p><img alt="DefaultChain Configuration" src="enhancer-defaultchain-config.png" title="Configuration options for the Default Chain" /></p>
+<p>This chain does not support the configuration of the name nor the service ranking. The name is fixed to "default" and the service ranking is Integer.MIN_VALUE</p>
+<p>Note that the DefaultChain does not actually implement the Chain interface, but only registers an instance of the AllActiveEnginesChain on activation.
+The implementation is part of the "org.apache.stanbol.enhancer.chain.allactive" module.</p>
+<h2 id="calculation-of-the-executionplan">Calculation of the ExecutionPlan</h2>
+<p>This chain considers all currently active <a href="../engines">Enhancement Engines</a>. The ExecutionPlan is calculated by using the value for 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 EnhancementJobMananger and the EnhancementEngine do support this feature.</li>
+</ul>
+<p>The DefaultChain ensures that the default behavior of the Stanbol Enhancer does not change after the introduction of EnhancementChains. This is because the WeightedJobManager as used previously followed exactly the same rules.</p>
+<p>However after the introduction of EnhancementChains users can now easily change the default behavior.</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/0.9.0-incubating/enhancer/chains/enhancer-defaultchain-config.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-defaultchain-config.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-graphchain-config.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-graphchain-config.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-listchain-config.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-listchain-config.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-weightedchain-allactive.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-weightedchain-allactive.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-weightedchain-config.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-weightedchain-config.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-weightedchain-optionalinactive.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-weightedchain-optionalinactive.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-weightedchain-requiredinactive.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/enhancer-weightedchain-requiredinactive.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/executionplan.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/executionplan.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/executionplan.html Wed Apr 11 08:30:47 2012
@@ -0,0 +1,166 @@
+<!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"/>
+</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="/stanbol/docs/trunk/downloads.html">Overview</a></li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Execution 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/0.9.0-incubating/enhancer/chains/executionplan.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/executionplan.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/graphchain.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/graphchain.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/graphchain.html Wed Apr 11 08:30:47 2012
@@ -0,0 +1,132 @@
+<!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"/>
+</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="/stanbol/docs/trunk/downloads.html">Overview</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">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/0.9.0-incubating/enhancer/chains/index.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/index.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/index.html Wed Apr 11 08:30:47 2012
@@ -0,0 +1,164 @@
+<!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="/stanbol/docs/trunk/downloads.html">Overview</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 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/0.9.0-incubating/enhancer/chains/listchain.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/listchain.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/0.9.0-incubating/enhancer/chains/listchain.html Wed Apr 11 08:30:47 2012
@@ -0,0 +1,96 @@
+<!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"/>
+</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="/stanbol/docs/trunk/downloads.html">Overview</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">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>