Author: rwesten
Date: Fri May 23 07:15:21 2014
New Revision: 1597019
URL: http://svn.apache.org/r1597019
Log:
STANBOL-488, STANBOL-336, STANBOL-1223, STANBOL-1165: improvements, corrections
and clarifications
Modified:
stanbol/site/trunk/content/docs/trunk/components/enhancer/engines/dereference.mdtext
stanbol/site/trunk/content/docs/trunk/components/enhancer/engines/entityhubdereference.mdtext
stanbol/site/trunk/content/docs/trunk/components/enhancer/enhancementproperties.mdtext
Modified:
stanbol/site/trunk/content/docs/trunk/components/enhancer/engines/dereference.mdtext
URL:
http://svn.apache.org/viewvc/stanbol/site/trunk/content/docs/trunk/components/enhancer/engines/dereference.mdtext?rev=1597019&r1=1597018&r2=1597019&view=diff
==============================================================================
---
stanbol/site/trunk/content/docs/trunk/components/enhancer/engines/dereference.mdtext
(original)
+++
stanbol/site/trunk/content/docs/trunk/components/enhancer/engines/dereference.mdtext
Fri May 23 07:15:21 2014
@@ -11,31 +11,42 @@ The Entity Dereference Engine consumes t
## Design
-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 [Entityhub
Dereference Engine](entityhubdereference) for dereferencing Entities via the
[Stanbol Entityhub](/docs/trunk/components/entityhub/)).
+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 [Entityhub Dereference Engine](entityhubdereference) for
dereferencing Entities via the [Stanbol
Entityhub](/docs/trunk/components/entityhub/)).
-The engine is defined by the
`org.apache.stanbol:org.apache.stanbol.enhancer.dereference.core` module and
defines the following two main components:
+The module providing this infrastructure is
+
+ :::xml
+ <dependency>
+ <groupId>org.apache.stanbol</groupId>
+ <artifactId>org.apache.stanbol.enhancer.dereference.core</artifactId>
+ <version>${stanbol-version}</version>
+ </depednecy>
+
+This module provides the following main components:
1. [EnhancementEngine](index) implementation that
* processes the Enhancement results and schedules Entities to be
dereferenced.
* supports the use of a thread pool to dereference multiple entities
concurrently.
* supports [EnhancementProperties](../enhancementproperties) for _chain_
and _request_ scoped configuration of the dereferenced information.
-2. Definition of the `EntityDerefernece` interface used to dereference
scheduled entities. This interface needs to be implemented by Dereference
Engines for different technologies/services (e.g. the Entityhub)
+2. Definition of the `EntityDerefernecer` interface used to dereference
scheduled entities. This interface needs to be implemented by Dereference
Engines for different technologies/services (e.g. the Entityhub)
+
+In addition the module also provides utilities for managing the enhancement
engine configuration as well as parsed Enhancement Properties.
## Configuration
The following Configuration parameter are defined by the core Entity
Dereference Engine. Actual Dereference Engine implementations might not support
all of them.
* __Name__ _(stanbol.enhancer.engine.name)_: The name of the Enhancement engine
-* __URI Prefix__ _(enhancer.engines.dereference.uriPrefix)_: 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.
-* __URI Pattern__ _(enhancer.engines.dereference.uriPatter)_: 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.
-* __Fallback Mode__ _(enhancer.engines.dereference.fallback)_: If enabled the
EnhancementEngine ordering will get adapted in a way that in case a [Weighted
Chain](../chains/weightedchain) 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
- 1. First running Dereference Engines for fast/local data sources.
Especially those where one can configure an _URI Prefix_ and/or an _URI
Pattern_. Second running Dereference Engines for datastes that require remote
service calls or for those no _URI Prefix_ nor _URI Pattern_ can be configured.
This can be achieved by deactivating _Fallback Mode_ for the first group and
activating it for the second.
- 2. 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 _Fallback Mode_ for the local cache and an other for the
remote datasource with activated _Fallback Mode_. This setting ensures that
only Entities not available in the local cache are requested from the remote
service.
-* __Dereference only Content Language Literals__
_(enhancer.engine.dereference.filterContentlanguages)_: 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.
+* __URI Prefix__ _(enhancer.engines.dereference.uriPrefix)_: 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 `EntityDereferencer`.
+* __URI Pattern__ _(enhancer.engines.dereference.uriPatter)_: 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.
+* __Fallback Mode__ _(enhancer.engines.dereference.fallback)_: The fallback
mode will only schedule Entities for dereferencing if no data for them are yet
present in the Enhancement results. In case a [Weighted
Chain](../chains/weightedchain) is use this mode will also make sure that
Dereference Engines in _Fallback Mode_ 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
+ 1. First running Dereference Engines for fast/local data sources.
Especially those where one can configure an _URI Prefix_ and/or an _URI
Pattern_ - by deactivating _Fallback Mode_. Second running Dereference Engines
for datastes that require remote service calls or for those no _URI Prefix_ nor
_URI Pattern_ can be configured - by activating _Fallback Mode_. 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.
+ 2. 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 _Fallback Mode_ deactivated for the
partial cache and a second with enabled _Fallback Mode_ for the original but
slower datasource.
* __Dereference Languages__ _(enhancer.engines.dereference.languages)_: A set
of languages that are dereferenced. Even if _'Dereference only Content Language
Literals'_ is active explicitly configured languages will still get
dereferenced. If not present and _'Dereference only Content Language Literals'_
is deactivated literals of any language will get dereferenced.
-* __Dereferenced Fields__ _(enhancer.engines.dereference.fields)_: The
dereferenced fields - in RDF terminology 'properties' - to be dereferenced.
Typically QNames (e.g. `rdf:label`) can be used for the configuration. However
support for QNames is optional. Some Implementations might also support
wildcards and exclusions.
-* __Dereference LD Path__ _(enhancer.engines.dereference.ldpath)_: The [LD
Path Language](http://marmotta.apache.org/ldpath/language.html) allows to
define powerful selectors for dereferenced Entities.
+* __Dereference only Content Language Literals__
_(enhancer.engine.dereference.filterContentlanguages)_: 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.
+* __Dereferenced Fields__ _(enhancer.engines.dereference.fields)_: The
dereferenced fields - in RDF terminology 'properties' - to be dereferenced.
Typically QNames (e.g. `rdf:label`) can be used for the configuration. However
support for QNames is optional. Some Implementations might also support
wildcards and exclusions.
+* __Dereference LD Path__ _(enhancer.engines.dereference.ldpath)_: The [LD
Path Language](http://marmotta.apache.org/ldpath/language.html) 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.
* __Service Ranking__ _(service.ranking)_: 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.
_NOTE_ that the configurations for _Dereference Languages_, _Dereferenced
Fields_ and _Dereference LD Path_ are just managed by the Core Entity
Dereference Engine implementation. Actual support for such properties will
depend on the actual `EntityDereferencer` implementation.
@@ -57,11 +68,13 @@ The following listing shows the signatur
+ boolean dereference(UriRef entity, MGraph graph, Lock writeLock,
DereferenceContext dereferenceContext) throws DereferenceException;
-`supportsOfflineMode` need to return `true` if the implementation does not
need to access a remote service for dereferencing entities and `false` if it
requires remote services. Stanbol can be started with an option that enforces
_Offline Mode_. In this case EntityDereferencers that do not support this mode
will be deactivated.
+`supportsOfflineMode` need to return `true` if the implementation does not
need to access a remote service for dereferencing entities and `false` if it
requires remote services. If Apache Stanbol is started with _Offline Mode_
enabled `EntityDereferencer` implementation that do not support _Offline Mode_
will not be called - meaning that no Entities will get dereferenced from
services that do require an internet connection.
+
+The `ExecutorService` is used by the `EntityDereferenceEngine` to concurrently
dereference entities. This means that the `dereference(..)` method of the
`EntityDereferencer` implementations will be called in the contexts of threads
provided by the returned `ExecutorService`. Returning `null` will deactivate
this feature.
-The `ExecutorService` is used by the `EntityDereferenceEngine` to concurrently
dereference entities. This means that the `dereference(..)` method of the
`EntityDereferencer` implementations will be called in the contexts of threads
provided by the returned `ExecutorService`. Returning `null` will deactivate
this feature. However note that still multiple threads will be used to call the
`dereference(..)` method. Meaning that the implementation MUST BE thread save.
+__NOTE__ that all `EntityDereferencer` __MUST BE__ thread save as multiple
threads will be used to call the `dereference(..)` method. Even if
`getExecutor()` returns `null` the EnhancementJobManager will still use
multiple threads for calling the `EntityDereferenceEngine` - meaning that
`dereference(..)` will be called with different thread contexts.
-The `dereference(..)` method is used to dereference the Entity with the parsed
`UriRef`. Dereferenced information are expected to be written in the parsed
`MGraph`. While writing a write lock MUST BE acquired. The `DereferenceContext`
provides the configuration (see the following section for more information). If
the parsed entity was successfully dereferenced this method is expected to
return `true`. Otherwise `false`.
+The `dereference(..)` method is used to dereference the Entity with the parsed
`UriRef`. Dereferenced information are expected to be written in the parsed
`MGraph`. While writing dereferenced information to the parsed graph a write
lock MUST BE acquired. The `DereferenceContext` provides the configuration (see
the following section for more information). If the parsed entity was
successfully dereferenced this method is expected to return `true`. Otherwise
`false`.
### Configuration API
Modified:
stanbol/site/trunk/content/docs/trunk/components/enhancer/engines/entityhubdereference.mdtext
URL:
http://svn.apache.org/viewvc/stanbol/site/trunk/content/docs/trunk/components/enhancer/engines/entityhubdereference.mdtext?rev=1597019&r1=1597018&r2=1597019&view=diff
==============================================================================
---
stanbol/site/trunk/content/docs/trunk/components/enhancer/engines/entityhubdereference.mdtext
(original)
+++
stanbol/site/trunk/content/docs/trunk/components/enhancer/engines/entityhubdereference.mdtext
Fri May 23 07:15:21 2014
@@ -1,10 +1,10 @@
title: Entityhub Dereference Engine
-This is a [Entity Dereference Engine](dereference) for the [Stanbol
Entityhub](/docs/trunk/components/entityhub). It supports dereferencing
Entities from
+This is an [Entity Dereference Engine](dereference) for the [Stanbol
Entityhub](/docs/trunk/components/entityhub). It supports dereferencing
Entities from
-* Entityhub: locally managed Entities
-* Managed and Referenced Sites
-* SiteManager: Union view over all Managed and Referenced Sites
+* Entityhub: locally managed Entities (the `/entityhub` endpoint)
+* Managed and Referenced Sites (the `/entityhub/site/{site-name}` endpoints)
+* SiteManager: Union view over all Managed and Referenced Sites (the
`/entityhub/sites` endpoint)
## Configuration
@@ -17,11 +17,9 @@ The following Configuration parameter ar
* __Name__ _(stanbol.enhancer.engine.name)_: The name of the Enhancement engine
* __Site__ _(enhancer.engines.dereference.entityhub.siteId)_: The name of the
Entityhub Site to be used for dereferencing. `*` will dereference against the
SiteManager (union over all Referenced and Managed sites) and `entityhub` will
use the entityhub itself for dereferencing.
-* __Fallback Mode__ _(enhancer.engines.dereference.fallback)_: If enabled the
EnhancementEngine ordering will get adapted in a way that in case a [Weighted
Chain](../chains/weightedchain) 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
- 1. First running Dereference Engines for fast/local data sources.
Especially those where one can configure an _URI Prefix_ and/or an _URI
Pattern_. Second running Dereference Engines for datastes that require remote
service calls or for those no _URI Prefix_ nor _URI Pattern_ can be configured.
This can be achieved by deactivating _Fallback Mode_ for the first group and
activating it for the second.
- 2. 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 _Fallback Mode_ for the local cache and an other for the
remote datasource with activated _Fallback Mode_. This setting ensures that
only Entities not available in the local cache are requested from the remote
service.
-* __URI Prefix__ _(enhancer.engines.dereference.uriPrefix)_: 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.
-* __URI Pattern__ _(enhancer.engines.dereference.uriPatter)_: 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.
+* __Fallback Mode__ _(enhancer.engines.dereference.fallback)_: 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 [Entity
Dereference Engine](dereference) for more information and possible usage
scenarios).
+* __URI Prefix__ _(enhancer.engines.dereference.uriPrefix)_: 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 `EntityDereferencer`.
+* __URI Pattern__ _(enhancer.engines.dereference.uriPatter)_: 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.
* __Dereference only Content Language Literals__
_(enhancer.engine.dereference.filterContentlanguages)_: 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.
* __Dereferenced Fields__ _(enhancer.engines.dereference.fields)_: The
dereferenced fields - in RDF terminology 'properties' - to be dereferenced.
QNames (e.g. `rdf:label`) can be used for the configuration. This Engine
supports the use of FieldMappings for the configuration (see the according
sub-section for details).
* __Dereference LD Path__ _(enhancer.engines.dereference.ldpath)_: The [LD
Path Language](http://marmotta.apache.org/ldpath/language.html) allows to
define powerful selectors for dereferenced Entities.
@@ -44,3 +42,22 @@ The Shared Thread Pool is a singelton Co
The _enhancer.engines.dereference.fields_ configuration does support the
Entityhub Field Mapping language.
+FieldMappings do use the following syntax:
+
+ :::text
+ [!]FieldPattern [| Filter] [> Mapping]
+
+* an optional Exclusion indicated by '!' as the first character of the mapping
used to exclude fields that are matched by the pattern.
+* the required _FieldPattern_ supports the definition of prefixes such as
`http://xmlns.com/foaf/0.1/*` or `foaf:*`
+* the optional _Filter_ part allows to filter specific languages (e.g.
`@=null;en;de;` will only dereference English and German literals as well as
literals with no language tag), typed literals (e.g. `d=xsd:dateTime;xsd:date`)
or URI values (e.g. `d=entityhub:ref`). Filters will also try to convert values
to the parsed data type (e.g. `d=xsd:double` would convert `xsd:float` values
to `xsd:doule`. Also string literals that can be parsed as double would be
converted).
+* an optional _Mapping_ can be used to copy values to an other field (e.g.
`foaf:name > schema:name` would copy all FOAF names to the schema.org name
field)
+
+__NOTE__: Field Mappings configured for the EntityhubDerefereceEngine are
overridden by Field Mappings parsed as [Enhancement
Properties](../enhancementproperties).
+
+## Supported Enhancement Properties
+
+The following Enhancement Properties are supported by the Entityhub
Dereference Engine
+
+* __Dereference Languages__ _(enhancer.engines.dereference.languages)_: A set
of languages that are dereferenced. Even if _'Dereference only Content Language
Literals'_ is active explicitly configured languages will still get
dereferenced. * __Dereferenced Fields__
_(enhancer.engines.dereference.fields)_: The dereferenced fields - in RDF
terminology 'properties' - to be dereferenced. QNames (e.g. `rdf:label`) 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.
+* __Dereference LD Path__ _(enhancer.engines.dereference.ldpath)_: The [LD
Path Language](http://marmotta.apache.org/ldpath/language.html) 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.
+
Modified:
stanbol/site/trunk/content/docs/trunk/components/enhancer/enhancementproperties.mdtext
URL:
http://svn.apache.org/viewvc/stanbol/site/trunk/content/docs/trunk/components/enhancer/enhancementproperties.mdtext?rev=1597019&r1=1597018&r2=1597019&view=diff
==============================================================================
---
stanbol/site/trunk/content/docs/trunk/components/enhancer/enhancementproperties.mdtext
(original)
+++
stanbol/site/trunk/content/docs/trunk/components/enhancer/enhancementproperties.mdtext
Fri May 23 07:15:21 2014
@@ -14,39 +14,40 @@ The String key of Enhancement Properties
Globally defined properties use '`enhancer.{property-name}`'. Enhancement
Engine specific properties a possible shorted/simplified name of the engine
should be used as `{level-1}`. Engine specific properties might also use
`engines` as `{level-1}` and the name of the engine as `{level-2}`.
-Examples: `enhancer.max-suggestions` or `enhancer.min-confidence` are typical
examples for globally defined Enhancement Properties. Properties defined by
specific Enhancement Engines will look like
`enhancer.entity-co-mention.adjust-existing-confidence` or
`enhancer.engines.dereference.fields` (as defined by
[STANBOL-1287](https://issues.apache.org/jira/browse/STANBOL-1287).
+Examples: `enhancer.max-suggestions` or `enhancer.min-confidence` are typical
examples for globally defined Enhancement Properties. Properties defined by
specific Enhancement Engines will look like
`enhancer.entity-co-mention.adjust-existing-confidence` or
`enhancer.engines.dereference.fields` (as defined by
[STANBOL-1287](https://issues.apache.org/jira/browse/STANBOL-1287)).
Enhancement Properties can also be defined as RDF datatype properties. This
allows to specify the expected XSD data type of
expected values.
- @prefix ehp <http://stanbol.apache.org/ontology/enhancementproperties#>
+ @prefix ehp <http://stanbol.apache.org/ontology/enhancementproperties#> .
- ehp:enhancer.max-suggestions rdf:type rdfs:DatatypeProperty,
- xsd:datatype xsd:Integer;
+ ehp:enhancer.max-suggestions a rdfs:DatatypeProperty ;
+ xsd:datatype xsd:Integer .
- ehp:enhancer.min-confidence rdf:type rdfs:DatatypeProperty,
- xsd:datatype xsd:Double;
+ ehp:enhancer.min-confidence a rdfs:DatatypeProperty ;
+ xsd:datatype xsd:Double .
- ehp:enhancer.entity-co-mention.adjust-existing-confidence rdf:type
rdfs:DatatypeProperty,
- xsd:datatype xsd:Double;
+ ehp:enhancer.entity-co-mention.adjust-existing-confidence a
rdfs:DatatypeProperty ;
+ xsd:datatype xsd:Double .
- ehp:enhancer.engines.dereference.fields rdf:type
rdfs:DatatypeProperty,
- xsd:datatype xsd:String;
+ ehp:enhancer.engines.dereference.fields a rdfs:DatatypeProperty ;
+ xsd:datatype xsd:String .
_NOTE_ that the [Java Interface](#java-interface) will parse enhancement
properties as `Map<String,Object>`. 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.
-h2. Scopes
+Scopes
+------
Enhancement Properties can be defined with the following scopes
-1. __request and engine__: Properties with this scope are applied for a single
request and a specific [Enhancement Engine](engines) part of the executed
[Enhancement Chain](chains). They do have the highest priority and will
therefore override any property with the same name defined with an different
scope.
+1. __request and engine__: Properties with this scope are applied for a single
request and a specific [Enhancement Engine](engines) part of the executed
[Enhancement Chain](chains). They do have the highest priority and will
therefore override properties defined with any of the below scopes.
2. __request__: Properties valid for a single request that are parsed to every
Enhancement Engine part of the executed Enhancement Chain.
-3. __chain and engine__: Properties defined for a specific [Enhancement
Engine](engines) of an [Enhancement Chain](chains). This properties will get
applied to all calls of the Enhancement Engine part of the execution of the
Chain the property is defined for.
-4. __chain__: Properties parsed to every Enhancement Engine called as part of
the execution of the defined [Enhancement Chain](chains). 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.
+3. __chain and engine__: Properties defined for a specific [Enhancement
Engine](engines) of an [Enhancement Chain](chains). As all _chain_ scoped
properties, those get applied to all executions of that chain.
+4. __chain__: Chain specific properties parsed to all Enhancement Engines of
the [Enhancement Chain](chains). 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.
-Properties with a higher priority will override properties with an lower
priority. Meaning if a property `enhancer.min-confidence=0.5` is defined on a
_chain_ scope it can be overridden by `enhancer.min-confidence=0.75` on a
__chain and engine__ scope. A single request might still override the value on
a __request__ or __request and engine__ scope.
+Properties with a higher priority will override properties with an lower
priority. Meaning if a property `enhancer.min-confidence=0.5` is defined on a
_chain_ scope it can be overridden by `enhancer.min-confidence=0.75` on a
_chain and engine_ scope. A single request might still override the value on a
_request_ or _request and engine_ scope.
-__Chain__ and/or __chain and engine__ scoped properties are configured with
[Enhancement Chain](chains) definition. __Request__ and/or __request and
engine__ scoped properties can be specified as query parameter of the POST
request or via the Java API by accessing the _Request Properties_ content part.
See the following sections for detailed information.
+_Chain_ and/or _chain and engine_ scoped properties are configured with
[Enhancement Chain](chains) definition. _Request_ and/or _request and engine_
scoped properties can be specified as query parameter of the POST request or
via the Java API by accessing the _Request Properties_ content part. See the
following sections for detailed information.
Using Enhancement Properties
-----------------------------------
@@ -71,9 +72,9 @@ With `2.0.0` the EnhancementEngine API w
[..]
}
-The `Map<String,Object>` 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.
+The `Map<String,Object>` 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.
-The keys of in the map are the string keys of the parsed Enhancement
Properties (e.g. `enhancer.max-suggestion` or
`enhancer.engines.dereference.fields`). Values can be any Object. Arrays and
Collections may be used for multi value properties. The
`EnhancementEngineHelper` utility provides methods to convert values.
+The keys of in the map are the string keys of the parsed Enhancement
Properties (e.g. `enhancer.max-suggestion` or
`enhancer.engines.dereference.fields`). Values can be any Object. Arrays and
Collections may be used for multi value properties. The
`EnhancementEngineHelper` utility provides methods to convert values to
expected.
:::java
//define supported enhancement properties as constants
@@ -94,10 +95,10 @@ The keys of in the map are the string ke
_TIP_ the same methods can also be used to process the configuration parsed by
OSGI.
-Definition Chain scoped Enhancement Properties
-----------------------------------------------
+Definition ofChain scoped Enhancement Properties
+------------------------------------------------
-Chain scoped EnhancementProperties are represented by RDF in the
ExecutionPlan. As in `0.12.1` and `1.*` the ExecutionPlan is generated by the
Enhancement Chain implementations needs to support the configuration.
+Chain scoped EnhancementProperties are represented by RDF in the
ExecutionPlan. As in `0.12.1` and `1.*` the ExecutionPlan is provided by the
`Chain#getExecutionPlan()` method most currently used Chain implementations
where extended to support the the configuration of _chain_ scoped Enhancement
Properties.
Starting from `0.12.1` the [ListChain](chains/listchain),
[WeightedChain](chains/weightedchain) and [GraphChain](chains/graphchain) allow
the configuration of EnhancementProperties:
@@ -160,3 +161,13 @@ Java API.
reqProp.put("linking:enhancer.maxSuggestions","10");
_Note_ with the enhancer `2.0` the request properties content part will get
removed and replaced by the EnhancementJob API (TBD).
+
+## Enhancement Engine Support
+
+Enhancement Properties MUST BE supported by Enhancement Engine implementations.
+
+__NOTE:__ that the properties used in the different examples are NOT supported
in with the `0.12.1` release. The definition of global enhancement properties
and its support for the most commonly used enhancement engines is paned to be
added before the `1.0.0` release. The epic
[STANBOL-1343](https://issues.apache.org/jira/browse/STANBOL-1343) tracks the
progress. Please also note the documentation of [specific
engines](engines/list) for details about supported properties.
+
+The only engine that does already support Enhancement Properties with the
`0.12.1` release is the [Entityhub Dereference
Engine](engines/entityhubdereference).
+
+
