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">
