Author: rwesten
Date: Fri Jan 27 08:23:41 2012
New Revision: 1236579
URL: http://svn.apache.org/viewvc?rev=1236579&view=rev
Log:
Added links to the EnhancementEngine documentation within other components
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/defaultchain.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/graphchain.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/listchain.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/weightedchain.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/enhancementengine.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.mdtext
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/defaultchain.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/defaultchain.mdtext?rev=1236579&r1=1236578&r2=1236579&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/defaultchain.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/defaultchain.mdtext
Fri Jan 27 08:23:41 2012
@@ -1,6 +1,6 @@
Title: DefaultChain
-Implementation that keeps track of all currently active EnhancementEngine and
registers itself as a Chain service with the
"stanbol.enhancer.chain.name=default" an service ranking of Integer.MIN_VALUE.
+Implementation that keeps track of all currently active
EnhancementEngine](../engines/enhancementengine.html) and registers itself as a
Chain service with the "stanbol.enhancer.chain.name=default" an service ranking
of Integer.MIN_VALUE.
This will cause this chain to be returned by the ChainManager.getDefault()
method if users:
@@ -22,7 +22,7 @@ The implementation is part of the "org.a
### Calculation of the ExecutionPlan
-This chain considers all currently active EnhancementEngines. The
ExecutionPlan is calculated by using the value for the
"org.apache.stanbol.enhancer.engine.order" property provided by the
EnhancementEngine:
+This chain considers all currently active
EnhancementEngine](../engines/enhancementengine.html)s. The ExecutionPlan is
calculated by using the value for the
"org.apache.stanbol.enhancer.engine.order" property provided by the
EnhancementEngine:
* Engines with a lower order are executed before Engines with a higher value
* Engines with the same order may be executed simultaneously if the
EnhancementJobMananger and the EnhancementEngine do support this feature.
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.mdtext?rev=1236579&r1=1236578&r2=1236579&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/enhancementchain.mdtext
Fri Jan 27 08:23:41 2012
@@ -1,6 +1,6 @@
Title: Enhancement Chains
-An Enhancement Chain defines how Content parsed to the Stanbol Enhancer is
processed. More concrete it defines what engines and in what order are used to
process ContentItems. Chains are not responsible for the actual processing of
ContentItems. They provide the [ExecutionPlan](executionplan.html) to the
[EnhancementJobManger](../enhancementjobmanager.html) that does the actual
processing of the ContentItem.
+An Enhancement Chain defines how Content parsed to the Stanbol Enhancer is
processed. More concrete it defines what
[EnhancementEngine](../engines/enhancementengine.html)s and in what order are
used to process ContentItems. Chains are not responsible for the actual
processing of ContentItems. They provide the
[ExecutionPlan](executionplan.html) to the
[EnhancementJobManger](../enhancementjobmanager.html) that does the actual
processing of the ContentItem.
In the RESTful API enhancement chains can be accessed by there name under
@@ -55,7 +55,7 @@ Each Chain has an name assigned. This is
within the activate method of the Chain. There is also an AbstractChain
implementation provided by the servicesapi module of the Stanbol Enhancer that
already implements this functionality.
-The getEngines method returns the name of all EnhancementEngines referenced by
a Chain. Note that this method returns a Set. This method is intended to allow
fast access to the referenced engines and does not provide any information
about the execution order.
+The getEngines method returns the name of all
[EnhancementEngine](../engines/enhancementengine.html)s referenced by a Chain.
Note that this method returns a Set. This method is intended to allow fast
access to the referenced engines and does not provide any information about the
execution order.
Components that need to know the details about a Chain need to process the
[ExecutionPlan](executionplan.html) returned by the getExectuonPlan() method.
The [ExecutionPlan](executionplan.html) is represented as an RDF graph
following the ExecutionPlan Ontology. It formally describes how a ContentItem
must be processed by the EnhancementJobManager. For details see the
documentation for the [ExecutionPlan](executionplan.html).
@@ -90,7 +90,7 @@ The default Chain is determined by the f
If no chain is active a ChainException with an according message MUST BE
thrown.
-All Stanbol launchers are configured with the [Default
Chain](defaultchain.html) enabled. This registers itself with the name
"default" and the lowest possible service ranking - Integer.MIN_VALUE. This
default provides a Chain that considered all currently active
EnhancementEngines and sorts them based on there ordering information (see the
[Calculation of the Execution Plan based on the EnhancementEngine
Ordering](weightedchain.html#calculation_of_the_executionplan) for details).
+All Stanbol launchers are configured with the [Default
Chain](defaultchain.html) enabled. This registers itself with the name
"default" and the lowest possible service ranking - Integer.MIN_VALUE. This
default provides a Chain that considered all currently active
[EnhancementEngine](../engines/enhancementengine.html)s and sorts them based on
there ordering information (see the [Calculation of the Execution Plan based on
the EnhancementEngine
Ordering](weightedchain.html#calculation_of_the_executionplan) for details).
### ChainManager interface
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.mdtext?rev=1236579&r1=1236578&r2=1236579&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.mdtext
Fri Jan 27 08:23:41 2012
@@ -14,21 +14,21 @@ The RDFS schema used for the execution p
* __ep:inExecutionPlan__ (domain: ep:ExecutionNode; range:
ep:ExecutionPlan ;inverseOf: ep:hasExecutionNode): functional property that
links the execution node with an execution plan
* __ep:engine__ (domain: ep:ExecutionNode; range: xsd:string): The
property used to link to the Enhancement Engine by the name of the engine.
* __ep:dependsOn__ (domain: ep:ExecutionNode; range: ep:ExecutionNode)
Defines that the execution of this node depends on the completion of the
referenced one.
- * __ep:optional__ (domain: ep:ExecutionNode; range: xsd:boolean) Can be
used to specify that the execution of this EnhancementEngine is optional. If
this property is set to TRUE an engine will be marked as executed even if it
execution was not possible (e.g. because an engine with this name was not
active) or the execution failed (e.g. because of the Exception).
+ * __ep:optional__ (domain: ep:ExecutionNode; range: xsd:boolean) Can be
used to specify that the execution of this
[EnhancementEngine](../engines/enhancementengine.html) is optional. If this
property is set to TRUE an engine will be marked as executed even if it
execution was not possible (e.g. because an engine with this name was not
active) or the execution failed (e.g. because of the Exception).
Note the the data for the ep:ExecutionPlan and the
ep:hasExecutionNode/ep:inExecutionPlan typically need not to be parsed as
configuration of a Chain. This information are typically automatically added
based on the assumption that all ep:ExecutionNode parsed in the configuration
for a chain are member of the execution plan for such chain. Therefore this
information is typically added by the Chain itself when the configuration is
parsed and validated.
#### Example:
-This example shows an ExecutionPlan with three nodes for the "langId", "ner",
"dbpediaLinking" "geonamesLinking" and "zemanta" engine. Note that this names
refer to actual EnhancementEngine Services registered with the current OSGI
Environment.
+This example shows an ExecutionPlan with three nodes for the "langId", "ner",
"dbpediaLinking" "geonamesLinking" and "zemanta" engine. Note that this names
refer to actual [EnhancementEngine](../engines/enhancementengine.html) Services
registered with the current OSGI Environment.
This example assumes that
-* "langId" is the singleton instance of LangIdEnhancementEngine
-* "ner" is the default instance of the NamedEntityExtractionEnhancementEngine
engine
-* "dbpediaLinking" is an instance of the NamedEntityTaggingEngine configured
to use the dbpedia.org ReferencedSite of the Entityhub
-* "geonamesLinking" is an instance of the NamedEntityTaggingEngine configured
to use the geonames.org ReferencedSite
-* "zemanta" is the singleton instance of the ZemantaEnhancementEngine
+* "langId" is the singleton instance of
[LangIdEnhancementEngine](../engines/langidengine.html)
+* "ner" is the default instance of the
[NamedEntityExtractionEnhancementEngine](../engines/namedentityextractionengine.html)
+* "dbpediaLinking" is an instance of the
[NamedEntityTaggingEngine](../engines/namedentitytaggingengine.html) configured
to use the dbpedia.org ReferencedSite of the Entityhub
+* "geonamesLinking" is an instance of the
[NamedEntityTaggingEngine](../engines/namedentitytaggingengine.html) configured
to use the geonames.org ReferencedSite
+* "zemanta" is the singleton instance of the
[ZemantaEnhancementEngine](../engines/zemantaengine.html)
The RDF graph of such a chain would look:
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/graphchain.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/graphchain.mdtext?rev=1236579&r1=1236578&r2=1236579&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/graphchain.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/graphchain.mdtext
Fri Jan 27 08:23:41 2012
@@ -1,6 +1,6 @@
Title: GraphChain
-The GraphChain allows to directly configure the ExecutionPlan returned by the
Chain.getExecutionPlan() method. This means on the one hand that it allows to
configure any kind of execution process on the other hand its usage also
requires a lot of knowledge about the EnhancementEngines and the ExecutionPlan
model form the user.
+The GraphChain allows to directly configure the ExecutionPlan returned by the
Chain.getExecutionPlan() method. This means on the one hand that it allows to
configure any kind of execution process on the other hand its usage also
requires a lot of knowledge about the
[EnhancementEngine](../engines/enhancementengine.html)s and the ExecutionPlan
model form the user.
Typically it is a good practice to start with other - more simple to use -
Chain implementation such as the [Weighted Chain](weightedchain.html) and only
afterwards convert this configuration to a GraphChain to configure
optimizations to the enhancement process such as to allow more Engines to be
executed in parallel.
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/listchain.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/listchain.mdtext?rev=1236579&r1=1236578&r2=1236579&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/listchain.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/listchain.mdtext
Fri Jan 27 08:23:41 2012
@@ -1,6 +1,6 @@
Title: ListChain
-The List Chain creates the ExecutionPlan based on the exact order of the
configured EnhancementEngines. This provides users with a simple possibility
configure the exact oder in that the referenced EnhancementEngines are called
during the enhancement process of a content item. However the ListChain can not
support parallel execution of engines a considerable disadvantage in contrast
to the [GraphChain](graphchain.html).
+The List Chain creates the ExecutionPlan based on the exact order of the
configured [EnhancementEngine](../engines/enhancementengine.html)s. This
provides users with a simple possibility configure the exact oder in that the
referenced EnhancementEngines are called during the enhancement process of a
content item. However the ListChain can not support parallel execution of
engines a considerable disadvantage in contrast to the
[GraphChain](graphchain.html).
A typical usage scenario would be that users start of with configuring a
ListChain and later optimize the execution by migrating functional
configuration to [GraphChain](graphchain.html)s.
@@ -30,4 +30,4 @@ To create the same configuration as in t
### Calculation of the ExecutionPlan
-The ExecutionPlan is created based on the exact order of the
EnhancementEngines provided by the "stanbol.enhancer.chain.list.enginelist"
property. The configuration MUST contain at least a single engine. In addition
no engine MUST be mentioned twice.
+The ExecutionPlan is created based on the exact order of the
EnhancementEngine](../engines/enhancementengine.html)s provided by the
"stanbol.enhancer.chain.list.enginelist" property. The configuration MUST
contain at least a single engine. In addition no engine MUST be mentioned twice.
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/weightedchain.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/weightedchain.mdtext?rev=1236579&r1=1236578&r2=1236579&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/weightedchain.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/weightedchain.mdtext
Fri Jan 27 08:23:41 2012
@@ -1,6 +1,6 @@
Title: WeightedChain
-The Wighted Chain takes a list of Enhancement Engine names as input and uses
the "org.apache.stanbol.enhancer.engine.order" metadata of the configured
Engines to calculate the ExecutionPlan.
+The Wighted Chain takes a list of
EnhancementEngine](../engines/enhancementengine.html) names as input and uses
the "org.apache.stanbol.enhancer.engine.order" metadata of the configured
Engines to calculate the ExecutionPlan.
This Chain is designed for easy configuration - just a list of the engine
names - but has limited possibilities to control the execution order.
@@ -21,7 +21,7 @@ both variants result that the execution
### Calculation of the ExecutionPlan
-It is important to note that the ordering of the list has no influence on the
ExecutionPlan because the order of execution of the configured
EnhancementEngines is calculated only by using the value for the
"org.apache.stanbol.enhancer.engine.order" property provided by the
EnhancementEngine:
+It is important to note that the ordering of the list has no influence on the
ExecutionPlan because the order of execution of the configured
EnhancementEngine](../engines/enhancementengine.html)s is calculated only by
using the value for the "org.apache.stanbol.enhancer.engine.order" property
provided by the EnhancementEngine:
* Engines with a lower order are executed before Engines with a higher value
* Engines with the same order may be executed simultaneously if the
EnhancementJobMananger and the EnhancementEngine do support this feature.
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/enhancementengine.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/enhancementengine.mdtext?rev=1236579&r1=1236578&r2=1236579&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/enhancementengine.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/enhancementengine.mdtext
Fri Jan 27 08:23:41 2012
@@ -1,6 +1,6 @@
Title: EnhancementEngine
-EnhancementEngines are the components that are responsible to enhance
ContentItmes. They are called by the
[EnhancementJobManager](enhancementjobmanager.html). EnhancementEngines do have
full access to the parsed ContentItems. They are expected to modify the state
of the content item.
+EnhancementEngines are the components that are responsible to enhance
ContentItmes. They are called by the
[EnhancementJobManager](../enhancementjobmanager.html). EnhancementEngines do
have full access to the parsed ContentItems. They are expected to modify the
state of the content item.
The RESTful interface of an EnhancementEngines can be accessed by
@@ -79,7 +79,7 @@ The Engine Ordering information as descr
Basically this features allows the implementor of an EnhancementEngine to
define the correct position of his engine within an typical enhancement chain
and therefore ensure that users that add this engine to a Stanbol Enhancer
installation to immediately use this engine with the
[DefaultChain](../chains/defaultchain.html).
-However the Engine Ordering is not the only possibility for users to control
the execution order. Enhancement chain implementations such as the
[ListChain](../chains/listchain.html) and the
[GraphChain](../chains/grpahchain.html) do also allow to directly define the
oder of execution. For this chains the ordering information provided by
EnhancementEngines are ignored.
+However the Engine Ordering is not the only possibility for users to control
the execution order. Enhancement chain implementations such as the
[ListChain](../chains/listchain.html) and the
[GraphChain](../chains/graphchain.html) do also allow to directly define the
oder of execution. For this chains the ordering information provided by
EnhancementEngines are ignored.
## EnhancementEngine management
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.mdtext?rev=1236579&r1=1236578&r2=1236579&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.mdtext
Fri Jan 27 08:23:41 2012
@@ -13,7 +13,7 @@ The interface of the EnhancementJobManag
/** Enhances the content item by using the parsed Chain */
+ enhanceContent(ContentItem ci, Chain chain)
-Note that the parsed ContentItem will be changed during the enhancement
process. EnhancementEngines will add extracted knowledge to the metadata of the
content item. Also additional content parts may be added to the content item.
+Note that the parsed ContentItem will be changed during the enhancement
process. [EnhancementEngine](engines/enhancementengine.html)s will add
extracted knowledge to the metadata of the content item. Also additional
content parts may be added to the content item.
## Enhancement Process
@@ -36,7 +36,7 @@ See the documentation of the [ExecutionM
### Engine Execution
-The ExecutionPlan provides the necessary information what engines can be
executed at any given state. The following code shows how to determine
executable engines.
+The ExecutionPlan provides the necessary information what
[EnhancementEngine](engines/enhancementengine.html)s can be executed at any
given state. The following code shows how to determine executable engines.
This code snippet assumes to be called after the execution of an
EnhancementEngine has completed. Note that in a multi threaded environment
access to the list of executed and running engines need to be synchronized.
Collection<NonLiteral> executed; //already executed Engines
@@ -55,7 +55,7 @@ This code snippet assumes to be called a
} // else already running -> ignore
}
-Before executing an EnhancementEngine the EnhancementJobManager needs to check
if and how the engine can enhance a content item. This is indicated by the
integer returned by the "canEnhance(ContentItem ci)" method:
+Before executing an [EnhancementEngine](engines/enhancementengine.html) the
EnhancementJobManager needs to check if and how the engine can enhance a
content item. This is indicated by the integer returned by the
"canEnhance(ContentItem ci)" method:
* __CANNOT_ENHANCE__: Indicates that this engines can not process the parsed
content item. In this case the EnhancementJobManager needs to skip this engine
and mark the EngineExectuion as skipt with a status message that the
EnhancementEngine was unable to process the content item. If this engine is
marked as optional the enhancement process can continue if not, than the
execution MUST be marked as failed and an according Exception needs to be
thrown.
* __ENHANCE_SYNCHRONOUS__: Indicates that the engines needs exclusive access
to the parsed content item. The EnhancementJobManager needs to ensure that in
some way. Typically by calling the "computeEnhancement(ContentItem ci)" method
within an write lock.
@@ -67,7 +67,7 @@ If a call to "computeEnhancement(Content
### Multi Threaded enhancement processes
-In case the EnhancementJobManager supports to simultaneously call
EnhancementEngines for the same content item in multiple threads it is
important to correctly use the ReadWriteLock as provided by the
ContentItem.getLock() method.
+In case the EnhancementJobManager supports to simultaneously call
[EnhancementEngine](engines/enhancementengine.html)s for the same content item
in multiple threads it is important to correctly use the ReadWriteLock as
provided by the ContentItem.getLock() method.
There are manny good examples on how to correctly use
"java.util.concurrent.ReadWriteLock" available on the web.
