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 2014/05/23 09:15:27 UTC
svn commit: r909687 - in /websites/staging/stanbol/trunk/content: ./
docs/trunk/components/enhancer/engines/dereference.html
docs/trunk/components/enhancer/engines/entityhubdereference.html
docs/trunk/components/enhancer/enhancementproperties.html
Author: buildbot
Date: Fri May 23 07:15:27 2014
New Revision: 909687
Log:
Staging update by buildbot for stanbol
Modified:
websites/staging/stanbol/trunk/content/ (props changed)
websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/engines/dereference.html
websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/engines/entityhubdereference.html
websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/enhancementproperties.html
Propchange: websites/staging/stanbol/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri May 23 07:15:27 2014
@@ -1 +1 @@
-1596858
+1597019
Modified: websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/engines/dereference.html
==============================================================================
--- websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/engines/dereference.html (original)
+++ websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/engines/dereference.html Fri May 23 07:15:27 2014
@@ -97,9 +97,17 @@ referenced by the Enhancement Results an
<li><strong>Language</strong> (optional): The language detected for the text may be used to determine the set of languages of literals to be dereferenced.</li>
</ul>
<h2 id="design">Design</h2>
-<p>The Entity Dereference Engine can not directly be used to dereference Entities. It provides the infrastructure to implement actual dereference
-Engines for different technologies and services such as the <a href="entityhubdereference">Entityhub Dereference Engine</a> for dereferencing Entities via the <a href="/docs/trunk/components/entityhub/">Stanbol Entityhub</a>).</p>
-<p>The engine is defined by the <code>org.apache.stanbol:org.apache.stanbol.enhancer.dereference.core</code> module and defines the following two main components:</p>
+<p>The Entity Dereference Engine can not directly be used to dereference Entities. It provides the base functionality for the implementation of dereference Engines for different technologies and services. One such implementation is the <a href="entityhubdereference">Entityhub Dereference Engine</a> for dereferencing Entities via the <a href="/docs/trunk/components/entityhub/">Stanbol Entityhub</a>).</p>
+<p>The module providing this infrastructure is </p>
+<div class="codehilite"><pre><span class="nt"><dependency></span>
+ <span class="nt"><groupId></span>org.apache.stanbol<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>org.apache.stanbol.enhancer.dereference.core<span class="nt"></artifactId></span>
+ <span class="nt"><version></span>${stanbol-version}<span class="nt"></version></span>
+<span class="nt"></depednecy></span>
+</pre></div>
+
+
+<p>This module provides the following main components:</p>
<ol>
<li><a href="index">EnhancementEngine</a> implementation that<ul>
<li>processes the Enhancement results and schedules Entities to be dereferenced.</li>
@@ -107,23 +115,25 @@ Engines for different technologies and s
<li>supports <a href="../enhancementproperties">EnhancementProperties</a> for <em>chain</em> and <em>request</em> scoped configuration of the dereferenced information.</li>
</ul>
</li>
-<li>Definition of the <code>EntityDerefernece</code> interface used to dereference scheduled entities. This interface needs to be implemented by Dereference Engines for different technologies/services (e.g. the Entityhub)</li>
+<li>Definition of the <code>EntityDerefernecer</code> interface used to dereference scheduled entities. This interface needs to be implemented by Dereference Engines for different technologies/services (e.g. the Entityhub)</li>
</ol>
+<p>In addition the module also provides utilities for managing the enhancement engine configuration as well as parsed Enhancement Properties.</p>
<h2 id="configuration">Configuration</h2>
<p>The following Configuration parameter are defined by the core Entity Dereference Engine. Actual Dereference Engine implementations might not support all of them.</p>
<ul>
<li><strong>Name</strong> <em>(stanbol.enhancer.engine.name)</em>: The name of the Enhancement engine</li>
-<li><strong>URI Prefix</strong> <em>(enhancer.engines.dereference.uriPrefix)</em>: Allows to configure a simple prefix of Entities that can be dereferenced by this engine. If present only Entities referenced in the Enhancement Metadata matching at least one of the configured prefixes (or one of the configured URI Patterns) will be scheduled for dereferencing.</li>
-<li><strong>URI Pattern</strong> <em>(enhancer.engines.dereference.uriPatter)</em>: Allows to configure a regex pattern for matching Entity URIs. If present only Entities matching at lease one of the configured regex patterns ((or one of the configured URI Prefixes) will be scheduled for dereferencing.</li>
-<li><strong>Fallback Mode</strong> <em>(enhancer.engines.dereference.fallback)</em>: If enabled the EnhancementEngine ordering will get adapted in a way that in case a <a href="../chains/weightedchain">Weighted Chain</a> is use this Dereference Engine will get called after other with this option deactivated. In addition only Entities with no dereferenced data will get scheduled for dereferencing. This option is only useful in cases where multiple dereference engines are used in the same enhancement chain. It allows to ensure the following workflows<ol>
-<li>First running Dereference Engines for fast/local data sources. Especially those where one can configure an <em>URI Prefix</em> and/or an <em>URI Pattern</em>. Second running Dereference Engines for datastes that require remote service calls or for those no <em>URI Prefix</em> nor <em>URI Pattern</em> can be configured. This can be achieved by deactivating <em>Fallback Mode</em> for the first group and activating it for the second.</li>
-<li>Dereference Entities from slow/remote data sources: E.g. when using a partial local cache of a knowledge base one can configure a Dereference Engine with deactivated <em>Fallback Mode</em> for the local cache and an other for the remote datasource with activated <em>Fallback Mode</em>. This setting ensures that only Entities not available in the local cache are requested from the remote service.</li>
+<li><strong>URI Prefix</strong> <em>(enhancer.engines.dereference.uriPrefix)</em>: Allows to configure [0..*] prefixes of Entity URIs that can be dereferenced by this engine. If present only Entities that match one of those prefixes are scheduled to be dereferenced by the <code>EntityDereferencer</code>.</li>
+<li><strong>URI Pattern</strong> <em>(enhancer.engines.dereference.uriPatter)</em>: Allows to configure a regex pattern for matching Entity URIs. If present only Entities matching at lease one of the configured patterns will be scheduled for dereferencing.</li>
+<li><strong>Fallback Mode</strong> <em>(enhancer.engines.dereference.fallback)</em>: The fallback mode will only schedule Entities for dereferencing if no data for them are yet present in the Enhancement results. In case a <a href="../chains/weightedchain">Weighted Chain</a> is use this mode will also make sure that Dereference Engines in <em>Fallback Mode</em> will be executed after those with this mode deactivated.
+ This option is only useful in cases where multiple dereference engines are used in the same enhancement chain. It allows to ensure the following workflows<ol>
+<li>First running Dereference Engines for fast/local data sources. Especially those where one can configure an <em>URI Prefix</em> and/or an <em>URI Pattern</em> - by deactivating <em>Fallback Mode</em>. Second running Dereference Engines for datastes that require remote service calls or for those no <em>URI Prefix</em> nor <em>URI Pattern</em> can be configured - by activating <em>Fallback Mode</em>. This can greatly improve performance and reduce the number of remote service calls as already dereferenced Entities will not get scheduled to be dereferenced by using the remote service.</li>
+<li>In settings where a partial local cache for an otherwise slow data source exists. In this case one can configure two Entity Dereference Engines for the same data source. First one with <em>Fallback Mode</em> deactivated for the partial cache and a second with enabled <em>Fallback Mode</em> for the original but slower datasource.</li>
</ol>
</li>
-<li><strong>Dereference only Content Language Literals</strong> <em>(enhancer.engine.dereference.filterContentlanguages)</em>: If enabled only Literals with the same language as the language detected for the Content will get dereferenced. Literals with no language tag will always get dereferenced.</li>
<li><strong>Dereference Languages</strong> <em>(enhancer.engines.dereference.languages)</em>: A set of languages that are dereferenced. Even if <em>'Dereference only Content Language Literals'</em> is active explicitly configured languages will still get dereferenced. If not present and <em>'Dereference only Content Language Literals'</em> is deactivated literals of any language will get dereferenced.</li>
-<li><strong>Dereferenced Fields</strong> <em>(enhancer.engines.dereference.fields)</em>: The dereferenced fields - in RDF terminology 'properties' - to be dereferenced. Typically QNames (e.g. <code>rdf:label</code>) can be used for the configuration. However support for QNames is optional. Some Implementations might also support wildcards and exclusions. </li>
-<li><strong>Dereference LD Path</strong> <em>(enhancer.engines.dereference.ldpath)</em>: The <a href="http://marmotta.apache.org/ldpath/language.html">LD Path Language</a> allows to define powerful selectors for dereferenced Entities. </li>
+<li><strong>Dereference only Content Language Literals</strong> <em>(enhancer.engine.dereference.filterContentlanguages)</em>: If enabled only Literals with the same language as the language detected for the Content will get dereferenced. Literals with no language tag will always get dereferenced.</li>
+<li><strong>Dereferenced Fields</strong> <em>(enhancer.engines.dereference.fields)</em>: The dereferenced fields - in RDF terminology 'properties' - to be dereferenced. Typically QNames (e.g. <code>rdf:label</code>) can be used for the configuration. However support for QNames is optional. Some Implementations might also support wildcards and exclusions.</li>
+<li><strong>Dereference LD Path</strong> <em>(enhancer.engines.dereference.ldpath)</em>: The <a href="http://marmotta.apache.org/ldpath/language.html">LD Path Language</a> allows to define powerful selectors for dereferenced Entities. As an example LDPath allows to select different properties based on the type of the dereferenced entity.</li>
<li><strong>Service Ranking</strong> <em>(service.ranking)</em>: The OSGI service ranking. Will only have an effect if their are two engines with the same name. In such cases the one with the higher service ranking will get called.</li>
</ul>
<p><em>NOTE</em> that the configurations for <em>Dereference Languages</em>, <em>Dereferenced Fields</em> and <em>Dereference LD Path</em> are just managed by the Core Entity Dereference Engine implementation. Actual support for such properties will depend on the actual <code>EntityDereferencer</code> implementation.</p>
@@ -140,9 +150,10 @@ Engines for different technologies and s
</pre></div>
-<p><code>supportsOfflineMode</code> need to return <code>true</code> if the implementation does not need to access a remote service for dereferencing entities and <code>false</code> if it requires remote services. Stanbol can be started with an option that enforces <em>Offline Mode</em>. In this case EntityDereferencers that do not support this mode will be deactivated.</p>
-<p>The <code>ExecutorService</code> is used by the <code>EntityDereferenceEngine</code> to concurrently dereference entities. This means that the <code>dereference(..)</code> method of the <code>EntityDereferencer</code> implementations will be called in the contexts of threads provided by the returned <code>ExecutorService</code>. Returning <code>null</code> will deactivate this feature. However note that still multiple threads will be used to call the <code>dereference(..)</code> method. Meaning that the implementation MUST BE thread save.</p>
-<p>The <code>dereference(..)</code> method is used to dereference the Entity with the parsed <code>UriRef</code>. Dereferenced information are expected to be written in the parsed <code>MGraph</code>. While writing a write lock MUST BE acquired. The <code>DereferenceContext</code> provides the configuration (see the following section for more information). If the parsed entity was successfully dereferenced this method is expected to return <code>true</code>. Otherwise <code>false</code>.</p>
+<p><code>supportsOfflineMode</code> need to return <code>true</code> if the implementation does not need to access a remote service for dereferencing entities and <code>false</code> if it requires remote services. If Apache Stanbol is started with <em>Offline Mode</em> enabled <code>EntityDereferencer</code> implementation that do not support <em>Offline Mode</em> will not be called - meaning that no Entities will get dereferenced from services that do require an internet connection.</p>
+<p>The <code>ExecutorService</code> is used by the <code>EntityDereferenceEngine</code> to concurrently dereference entities. This means that the <code>dereference(..)</code> method of the <code>EntityDereferencer</code> implementations will be called in the contexts of threads provided by the returned <code>ExecutorService</code>. Returning <code>null</code> will deactivate this feature.</p>
+<p><strong>NOTE</strong> that all <code>EntityDereferencer</code> <strong>MUST BE</strong> thread save as multiple threads will be used to call the <code>dereference(..)</code> method. Even if <code>getExecutor()</code> returns <code>null</code> the EnhancementJobManager will still use multiple threads for calling the <code>EntityDereferenceEngine</code> - meaning that <code>dereference(..)</code> will be called with different thread contexts.</p>
+<p>The <code>dereference(..)</code> method is used to dereference the Entity with the parsed <code>UriRef</code>. Dereferenced information are expected to be written in the parsed <code>MGraph</code>. While writing dereferenced information to the parsed graph a write lock MUST BE acquired. The <code>DereferenceContext</code> provides the configuration (see the following section for more information). If the parsed entity was successfully dereferenced this method is expected to return <code>true</code>. Otherwise <code>false</code>.</p>
<h3 id="configuration-api">Configuration API</h3>
<p>Configuration Parameters supported by the Core Entity Dereference Engine implementation are defined in the <code>DereferenceConstants</code> class. </p>
<p>The <code>DereferenceEngineConfig</code> class provides an easy - API based - access to those configuration parameters. It is instantiated by using the <code>Dictionary</code> parsed by the OSGI as part of the <code>ComponentContext</code>.</p>
Modified: websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/engines/entityhubdereference.html
==============================================================================
--- websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/engines/entityhubdereference.html (original)
+++ websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/engines/entityhubdereference.html Fri May 23 07:15:27 2014
@@ -89,11 +89,11 @@
<ul> <li><a href="/">Home</a></li> <li class="item"><a href="/docs/">Docs</a></li> <li class="item"><a href="/docs/trunk/">Trunk</a></li> <li class="item"><a href="/docs/trunk/components/">Components</a></li> <li class="item"><a href="/docs/trunk/components/enhancer/">Enhancer</a></li> <li class="item"><a href="/docs/trunk/components/enhancer/engines/">Engines</a></li> </ul>
</div>
<h1 class="title">Entityhub Dereference Engine</h1>
- <p>This is a <a href="dereference">Entity Dereference Engine</a> for the <a href="/docs/trunk/components/entityhub">Stanbol Entityhub</a>. It supports dereferencing Entities from</p>
+ <p>This is an <a href="dereference">Entity Dereference Engine</a> for the <a href="/docs/trunk/components/entityhub">Stanbol Entityhub</a>. It supports dereferencing Entities from</p>
<ul>
-<li>Entityhub: locally managed Entities</li>
-<li>Managed and Referenced Sites</li>
-<li>SiteManager: Union view over all Managed and Referenced Sites</li>
+<li>Entityhub: locally managed Entities (the <code>/entityhub</code> endpoint)</li>
+<li>Managed and Referenced Sites (the <code>/entityhub/site/{site-name}</code> endpoints)</li>
+<li>SiteManager: Union view over all Managed and Referenced Sites (the <code>/entityhub/sites</code> endpoint)</li>
</ul>
<h2 id="configuration">Configuration</h2>
<p>The following figure shows the configuration dialog of the Entityhub Dereference Engine:</p>
@@ -102,13 +102,9 @@
<ul>
<li><strong>Name</strong> <em>(stanbol.enhancer.engine.name)</em>: The name of the Enhancement engine</li>
<li><strong>Site</strong> <em>(enhancer.engines.dereference.entityhub.siteId)</em>: The name of the Entityhub Site to be used for dereferencing. <code>*</code> will dereference against the SiteManager (union over all Referenced and Managed sites) and <code>entityhub</code> will use the entityhub itself for dereferencing.</li>
-<li><strong>Fallback Mode</strong> <em>(enhancer.engines.dereference.fallback)</em>: If enabled the EnhancementEngine ordering will get adapted in a way that in case a <a href="../chains/weightedchain">Weighted Chain</a> is use this Dereference Engine will get called after other with this option deactivated. In addition only Entities with no dereferenced data will get scheduled for dereferencing. This option is only useful in cases where multiple dereference engines are used in the same enhancement chain. It allows to ensure the following workflows<ol>
-<li>First running Dereference Engines for fast/local data sources. Especially those where one can configure an <em>URI Prefix</em> and/or an <em>URI Pattern</em>. Second running Dereference Engines for datastes that require remote service calls or for those no <em>URI Prefix</em> nor <em>URI Pattern</em> can be configured. This can be achieved by deactivating <em>Fallback Mode</em> for the first group and activating it for the second.</li>
-<li>Dereference Entities from slow/remote data sources: E.g. when using a partial local cache of a knowledge base one can configure a Dereference Engine with deactivated <em>Fallback Mode</em> for the local cache and an other for the remote datasource with activated <em>Fallback Mode</em>. This setting ensures that only Entities not available in the local cache are requested from the remote service.</li>
-</ol>
-</li>
-<li><strong>URI Prefix</strong> <em>(enhancer.engines.dereference.uriPrefix)</em>: Allows to configure a simple prefix of Entities that can be dereferenced by this engine. If present only Entities referenced in the Enhancement Metadata matching at least one of the configured prefixes (or one of the configured URI Patterns) will be scheduled for dereferencing.</li>
-<li><strong>URI Pattern</strong> <em>(enhancer.engines.dereference.uriPatter)</em>: Allows to configure a regex pattern for matching Entity URIs. If present only Entities matching at lease one of the configured regex patterns ((or one of the configured URI Prefixes) will be scheduled for dereferencing.</li>
+<li><strong>Fallback Mode</strong> <em>(enhancer.engines.dereference.fallback)</em>: The fallback mode will only schedule Entities for dereferencing if no data for them are yet present in the Enhancement results (see the documentation of the <a href="dereference">Entity Dereference Engine</a> for more information and possible usage scenarios).</li>
+<li><strong>URI Prefix</strong> <em>(enhancer.engines.dereference.uriPrefix)</em>: Allows to configure [0..*] prefixes of Entity URIs that can be dereferenced by this engine. If present only Entities that match one of those prefixes are scheduled to be dereferenced by the <code>EntityDereferencer</code>.</li>
+<li><strong>URI Pattern</strong> <em>(enhancer.engines.dereference.uriPatter)</em>: Allows to configure a regex pattern for matching Entity URIs. If present only Entities matching at lease one of the configured patterns will be scheduled for dereferencing.</li>
<li><strong>Dereference only Content Language Literals</strong> <em>(enhancer.engine.dereference.filterContentlanguages)</em>: If enabled only Literals with the same language as the language detected for the Content will get dereferenced. Literals with no language tag will always get dereferenced.</li>
<li><strong>Dereferenced Fields</strong> <em>(enhancer.engines.dereference.fields)</em>: The dereferenced fields - in RDF terminology 'properties' - to be dereferenced. QNames (e.g. <code>rdf:label</code>) can be used for the configuration. This Engine supports the use of FieldMappings for the configuration (see the according sub-section for details).</li>
<li><strong>Dereference LD Path</strong> <em>(enhancer.engines.dereference.ldpath)</em>: The <a href="http://marmotta.apache.org/ldpath/language.html">LD Path Language</a> allows to define powerful selectors for dereferenced Entities. </li>
@@ -125,6 +121,24 @@
<p><img alt="Shared Thread Pool Configuration" src="entityhub-dereference-engine-shared-threadpool-config.png" /></p>
<h3 id="field-mapping-support">Field Mapping Support</h3>
<p>The <em>enhancer.engines.dereference.fields</em> configuration does support the Entityhub Field Mapping language.</p>
+<p>FieldMappings do use the following syntax:</p>
+<div class="codehilite"><pre>[!]FieldPattern [| Filter] [> Mapping]
+</pre></div>
+
+
+<ul>
+<li>an optional Exclusion indicated by '!' as the first character of the mapping used to exclude fields that are matched by the pattern.</li>
+<li>the required <em>FieldPattern</em> supports the definition of prefixes such as <code>http://xmlns.com/foaf/0.1/*</code> or <code>foaf:*</code></li>
+<li>the optional <em>Filter</em> part allows to filter specific languages (e.g. <code>@=null;en;de;</code> will only dereference English and German literals as well as literals with no language tag), typed literals (e.g. <code>d=xsd:dateTime;xsd:date</code>) or URI values (e.g. <code>d=entityhub:ref</code>). Filters will also try to convert values to the parsed data type (e.g. <code>d=xsd:double</code> would convert <code>xsd:float</code> values to <code>xsd:doule</code>. Also string literals that can be parsed as double would be converted).</li>
+<li>an optional <em>Mapping</em> can be used to copy values to an other field (e.g. <code>foaf:name > schema:name</code> would copy all FOAF names to the schema.org name field)</li>
+</ul>
+<p><strong>NOTE</strong>: Field Mappings configured for the EntityhubDerefereceEngine are overridden by Field Mappings parsed as <a href="../enhancementproperties">Enhancement Properties</a>.</p>
+<h2 id="supported-enhancement-properties">Supported Enhancement Properties</h2>
+<p>The following Enhancement Properties are supported by the Entityhub Dereference Engine</p>
+<ul>
+<li><strong>Dereference Languages</strong> <em>(enhancer.engines.dereference.languages)</em>: A set of languages that are dereferenced. Even if <em>'Dereference only Content Language Literals'</em> is active explicitly configured languages will still get dereferenced. * <strong>Dereferenced Fields</strong> <em>(enhancer.engines.dereference.fields)</em>: The dereferenced fields - in RDF terminology 'properties' - to be dereferenced. QNames (e.g. <code>rdf:label</code>) can be used for the configuration. This Engine supports the use of FieldMappings for the configuration. Dereferenced Fields parsed as EnhancementProperty will override values configured for the Engine.</li>
+<li><strong>Dereference LD Path</strong> <em>(enhancer.engines.dereference.ldpath)</em>: The <a href="http://marmotta.apache.org/ldpath/language.html">LD Path Language</a> allows to define powerful selectors for dereferenced Entities. An LD Path program parsed as EnhancementProperty will be executed in addition to those configured for the engine.</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/enhancementproperties.html
==============================================================================
--- websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/enhancementproperties.html (original)
+++ websites/staging/stanbol/trunk/content/docs/trunk/components/enhancer/enhancementproperties.html Fri May 23 07:15:27 2014
@@ -95,36 +95,36 @@
<p>EnhancementProperties are defined as string keys similar to Java properties. To represent them in RDF the key is transformed to an URI by using the string key as local name and <code>http://stanbol.apache.org/ontology/enhancementproperties#</code> as namespace. The default namespace prefix for enhancement properties is <code>ehp</code>. </p>
<p>The String key of Enhancement Properties MUST start with <code>enhancer.</code> and SHOULD use the <code>enhancer.{level-1}.{level-2}.{property-name}</code> syntax. Properties are case sensitive and SHOULD only use lower case characters. The '-' char shall be used to make properties with multiple names easier to read. </p>
<p>Globally defined properties use '<code>enhancer.{property-name}</code>'. Enhancement Engine specific properties a possible shorted/simplified name of the engine should be used as <code>{level-1}</code>. Engine specific properties might also use <code>engines</code> as <code>{level-1}</code> and the name of the engine as <code>{level-2}</code>.</p>
-<p>Examples: <code>enhancer.max-suggestions</code> or <code>enhancer.min-confidence</code> are typical examples for globally defined Enhancement Properties. Properties defined by specific Enhancement Engines will look like <code>enhancer.entity-co-mention.adjust-existing-confidence</code> or <code>enhancer.engines.dereference.fields</code> (as defined by <a href="https://issues.apache.org/jira/browse/STANBOL-1287">STANBOL-1287</a>.</p>
+<p>Examples: <code>enhancer.max-suggestions</code> or <code>enhancer.min-confidence</code> are typical examples for globally defined Enhancement Properties. Properties defined by specific Enhancement Engines will look like <code>enhancer.entity-co-mention.adjust-existing-confidence</code> or <code>enhancer.engines.dereference.fields</code> (as defined by <a href="https://issues.apache.org/jira/browse/STANBOL-1287">STANBOL-1287</a>).</p>
<p>Enhancement Properties can also be defined as RDF datatype properties. This allows to specify the expected XSD data type of
expected values. </p>
-<div class="codehilite"><pre><span class="p">@</span><span class="n">prefix</span> <span class="n">ehp</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">stanbol</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">ontology</span><span class="o">/</span><span class="n">enhancementproperties</span>#<span class="o">></span>
+<div class="codehilite"><pre><span class="p">@</span><span class="n">prefix</span> <span class="n">ehp</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">stanbol</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">ontology</span><span class="o">/</span><span class="n">enhancementproperties</span>#<span class="o">></span> <span class="p">.</span>
-<span class="n">ehp</span><span class="p">:</span><span class="n">enhancer</span><span class="p">.</span><span class="n">max</span><span class="o">-</span><span class="n">suggestions</span> <span class="n">rdf</span><span class="p">:</span><span class="n">type</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">DatatypeProperty</span><span class="p">,</span>
- <span class="n">xsd</span><span class="p">:</span><span class="n">datatype</span> <span class="n">xsd</span><span class="p">:</span><span class="n">Integer</span><span class="p">;</span>
+<span class="n">ehp</span><span class="p">:</span><span class="n">enhancer</span><span class="p">.</span><span class="n">max</span><span class="o">-</span><span class="n">suggestions</span> <span class="n">a</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">DatatypeProperty</span> <span class="p">;</span>
+ <span class="n">xsd</span><span class="p">:</span><span class="n">datatype</span> <span class="n">xsd</span><span class="p">:</span><span class="n">Integer</span> <span class="p">.</span>
-<span class="n">ehp</span><span class="p">:</span><span class="n">enhancer</span><span class="p">.</span><span class="n">min</span><span class="o">-</span><span class="n">confidence</span> <span class="n">rdf</span><span class="p">:</span><span class="n">type</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">DatatypeProperty</span><span class="p">,</span>
- <span class="n">xsd</span><span class="p">:</span><span class="n">datatype</span> <span class="n">xsd</span><span class="p">:</span><span class="n">Double</span><span class="p">;</span>
+<span class="n">ehp</span><span class="p">:</span><span class="n">enhancer</span><span class="p">.</span><span class="n">min</span><span class="o">-</span><span class="n">confidence</span> <span class="n">a</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">DatatypeProperty</span> <span class="p">;</span>
+ <span class="n">xsd</span><span class="p">:</span><span class="n">datatype</span> <span class="n">xsd</span><span class="p">:</span><span class="n">Double</span> <span class="p">.</span>
-<span class="n">ehp</span><span class="p">:</span><span class="n">enhancer</span><span class="p">.</span><span class="n">entity</span><span class="o">-</span><span class="n">co</span><span class="o">-</span><span class="n">mention</span><span class="p">.</span><span class="n">adjust</span><span class="o">-</span><span class="n">existing</span><span class="o">-</span><span class="n">confidence</span> <span class="n">rdf</span><span class="p">:</span><span class="n">type</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">DatatypeProperty</span><span class="p">,</span>
- <span class="n">xsd</span><span class="p">:</span><span class="n">datatype</span> <span class="n">xsd</span><span class="p">:</span><span class="n">Double</span><span class="p">;</span>
+<span class="n">ehp</span><span class="p">:</span><span class="n">enhancer</span><span class="p">.</span><span class="n">entity</span><span class="o">-</span><span class="n">co</span><span class="o">-</span><span class="n">mention</span><span class="p">.</span><span class="n">adjust</span><span class="o">-</span><span class="n">existing</span><span class="o">-</span><span class="n">confidence</span> <span class="n">a</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">DatatypeProperty</span> <span class="p">;</span>
+ <span class="n">xsd</span><span class="p">:</span><span class="n">datatype</span> <span class="n">xsd</span><span class="p">:</span><span class="n">Double</span> <span class="p">.</span>
-<span class="n">ehp</span><span class="p">:</span><span class="n">enhancer</span><span class="p">.</span><span class="n">engines</span><span class="p">.</span><span class="n">dereference</span><span class="p">.</span><span class="n">fields</span> <span class="n">rdf</span><span class="p">:</span><span class="n">type</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">DatatypeProperty</span><span class="p">,</span>
- <span class="n">xsd</span><span class="p">:</span><span class="n">datatype</span> <span class="n">xsd</span><span class="p">:</span><span class="n">String</span><span class="p">;</span>
+<span class="n">ehp</span><span class="p">:</span><span class="n">enhancer</span><span class="p">.</span><span class="n">engines</span><span class="p">.</span><span class="n">dereference</span><span class="p">.</span><span class="n">fields</span> <span class="n">a</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">DatatypeProperty</span> <span class="p">;</span>
+ <span class="n">xsd</span><span class="p">:</span><span class="n">datatype</span> <span class="n">xsd</span><span class="p">:</span><span class="n">String</span> <span class="p">.</span>
</pre></div>
<p><em>NOTE</em> that the <a href="#java-interface">Java Interface</a> will parse enhancement properties as <code>Map<String,Object></code>. Regardless of the defined data type Enhancement Engines that support a property MUST support to parse values from string values (the lexical form of the RDF literal). Multiple values may be parsed as Java Collection or an Array.</p>
-<p>h2. Scopes</p>
+<h2 id="scopes">Scopes</h2>
<p>Enhancement Properties can be defined with the following scopes</p>
<ol>
-<li><strong>request and engine</strong>: Properties with this scope are applied for a single request and a specific <a href="engines">Enhancement Engine</a> part of the executed <a href="chains">Enhancement Chain</a>. They do have the highest priority and will therefore override any property with the same name defined with an different scope. </li>
+<li><strong>request and engine</strong>: Properties with this scope are applied for a single request and a specific <a href="engines">Enhancement Engine</a> part of the executed <a href="chains">Enhancement Chain</a>. They do have the highest priority and will therefore override properties defined with any of the below scopes. </li>
<li><strong>request</strong>: Properties valid for a single request that are parsed to every Enhancement Engine part of the executed Enhancement Chain.</li>
-<li><strong>chain and engine</strong>: Properties defined for a specific <a href="engines">Enhancement Engine</a> of an <a href="chains">Enhancement Chain</a>. This properties will get applied to all calls of the Enhancement Engine part of the execution of the Chain the property is defined for. </li>
-<li><strong>chain</strong>: Properties parsed to every Enhancement Engine called as part of the execution of the defined <a href="chains">Enhancement Chain</a>. Enhancement Properties of this scope do have the lowest priority and will be overridden by any property with the same key and one of the above scopes.</li>
+<li><strong>chain and engine</strong>: Properties defined for a specific <a href="engines">Enhancement Engine</a> of an <a href="chains">Enhancement Chain</a>. As all <em>chain</em> scoped properties, those get applied to all executions of that chain.</li>
+<li><strong>chain</strong>: Chain specific properties parsed to all Enhancement Engines of the <a href="chains">Enhancement Chain</a>. Enhancement Properties of this scope do have the lowest priority and will be overridden by any property with the same key and one of the above scopes.</li>
</ol>
-<p>Properties with a higher priority will override properties with an lower priority. Meaning if a property <code>enhancer.min-confidence=0.5</code> is defined on a <em>chain</em> scope it can be overridden by <code>enhancer.min-confidence=0.75</code> on a <strong>chain and engine</strong> scope. A single request might still override the value on a <strong>request</strong> or <strong>request and engine</strong> scope.</p>
-<p><strong>Chain</strong> and/or <strong>chain and engine</strong> scoped properties are configured with <a href="chains">Enhancement Chain</a> definition. <strong>Request</strong> and/or <strong>request and engine</strong> scoped properties can be specified as query parameter of the POST request or via the Java API by accessing the <em>Request Properties</em> content part. See the following sections for detailed information.</p>
+<p>Properties with a higher priority will override properties with an lower priority. Meaning if a property <code>enhancer.min-confidence=0.5</code> is defined on a <em>chain</em> scope it can be overridden by <code>enhancer.min-confidence=0.75</code> on a <em>chain and engine</em> scope. A single request might still override the value on a <em>request</em> or <em>request and engine</em> scope.</p>
+<p><em>Chain</em> and/or <em>chain and engine</em> scoped properties are configured with <a href="chains">Enhancement Chain</a> definition. <em>Request</em> and/or <em>request and engine</em> scoped properties can be specified as query parameter of the POST request or via the Java API by accessing the <em>Request Properties</em> content part. See the following sections for detailed information.</p>
<h2 id="using-enhancement-properties">Using Enhancement Properties</h2>
<p>Enhancement Properties are consumed by <a href="engine">Enhancement Engine</a>s. This section describes how implementors of engines can retrieve Enhancement Properties from the request - calls to the <code>computeEnhancements(..)</code> method.</p>
<p>In version <code>0.12.1</code> and <code>1.*</code> EnhancementProperties are contained in the <a href="contentitem">ContentItem</a> parsed to the EnhancementEngine. The <code>EnhancementEngineHeloer</code> utility has methods to access them. The following listing shows the code necessary to get the Enhancement Properties from the parsed ContentItem.</p>
@@ -145,8 +145,8 @@ expected values. </p>
</pre></div>
-<p>The <code>Map<String,Object></code> containing the EnhancementProperties is a read/write-able copy of the EnhancementProperties present in the ContentItem. That mean that EnhancementEngine implementations are free to change the contents of that map as those changes will not affect the state of the ContentItem.</p>
-<p>The keys of in the map are the string keys of the parsed Enhancement Properties (e.g. <code>enhancer.max-suggestion</code> or <code>enhancer.engines.dereference.fields</code>). Values can be any Object. Arrays and Collections may be used for multi value properties. The <code>EnhancementEngineHelper</code> utility provides methods to convert values. </p>
+<p>The <code>Map<String,Object></code> containing the EnhancementProperties is a read/write-able copy of the EnhancementProperties parsed with the ContentItem. That mean that EnhancementEngine implementations are free to change the contents of that map. Those changes will not affect the state of the ContentItem.</p>
+<p>The keys of in the map are the string keys of the parsed Enhancement Properties (e.g. <code>enhancer.max-suggestion</code> or <code>enhancer.engines.dereference.fields</code>). Values can be any Object. Arrays and Collections may be used for multi value properties. The <code>EnhancementEngineHelper</code> utility provides methods to convert values to expected. </p>
<div class="codehilite"><pre><span class="c1">//define supported enhancement properties as constants</span>
<span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="n">String</span> <span class="n">MAX_SUGGESTIONS</span> <span class="o">=</span> <span class="s">"enhancer.max-suggestions"</span><span class="o">;</span>
<span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="n">String</span> <span class="n">DEREFERENCED_FIELDS</span> <span class="o">=</span> <span class="s">"enhancer.engines.dereference.fields"</span><span class="o">;</span>
@@ -166,8 +166,8 @@ expected values. </p>
<p><em>TIP</em> the same methods can also be used to process the configuration parsed by OSGI.</p>
-<h2 id="definition-chain-scoped-enhancement-properties">Definition Chain scoped Enhancement Properties</h2>
-<p>Chain scoped EnhancementProperties are represented by RDF in the ExecutionPlan. As in <code>0.12.1</code> and <code>1.*</code> the ExecutionPlan is generated by the Enhancement Chain implementations needs to support the configuration.</p>
+<h2 id="definition-ofchain-scoped-enhancement-properties">Definition ofChain scoped Enhancement Properties</h2>
+<p>Chain scoped EnhancementProperties are represented by RDF in the ExecutionPlan. As in <code>0.12.1</code> and <code>1.*</code> the ExecutionPlan is provided by the <code>Chain#getExecutionPlan()</code> method most currently used Chain implementations where extended to support the the configuration of <em>chain</em> scoped Enhancement Properties.</p>
<p>Starting from <code>0.12.1</code> the <a href="chains/listchain">ListChain</a>, <a href="chains/weightedchain">WeightedChain</a> and <a href="chains/graphchain">GraphChain</a> allow the configuration of EnhancementProperties:</p>
<ul>
<li>
@@ -221,6 +221,10 @@ Java API.</p>
<p><em>Note</em> with the enhancer <code>2.0</code> the request properties content part will get removed and replaced by the EnhancementJob API (TBD). </p>
+<h2 id="enhancement-engine-support">Enhancement Engine Support</h2>
+<p>Enhancement Properties MUST BE supported by Enhancement Engine implementations.</p>
+<p><strong>NOTE:</strong> that the properties used in the different examples are NOT supported in with the <code>0.12.1</code> release. The definition of global enhancement properties and its support for the most commonly used enhancement engines is paned to be added before the <code>1.0.0</code> release. The epic <a href="https://issues.apache.org/jira/browse/STANBOL-1343">STANBOL-1343</a> tracks the progress. Please also note the documentation of <a href="engines/list">specific engines</a> for details about supported properties.</p>
+<p>The only engine that does already support Enhancement Properties with the <code>0.12.1</code> release is the <a href="engines/entityhubdereference">Entityhub Dereference Engine</a>.</p>
</div>
<div id="footer">