You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by ag...@apache.org on 2012/02/22 14:25:14 UTC
svn commit: r1292276 - in
/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer: ./
chains/ engines/
Author: agruber
Date: Wed Feb 22 13:25:13 2012
New Revision: 1292276
URL: http://svn.apache.org/viewvc?rev=1292276&view=rev
Log:
STANBOL-449 Minor text edits, typos in engines and chains doku
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/chainmanager.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/defaultchain.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/index.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/contentitem.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/enhancementenginemanager.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/geonamesengine.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/index.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/keywordlinkingengine.mdtext
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/chainmanager.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/chainmanager.mdtext?rev=1292276&r1=1292275&r2=1292276&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/chainmanager.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/chainmanager.mdtext Wed Feb 22 13:25:13 2012
@@ -1,10 +1,10 @@
-Title: ChainManager
+Title: Chain Manager
-The ChainManager provides name based access to all active [Enhancement Chain](index.html) and their ServiceReferences. This interface is typically used by components that need to lookup Chains based on their name. However the ChainsTracker implementation can also be used to track specific Chains.
+The ChainManager provides name based access to all active [Enhancement Chains](index.html) and their ServiceReferences. This interface is typically used by components that need to lookup Chains based on their name. However the ChainsTracker implementation can also be used to track specific Chains.
-### ChainManager interface
+## ChainManager interface
-This is the Java API providing access to registered Chains in the ways as described above. This interface includes the following methods:
+This is the Java API providing access to registered chains in the ways as described above. This interface includes the following methods:
:::java
/** Constant for the name of the DefaultChain */
@@ -31,7 +31,7 @@ This is the Java API providing access to
There are two implementations of this interface available:
-#### ChainManager Service
+### ChainManager Service
This is an implementation of the ChainManager interface that is registered as OSGI service. It can be used e.g. by using the @Reference annotation
@@ -41,9 +41,9 @@ This is an implementation of the ChainMa
This service is provided by the "org.apache.stanbol.enhancer.chainmanger" module and is included in all Stanbol launchers.
-#### ChainsTracker
+### ChainsTracker
-This is an Utility similar to the standard OSGI ServiceTracker that allows to track some/all Chains. It also supports the usage of a ServiceTrackerCustomizer so that users of that utility can directly react to changes of tracked Chains.
+This is an utility similar to the standard OSGI ServiceTracker that allows to track some/all chains. It also supports the usage of a ServiceTrackerCustomizer so that users of this utility can directly react to changes of tracked chains.
:::java
//track only "myChain" and "otherChain"
@@ -55,4 +55,4 @@ This is an Utility similar to the standa
tracker.close()
tracker = null;
-For most users the ChainManager service is sufficient and preferable. Direct use of the ChainTracker is only recommended if one needs only to track some specific chains and especially if one needs to get notified an changes of such chains.
\ No newline at end of file
+For most users the ChainManager service is sufficient and preferable. Direct use of the ChainsTracker is only recommended if one needs only to track some specific chains and especially if one needs to get notified an changes of such chains.
\ No newline at end of file
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=1292276&r1=1292275&r2=1292276&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 Wed Feb 22 13:25:13 2012
@@ -1,32 +1,32 @@
-Title: DefaultChain
+Title: Default Chain
-Implementation that keeps track of all currently active [EnhancementEngine](../engines) and registers itself as a Chain service with the "stanbol.enhancer.chain.name=default" an service ranking of Integer.MIN_VALUE.
+This implementation that keeps track of all currently active [Enhancement Engines](../engines) and registers itself as a chain service with the "stanbol.enhancer.chain.name=default" and the service ranking of Integer.MIN_VALUE.
This will cause this chain to be returned by the ChainManager.getDefault() method if users:
-* do not deactivate this Chain (see below)
-* configure an other Chain with the "stanbol.enhancer.chain.name=default" and an higher service ranking
+* do not deactivate this chain (see below)
+* configure an other chain with the "stanbol.enhancer.chain.name=default" and a higher service ranking
The Chain returned by ChainManager.getDefault() is the one used for requests that do not specify a chain. This are enhancement requests to the "/engines" and "/enhancer" endpoint.
-### Configuration
+## Configuration
This chain can be enabled/disabled by using the "stanbol.enhancer.chain.default.enabled"
-
+
This chain does not support the configuration of the name nor the service ranking. The name is fixed to "default" and the service ranking is Integer.MIN_VALUE
Note that the DefaultChain does not actually implement the Chain interface, but only registers an instance of the AllActiveEnginesChain on activation.
The implementation is part of the "org.apache.stanbol.enhancer.chain.allactive" module.
-### Calculation of the ExecutionPlan
+## Calculation of the ExecutionPlan
-This chain considers all currently active [EnhancementEngine](../engines)s. 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 [Enhancement Engines](../engines). 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 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.
-The DefaultChain ensures therefore that the default behavior of the Stanbol Enhancer does not change after the introduction of EnhancementChains. This is because the WeightedJobManager as used previously followed exactly the same rules.
+The DefaultChain ensures that the default behavior of the Stanbol Enhancer does not change after the introduction of EnhancementChains. This is because the WeightedJobManager as used previously followed exactly the same rules.
However after the introduction of EnhancementChains users can now easily change the default behavior.
\ No newline at end of file
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=1292276&r1=1292275&r2=1292276&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 Wed Feb 22 13:25:13 2012
@@ -1,28 +1,28 @@
-Title: ExecutionPlan
+Title: Execution Plan
-The ExecutionPlan is represented as an RDF graph following the ExecutionPlan Ontology. It needs to be provided by the [Enhancement Chain](index.html) and is used by the [EnhancementJobManager](../enhancementjobmanager.html) to enhance [ContentItem](../contentitem.html)s and to write the [ExecutionMetadata](../executionmetadata.html).
+The ExecutionPlan is represented as an RDF graph following the ExecutionPlan ontology. It needs to be provided by the [Enhancement Chain](index.html) and is used by the [EnhancementJobManager](../enhancementjobmanager.html) to enhance [ContentItems](../contentitem.html) and to write the [ExecutionMetadata](../executionmetadata.html).
## ExecutionPlan Ontology
-The RDFS schema used for the execution plan is defined as follows.
+The RDFS schema used for the execution plan is defined as follows:
* Namespace: ep : http://stanbol.apache.org/ontology/enhancer/executionplan#
- * __ep:ExecutionPlan__ : Represent an execution plan defined by all linked execution nodes.
+ * __ep:ExecutionPlan__ : Represents an execution plan defined by all linked execution nodes.
* __ep:hasExecutionNode__ (domain: ep:ExecutionPlan; range: ep:ExecutionNode; inverseOf: ep:inExecutionPlan): links the execution plan with all the execution nodes.
- * __ep:chain__ (domain: ep:ExecutionPlan; range: xsd:string): The name of the Chain this execution plan is used for.
+ * __ep:chain__ (domain: ep:ExecutionPlan; range: xsd:string): The name of the chain this execution plan is used for.
* __ep:ExecutionNode__ : Class used for all Nodes representing the execution of an Enhancement Engine.
* __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:engine__ (domain: ep:ExecutionNode; range: xsd:string): The property is 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](../engines) 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.
+Note: the data for the ep:ExecutionPlan and the ep:hasExecutionNode/ep:inExecutionPlan typically need not to be parsed as configuration of a Chain. This information are typically automatically added based on the assumption that all ep:ExecutionNode parsed in the configuration for a chain are member of the execution plan for such a chain. Therefore, this information is typically added by the chain itself when the configuration is parsed and validated.
-#### Example:
+### 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](../engines) Services registered with the current OSGI Environment.
+This example shows an ExecutionPlan with the nodes for the "langId", "ner", "dbpediaLinking" "geonamesLinking" and "zemanta" engine. Note that this names refer to actual [EnhancementEngine](../engines) Services registered with the current OSGI Environment.
This example assumes that
@@ -32,7 +32,7 @@ This example assumes that
* "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:
+The RDF graph of such a chain would look
:::text
urn:execPlan
@@ -43,7 +43,7 @@ The RDF graph of such a chain would look
urn:node1
rdf:type stanbol:ExecutionNode
ep:inExecutionPlan urn:execPlan
- stanbol:engine langId
+ ep:engine langId
urn:node2
rdf:type ep:ExecutionNode
@@ -69,20 +69,20 @@ The RDF graph of such a chain would look
ep:engine zemanta
ep:optional "true"^^xsd:boolean
-This plan defines that the "langId" and the "zemanta" engine do not depend on anything and can therefore be executed from the start (even in parallel if the JobManager execution this chains supports this). The execution of the "ner" engine depends on the extraction of the language and the execution of the entity linking to dbpedia and geonames depends on the "ner" engine. Note that the execution of the "dbpediaLinking" and "geonamesLinking" could be also processed in parallel.
+This plan defines that the "langId" and the "zemanta" engine do not depend on anything and can therefore be executed from the start (even in parallel if the JobManager execution of these chains supports this). The execution of the "ner" engine depends on the extraction of the language and the execution of the entity linking to dbpedia and geonames depends on the "ner" engine. Note that the execution of the "dbpediaLinking" and "geonamesLinking" could be also processed in parallel.
-#### ExecutionPlan Utility:
+## ExecutionPlan Utility
-The Enhancer MUST also define an Utility that provides the following utility
+The Enhancer MUST also define an utility that provides the following:
:::java
/** Getter for the list of executable ep:ExecutionNodes */
+ getExecuteable(Graph executionPlan, Set<NonLiteral> completed) : Collection<NonLiteral>
-This method takes an execution plan and the list of already executed nodes as input and return the list of ExecutionNodes that can be executed next. The existing utility methods within the EnhancementEngineHelper can be used to retrieve further information from the ex:ExecutionNode's returned by this method.
+This method takes an execution plan and the list of already executed nodes as input and return the list of ExecutionNodes that can be executed next. The existing utility methods within the EnhancementEngineHelper can be used to retrieve further information from the ex:ExecutionNodes returned by this method.
-Typically code using this utility will look like this (pseudo code)
+The code using this utility will look like this (pseudo code):
:::java
Graph executionPlan = chain.getExecuctionPlan();
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=1292276&r1=1292275&r2=1292276&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 Wed Feb 22 13:25:13 2012
@@ -1,39 +1,39 @@
-Title: GraphChain
+Title: Graph Chain
-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)s 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)s and the ExecutionPlan model.
-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.
+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.
-### Configuration
+## Configuration
-The GraphChain supports two variants to configure the ExecutionPlan
+The GraphChain supports two variants to configure the ExecutionPlan.
-#### GraphResource
+### GraphResource
-A GraphResource is a RDF file available via the DataFileProvider. The easiest way is to copy the RDF file defining the ExecutionPlan to the "/sling/datafile" directory within the Stanbol home directory. The configuration of the GraphChain needs than only to refer to that file such as:
+A GraphResource is an RDF file available via the DataFileProvider. The easiest way is to copy the RDF file defining the ExecutionPlan to the "/sling/datafile" directory within the Stanbol home directory. The configuration of the GraphChain needs then only to refer to that file such as:
:::properties
stanbol.enhancer.chain.graph.graphresource=myExecutionPlan.rdf
-The used RDF encoding is guessed by the file extension. If the extension is not recognized the format can be also parsed as additional parameter
+The used RDF encoding is guessed by the file extension. If the extension is not recognized, the format can be also parsed as additional parameter
:::properties
stanbol.enhancer.chain.graph.graphresource=myExecutionPlan.something;format=application/rdf+xml
-The GraphCain will track for that file and activate itself as soon as the file gets available. Removing the file, waiting some seconds and providing the new version afterwards should also work. Just replacing the file will not work, because the DataFileProvider does not have supports for updates. In such cases it might be needed to deactivate/activate the GraphChain.
+The GraphCain will track for that file and activate itself as soon as the file gets available. Removing the file, waiting some seconds and providing the new version afterwards should also work. Just replacing the file will not work, because the DataFileProvider does not have support for updates. In such cases it might be needed to deactivate/activate the GraphChain.
-#### ChainList
+### ChainList
-This allows to directly configure the ExecutionPlan as value of the "stanbol.enhancer.chain.graph.chainlist" property. Both arrays and Collections are supported.
+This allows to directly configure the ExecutionPlan as value of the "stanbol.enhancer.chain.graph.chainlist" property. Both arrays and collections are supported.
-_NOTE_: As soon as a graph resource is configures the ChainList is ignored. This is even true if the configured GraphResource is currently not available!
+_Note:_ As soon as a graph resource is configured the ChainList will be ignored. This is even true if the configured GraphResource is currently not available!
-The Syntax is defined as follows:
+The syntax is defined as follows:
:::text
{engine-name};[optional];[dependsOn={engine-name1},{engine-name2}]
-The following Example shows how this Syntax can be used to define an ExecutionPlan.
+The following example shows how this syntax can be used to define an ExecutionPlan.
:::text
metaxa;optional
@@ -44,9 +44,9 @@ The following Example shows how this Syn
geonames;optional;dependsOn=ner
refactor;dependsOn=geonames,dbpedia-linking,zemanta
-Not that the internal oder of the list does not influence the resulting ExecutionPlan. Only the "dependsOn" properties are used to determine the execution order of the Engines and if Engines can be executed in parallel.
+_Note:_ The internal oder of the list does not influence the resulting ExecutionPlan. Only the "dependsOn" properties are used to determine the execution order of the engines and if engines can be executed in parallel.
-Within an osgi configuration file (org.apache.stanbol.enhancer.chain.graph.impl.GraphChain-myGraphChain.config) this would look like
+Within an OSGI configuration file (org.apache.stanbol.enhancer.chain.graph.impl.GraphChain-myGraphChain.config) this would look like
:::properties
stanbol.enhancer.chain.graph.chainlist=[
@@ -55,27 +55,27 @@ Within an osgi configuration file (org.a
"geonames;optional;dependsOn\=ner",
"refactor;dependsOn\=geonames,dbpedia-linking,zemanta"]
-_NOTE:_ the whole test MUST BE in a single line within the .config file
+_Note:_ The whole test MUST BE in a single line within the .config file.
-A better visual expression provides this screenshot of the Apache Feilx Webconsole showing the dialog for the same configuration
+A better visual expression provides this screenshot of the Apache Felix web console showing the dialog for the above configuration
-
+
-### Execution
+## Execution
-In contrast to other Chain implementation the ExecutionPlan must not be calculated but is directly parsed by the user. This provides the most possible freedom in defining how the execution should take place.
+In contrast to other chain implementations the ExecutionPlan must not be calculated but is directly parsed by the user. This provides the most possible freedom in defining how the execution should take place.
-#### Optional Engines
+### Optional Engines
-The execution of optional engines is not mandatory. If they are not active or the execution fails the enhancement process continues. For users it is important to not that even Engines that depend on an optional Engine that was not executed will be called.
+The execution of optional engines is not mandatory. The enhancement process will continue, even if they are not active or their execution fail. For users it is important to know, that even engines that depend on an optional engine that was not executed will be called.
Given the above example this means that even if the 'metaxa' engine can not be executed the 'langId' will be called by the EnhancementJobManager.
-#### Parallel Execution
+### Parallel Execution
-Engines are executed as soon as all Engines they dependOn have completed. This also includes if optional engines where skipped (because they are not active) or failed. This means that in most cases several EnhancementEngines can be executed in parallel.
+Engines are executed as soon as all engines they depend on have completed. This also includes if optional engines were skipped (because they are not active) or failed. This means that in most cases several EnhancementEngines can be executed in parallel.
-Given the above Example both the 'zemanta' and the 'metaxa' engine are executed as soon as the enhancement process starts.
-When 'metaxa' finished the 'langid' engine is called. After the 'langid' finishes its work the EnhancementJobManager calls the 'ner' engine. After that both the 'dbpedia-linking' and the 'geonames' engine are called. At this time three engines might run simultaneously assuming that 'zemanta' has not finished yet. Before the 'refactor' engine can be executed it need to wait for all this engines to complete.
+Given the above example, both the 'zemanta' and the 'metaxa' engine are executed as soon as the enhancement process starts.
+When 'metaxa' is finished, the 'langid' engine is called. After the 'langid' finishes its work, the EnhancementJobManager calls the 'ner' engine. After that both the 'dbpedia-linking' and the 'geonames' engine are called. At this time three engines might run simultaneously assuming that 'zemanta' has not finished yet. Before the 'refactor' engine can be executed it need to wait for all these engines to complete.
Note that for parallel execution to be activated both the used EnhancementJobManager and the different engines must support asynchronous enhancement.
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/index.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/index.mdtext?rev=1292276&r1=1292275&r2=1292276&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/index.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/index.mdtext Wed Feb 22 13:25:13 2012
@@ -1,13 +1,13 @@
Title: Enhancement Chains
-An Enhancement Chain defines how Content parsed to the Stanbol Enhancer is processed. More concrete it defines what [EnhancementEngine](../engines)s and in what order are used to process [ContentItem](../contentitem.html)s. 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 concretely it defines which [EnhancementEngines](../engines) and in what order are used to process [ContentItems](../contentitem.html). 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
+In the RESTful API enhancement chains can be accessed by their name under
:::text
http://{host}:{port}/{stanbol-path}/enhancer/chain/{chain-name}
-Enhancement requestes issued to
+Enhancement requests issued to
:::text
http://{host}:{port}/{stanbol-path}/enhancer
@@ -15,7 +15,7 @@ Enhancement requestes issued to
are processed by using the default enhancement chain.
-When using the Java API Chains can be looked up as OSGI services. The [ChainManager](chainmanager.html) service is designed to ease this by providing a API that allows to access Chains by their name. Because Chains are not responsible to perform the actual execution but only provide the [ExecutionPlan](executionplan.html) one needs to also lookup an EnhancementJobManager instance to enhance a contentItem
+When using the Java API Chains can be looked up as OSGI services. The [ChainManager](chainmanager.html) service is designed to ease this by providing an API that allows to access Chains by their name. Because Chains are not responsible to perform the actual execution but only provide the [ExecutionPlan](executionplan.html) one needs to also lookup an EnhancementJobManager instance to enhance a ContentItem.
:::java
@Reference
@@ -41,7 +41,7 @@ To enhance a ContentItem with the defaul
## Chain Interface
-The Chain interface is very simplistic. It only defines three methods.
+The Chain interface is very simplistic. It defines just the following three methods:
:::java
/** Getter for the name of the Chain */
@@ -60,23 +60,23 @@ 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 [EnhancementEngine](../engines)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.
+The getEngines method returns the name of all [EnhancementEngines](../engines) 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).
+Components that need to know the details about a Chain need to process the [ExecutionPlan](executionplan.html) returned by the <code>getExecutionPlan()</code> 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).
-For Chain implementation it is important that the returned Graph holding the execution plan MUST BE read-only AND final. Meaning that a change in the configuration of a Chain MUST NOT change the graph returned by calls to the getExecutionPlan method.
+For any Chain implementation it is important that the returned Graph holding the execution plan MUST BE read-only AND final. This means, that a change in the configuration of a Chain MUST NOT change the graph returned by calls to the getExecutionPlan method.
-Because the configuration of a Chain might change at any time EnhancementJobManager implementation MUST retrieve the execution plan once and than use this instance for the whole enhancement process. Because of the above requirement that the execution plan is stored in an read-only and final Graph this ensures that the plan can not change even for long lasting enhancement processes. Therefore any change to the configuration of a chain will not influence ongoing enhancement processes.
+Because the configuration of a Chain might change at any time, the EnhancementJobManager implementation MUST retrieve the execution plan once and then use this instance for the whole enhancement process. Because of the above requirement that the execution plan is stored in a read-only and final Graph this ensures that the plan can not change even for long lasting enhancement processes. Therefore any change to the configuration of a chain will not influence the ongoing enhancement processes.
## Enhancement Chain Management
This section describes how Enhancement Chains are managed by the Stanbol Enhancer and how they can be selected/accessed. It also describes how the "default" Chain is determined.
-For every Stanbol Enhancer a single Chain MUST BE present. If this is not the case enhance request MUST throw a ChainException with an according error message. However typically multiple EnhancementChains will be configured.
+For every Stanbol Enhancer a single Chain MUST BE present. If this is not the case enhance requests MUST throw a ChainException with an according error message. However typically multiple EnhancementChains will be configured.
### Chain Name Conflicts
-Chains are identified by the value of the "stanbol.enhancer.chain.name" property - the name of the chain. If more than one Chain do use the same name, than the normal OSGI procedure to select the default service is used. This means that
+Chains are identified by the value of the "stanbol.enhancer.chain.name" property - the name of the chain. If more than one Chain do use the same name, then the normal OSGI procedure to select the default service is used. This means that
1. the Chain with the highest "service.ranking" and
2. the Chain with the lowest "service.id"
@@ -85,30 +85,28 @@ will be selected on requests for a given
### Default Chain
-The second important concept of the Chain management is the definition of the "default chain". The default Chin is used for enhancement requests that do not specify a Chain. This is true for requests to the "/engines" and "/enhancer" RESTful services as well as API calls to the "EnhancementJobManager.enhanceContent(ContentItem ci)" method.
+The second important concept of the Chain management is the definition of the "default chain". The default Chain is used for enhancement requests that do not specify a Chain. This is true for requests to the "/engines" and "/enhancer" RESTful services as well as API calls to the "EnhancementJobManager.enhanceContent(ContentItem ci)" method.
The default Chain is determined by the following rules:
-1. the Chain with the name "default". If more than one Chain is present with that name, than the above rules for resolving name conflicts apply. If none
-2. the Chain with the highest "service.ranking". If several have the same ranking
-3. the Chain with the lowest "service.id"
+1. the Chain with the name "default". If more than one Chain is present with that name, than the above rules for resolving name conflicts apply. If none,
+2. the Chain with the highest "service.ranking". If several have the same ranking,
+3. the Chain with the lowest "service.id".
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 [EnhancementEngine](../engines)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).
+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 considers all currently active [EnhancementEngines](../engines) and sorts them based on their ordering information (see the [Calculation of the Execution Plan based on the EnhancementEngine Ordering](weightedchain.html#calculation_of_the_executionplan) for details).
### ChainManager interface
-The [ChainManager](chainmanager.html) is the management interface for EnhancementChains that can be used by components to lookup chains based on their name. It also provides a getter for the default chain. There is also OSGI ServiceTracker like implementation that can be used to track only chains with specific names and to get even notified on any change of such chains.
+The [ChainManager](chainmanager.html) is the management interface for EnhancementChains that can be used by components to lookup chains based on their name. It also provides a getter for the default chain. There is also an OSGI ServiceTracker like implementation that can be used to track only chains with specific names and to get even notified on any change of such chains.
## Chain implementations
The following Chain implementations are included within the default Stanbol Enhancer distribution:
-* __[DefaultChain](defaultchain.html)__: Implementation that includes all currently active EnhancementEngine. If enabled it registers itself under the name "default" with the service ranking Integer.MIN_VALUE. This makes this chain to the default chain as long users do not deactivate it or register an other chain with the name "default".
+* __[DefaultChain](defaultchain.html)__: This implementation includes all currently active EnhancementEngines. If enabled it registers itself under the name "default" with the service ranking Integer.MIN_VALUE. This makes this chain to the default chain as long users do not deactivate it or register an other chain with the name "default".
* __[ListChain](listchain.html)__: Implementation that creates the ExecutionPlan by chaining the EnhancementEngines in the exact order as specified by the parsed list. This Chain does not support parallel execution of engines.
* __[WeightedChain](weightedchain.html)__: This Chain implementation takes a List of Engines names as input and uses the "org.apache.stanbol.enhancer.engine.order " metadata provided by such engines to calculate the ExecutionGraph.
-* __[GraphChain](graphchain.html)__: This Chain implementation is based on a ExecutionGraph parsed os configuration.
-* __SingleEngineChain__: An Adapter that allows to execute a single EnhancementEngine within a Chain. This types of Chains will not be registered as OSGI service. Instances will be created on request for single EnhancementEngines and directly parsed to the [EnhancementJobManager](../enhancementjobmanager.html) implementation.
-
-
+* __[GraphChain](graphchain.html)__: This Chain implementation is based on a ExecutionGraph parsed as configuration.
+* __SingleEngineChain__: An Adapter to execute a single EnhancementEngine within a Chain. This type of Chain will not be registered as OSGI service. Instances will be created on request for single EnhancementEngines and directly parsed to the [EnhancementJobManager](../enhancementjobmanager.html) implementation.
\ No newline at end of file
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=1292276&r1=1292275&r2=1292276&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 Wed Feb 22 13:25:13 2012
@@ -1,35 +1,34 @@
-Title: ListChain
+Title: List Chain
-The List Chain creates the ExecutionPlan based on the exact order of the configured [EnhancementEngine](../engines)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).
+The ListChain creates the ExecutionPlan based on the exact order of the configured [EnhancementEngines](../engines). This provides users with a simple possibility to configure the exact oder in which the referenced EnhancementEngines are called during the enhancement process of a content item. However the ListChain can not support parallel execution of engines - a considerable disadvantage in contrast to the [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.
+A typical usage scenario would be that users start of with configuring a ListChain and later optimize the execution by migrating functional configuration to a [GraphChain](graphchain.html).
-### Configuration
+## Configuration
-The property "stanbol.enhancer.chain.list.enginelist" is used to provide the list of engine names. This configuration MUST BE parsed as an Array as string because the ordering if the configured entries is central for the configuration.
+The property "stanbol.enhancer.chain.list.enginelist" is used to provide the list of engine names. This configuration MUST BE parsed as an array as string because the ordering of the configured entries is essential for the configuration.
-In addition it is possible to define Engines as optional. This allows to specify that the enhancement process should not fail if an Engine is not active or fails while processing a content item.
+In addition it is possible to define engines as optional. This allows to specify that the enhancement process should not fail if an engine is not active or fails while processing a content item.
-The syntax to define an Engine as optional is as follows
+The syntax to define an engine as optional is as follows below _(Both variants make the execution of the engine with the name <name> optional.)_:
:::text
<name>;optional
<name>;optional=true
-both variants result that the execution of the engine with the name <name> is optional.
-The following figure shows the configuration dialog for ListCahins as provided by the Apache Felix Web Console.
+The following figure shows the configuration dialog for ListChains as provided by the Apache Felix Web Console.
-
+
-It is also possible to configure a ListChain by directly installing a configuration with the name "{classname}-{configName}.config". Note that the {configName} needs not to be the same as the name of the chain. The {configName} is just used by the OSGI environment to distinguish different configuration for {classname}.
+It is also possible to configure a ListChain by directly installing a configuration with the name "{classname}-{configName}.config". Note that the {configName} needs not to be the same as the name of the chain. The {configName} is just used by the OSGI environment to distinguish different configurations for {classname}.
To create the same configuration as in the above screenshot the file would need to look like this:
:::properties
- stanbol.enhancer.chain.name="list"
+ stanbol.enhancer.chain.name="list"
stanbol.enhancer.chain.list.enginelist=["metaxa;optional","langid","ner","dbpediaLinking"]
-### Calculation of the ExecutionPlan
+## Calculation of the ExecutionPlan
-The ExecutionPlan is created based on the exact order of the [EnhancementEngine](../engines)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.
+The ExecutionPlan is created based on the exact order of the [EnhancementEngines](../engines) 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.
\ No newline at end of file
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=1292276&r1=1292275&r2=1292276&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 Wed Feb 22 13:25:13 2012
@@ -1,44 +1,43 @@
-Title: WeightedChain
+Title: Weighted Chain
-The Wighted Chain takes a list of [EnhancementEngine](../engines) names as input and uses the "org.apache.stanbol.enhancer.engine.order" metadata of the configured Engines to calculate the ExecutionPlan.
+The WeightedChain takes a list of [EnhancementEngine](../engines) names as input and uses the "org.apache.stanbol.enhancer.engine.order" metadata of the configured Engines to calculate an ExecutionPlan.
-This Chain is designed for easy configuration - just a list of the engine names - but has limited possibilities to control the execution order.
+This chain is designed for easy configuration - just a list of the engine names - but has limited possibilities to control the execution order.
-### Configuration
+## Configuration
-The property "stanbol.enhancer.chain.weighted.chain" is used to provide the list of engine names. Both Arrays and Collections are supported as values.
+The property "stanbol.enhancer.chain.weighted.chain" is used to provide the list of engine names. Both arrays and collections are supported as values.
-In addition it is possible to define Engines as optional. This allows to specify that the enhancement process should not fail if an Engine is not active or fails while processing a content item.
+In addition it is possible to define engines as optional. This allows to specify that the enhancement process should not fail if an engine is not active or fails while processing a content item.
-The syntax to define an Engine as optional is as follows
+The syntax to define an Engine as optional is as follows _(Both variants make the execution of the engine with the name <name> optional.)_:
:::text
<name>;optional
<name>;optional=true
-both variants result that the execution of the engine with the name <name> is optional.
-
+
-### Calculation of the ExecutionPlan
+## 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 [EnhancementEngine](../engines)s 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 [EnhancementEngines](../engines) is calculated only by using the value of 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.
+* Engines with a lower order are executed before engines with a higher value
+* Engines with the same order may be executed simultaneously if the EnhancementJobManager and the EnhancementEngine do support this feature.
The WeightedCahin follows exactly the same algorithm as the WeightedJobManager used to decide the execution order of all active EnhancementEngines. However the WeightedChain will only consider configured chains and ignore others.
-The following image shows the ExecutionPlan as calculated based on the above configuration
+The following image shows the ExecutionPlan as calculated based on the above configuration.
-
+
If some of the Enhancement Engines are not available this will be visualized as follows. If you parse content by using the RESTful interface similar information will be available via the the Execution Metadata included in the metadata of the enhanced content item.
-
+
This shows that the optional engine 'metaxa' is currently not available. The chain can be still used however the functionality provided by this optional engine will not be available. In this case only requests for plain text files could be processed.
-The following figure shows a situation where a required engine is not active. Requests to this chain will fail until all required engines are active.
+The next figure shows a situation where a required engine is not active. Requests to this chain will fail until all required engines are active.
-
+
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/contentitem.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/contentitem.mdtext?rev=1292276&r1=1292275&r2=1292276&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/contentitem.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/contentitem.mdtext Wed Feb 22 13:25:13 2012
@@ -57,7 +57,7 @@ returns the same blob instance.
The metadata of the ContentItem is managed by a lockable MGraph. This is basically a normal <code>java.util.Collections</code> for triples. The only RDF specific method is the support for filtered iterators which support wildcards for subjects, predicates and objects.
-This graph is used to store all enhancement results as well as metadata about the content item (such as content parts) and the enhancement process (see [execution metadata](executionmetadata.html).
+This graph is used to store all enhancement results as well as metadata about the content item (such as content parts) and the enhancement process (see [execution metadata](executionmetadata.html)).
### Read/Write locks
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/enhancementenginemanager.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/enhancementenginemanager.mdtext?rev=1292276&r1=1292275&r2=1292276&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/enhancementenginemanager.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/enhancementenginemanager.mdtext Wed Feb 22 13:25:13 2012
@@ -1,6 +1,6 @@
-Title: EnhancementEngineManager
+Title: Enhancement Engine Manager
-The EnhancementEngineManager provides name based access to all active [EnhancementEngine](index.html)s and their ServiceReferences. This interface is typically used by components that need to lookup EnhancementEngiens based on their name. However the EngineTracker implementation can also be used to track specific EnhancementEngines.
+The EnhancementEngineManager provides name based access to all active [EnhancementEngine](index.html)s and their ServiceReferences. This interface is typically used by components that need to lookup EnhancementEngines based on their name. However the EngineTracker implementation can also be used to track specific EnhancementEngines.
### EnhancementEngineManager interface
@@ -35,11 +35,11 @@ This is an implementation of the Enhance
@Reference
EnhancementEngineManager engineManager
-This service is provided by the "org.apache.stanbol.enhancer.enginemanger" module and is included in all Stanbol launchers.
+This service is provided by the "org.apache.stanbol.enhancer.enginemanager" module and is included in all Stanbol launchers.
#### EnginesTracker
-This is an Utility similar to the standard OSGI ServiceTracker that allows to track some/all EnhancementEngines. It also supports the usage of a ServiceTrackerCustomizer so that users of that utility can directly react to changes of tracked EnhancementEngines.
+This is an utility similar to the standard OSGI ServiceTracker which allows to track some/all EnhancementEngines. It also supports the usage of a ServiceTrackerCustomizer so that users of that utility can directly react to changes of tracked EnhancementEngines.
:::java
//track only "myEngine" and "otherEngine"
@@ -51,6 +51,6 @@ This is an Utility similar to the standa
tracker.close()
tracker = null;
-For most users the EnhancementEgingeManager service is sufficient and preferable. Direct use of the EngineTracker is only recommended if one needs only to track some specific engines and especially if one needs to get notified an changes of such engines.
+For most users the EnhancementEngineManager service is sufficient and preferable. Direct use of the EngineTracker is only recommended if one needs only to track some specific engines and especially if one needs to get notified an changes of such engines.
-The implementation of the [WeightedChain](http://svn.apache.org/repos/asf/incubator/stanbol/trunk/enhancer/chain/weighted/src/main/java/org/apache/stanbol/enhancer/chain/weighted/impl/WeightedChain.java) is a good example for the intended usage of the EnginesTracker.
+The implementation of the <code>[WeightedChain](http://svn.apache.org/repos/asf/incubator/stanbol/trunk/enhancer/chain/weighted/src/main/java/org/apache/stanbol/enhancer/chain/weighted/impl/WeightedChain.java)</code> is a good example for the intended usage of the EnginesTracker.
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/geonamesengine.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/geonamesengine.mdtext?rev=1292276&r1=1292275&r2=1292276&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/geonamesengine.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/geonamesengine.mdtext Wed Feb 22 13:25:13 2012
@@ -1,10 +1,10 @@
Title: The Geonames Enhancement Engine
-This engine creates fise:EntityAnnotations based on the http://geonames.org dataset. It does not directly work on the parsed content, but processes named entities extracted by some NLP (natural language processing) engine. This engine creates EnityAnnotations for Features found for named entities in the geonames.org data set. In addition it adds EntityAnnotations for the continent, country and administrative regions for entities with an high confidence level.
+This engine creates fise:EntityAnnotations based on the http://geonames.org dataset. It does not directly work on the parsed content, but processes named entities extracted by some NLP (natural language processing) engine. This engine creates EntityAnnotations for Features found for named entities in the geonames.org data set. In addition it adds EntityAnnotations for the continent, country and administrative regions for entities with an high confidence level.
## Processed Annotations (Input)
-This engine consumes fise:TextAnnotations of type dbpedia:Place. More concrete it filters for enhancements that confirm to the following two requirements and consumes the text selected by the TextAnnotations:
+This engine consumes fise:TextAnnotations of type dbpedia:Place. More concretely it filters for enhancements which confirm to the following two requirements and consumes the text selected by the TextAnnotations:
:::text
?textAnnotation rdf:type fise:TextAnnotation .
@@ -39,7 +39,7 @@ Typically such enhancements are created
The LocationEnhancementEngine creates two types of EntityAnnotations. First it suggests Entities for processed TextAnnotations and second it creates EntityAnnotations for the hierarchy of regions the suggested Entities are located in. Suggested Entities are connected with the "dc:relation" attribute to the TextAnnotation they enhance. EntityAnnotations representing the hierarchydefine a dc:requires attribute to the EntityAnnotation.
-###Entity Suggestions
+### Entity Suggestions
Entity suggestions are EntityEnhancements that suggest Features of the geonames.org dataset for an processed TextAnnotation. This suggestions are currently only calculated based on the fise:selected-text of the TextAnnotation.
@@ -144,7 +144,7 @@ Next the enhancement for the country "Au
urn:enhancement:entity-enhancement:id1 .
### A.ADM1 - A county
-Now three enhancement describing the different hierarchies of administrative regions within Austria. First the "Bundesland", next the "Stadtteil" and last the "Gemeindebezirk".
+Now three enhancements describing the different hierarchies of administrative regions within Austria. First the "Bundesland", next the "Stadtteil" and last the "Gemeindebezirk".
:::text
@@ -200,7 +200,7 @@ Now three enhancement describing the dif
The last two hierarchy levels are no longer valid for the meaning of "Vienna" as selected by the TextAnnotation, but added, because the geonames.org dataset locations the Feature of cities exactly in the center. However if the TextAnnotation would describe a precise address such hierarchy levels would completely make sense.
-##Configuration
+## Configuration
The LocationEnhancementEngine provides six configurations
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/index.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/index.mdtext?rev=1292276&r1=1292275&r2=1292276&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/index.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/index.mdtext Wed Feb 22 13:25:13 2012
@@ -1,8 +1,8 @@
Title: Enhancement Engines
-Enhancement engines are the components that are responsible to enhance [content items](../contentitem.html). They are called by the [Enhancement Job Manager](../enhancementjobmanager.html). Enhancement engines do have full access to the parsed content items. They are expected to modify their state.
+Enhancement engines are the components responsible to enhance [content items](../contentitem.html). They are called by the [Enhancement Job Manager](../enhancementjobmanager.html). Enhancement engines do have full access to the parsed content items. They are expected to modify their state.
-The RESTful interface of an enhancement engine can be accessed by
+The RESTful interface of an enhancement engine can be accessed via
:::text
http://{host}:{port}/{stanbol-root}/enhancer/engine/{engine-name}
@@ -12,7 +12,7 @@ e.g. an enhancement engine with the name
:::text
http://localhost:8080/enhancer/engine/ner
-When using the Java API enhancement engines can be liked up as OSGI services. The [Enhancement Engine Manager](enhancementenginemanager.html) service is designed to ease this by providing a API that allows to access enhancement engine by their name.
+When using the Java API, enhancement engines can be linked up as OSGI services. The [Enhancement Engine Manager](enhancementenginemanager.html) service is designed to ease this by providing an API that allows to access enhancement engine by their name.
## Enhancement Engine Interface
@@ -24,7 +24,7 @@ The interface for enhancement engines co
/** Checks if this engine can enhance the parsed content item */
+ canEnhance(ContentItem ci) : int
/** Enhances the parsed content item */
- + computeEnhacements(ContentItem ci)
+ + computeEnhancements(ContentItem ci)
/** The property used for the name of an engine */
PROPERTY_NAME : String
@@ -40,11 +40,11 @@ Each enhancement engine has a name. This
:::java
this.name = (String)ComponentContext.getProperties(EnhancementEngine.PROPERTY_NAME);
-The <code>canEnahnce(ContentItem ci)</code> method is used by the [Enhancement Job Manager](../enhancementjobmanager.html) to check if an engine is able to process a [Content Item](../contentitem.html). Calling this method MUST NOT change the state of the content item and this method MUST also NOT acquire a write lock on the content item.
+The <code>canEnhance(ContentItem ci)</code> method is used by the [Enhancement Job Manager](../enhancementjobmanager.html) to check if an engine is able to process a [Content Item](../contentitem.html). Calling this method MUST NOT change the state of the content item and this method MUST also NOT acquire a write lock on the content item.
-The <code>computeEnhacements(ContentItem ci)</code> starts the processing of the parsed content item by the engine. It is expected to change the state of the parsed content item. Engines that support asynchronous processing need to take care to correctly apply read/write locks when reading/writing information from/to the content item. Engines that return <code>ENHANCE_SYNCHRONOUS</code> on calls to <code>canEnhance(..)</code> do not need to use locks. They can trust that they have exclusive read/write access to the content item.
+The <code>computeEnhancements(ContentItem ci)</code> starts the processing of the parsed content item by the engine. It is expected to change the state of the parsed content item. Engines that support asynchronous processing need to take care to correctly apply read/write locks when reading/writing information from/to the content item. Engines that return <code>ENHANCE_SYNCHRONOUS</code> on calls to <code>canEnhance(..)</code> do not need to use locks. They can trust that they have exclusive read/write access to the content item.
-Enhancement engins do have full access to the content item. Theoretically, they would be even allowed to delete all metadata as well as all content parts from the parsed content item. However typically the do only
+Enhancement engines do have full access to the content item. Theoretically, they would be even allowed to delete all metadata as well as all content parts from the parsed content item. However typically the do only
* read existing content parts
* add new content parts
@@ -55,7 +55,7 @@ Both the <code>canEnhance(..)</code> and
### Services Properties Interface
-This interface is implemented by most of the current enhancement engines. It allows engines to expose additional properties to other component. This interface defines a single method
+This interface is implemented by most of the current enhancement engines. It allows engines to expose additional properties to other components. This interface defines a single method
:::java
/** Getter for the ServiceProperties */
@@ -65,7 +65,7 @@ but also predefines the property <code>E
### Engine Ordering Information
-By implementing the ServicesProperties interface enhancement engines do have the possibility to expose additional metadata to other components. The services properties interface defines only a single method
+By implementing the ServicesProperties interface, enhancement engines do have the possibility to expose additional metadata to other components. The services properties interface defines only a single method
:::java
/** Getter for the ServiceProperties */
@@ -73,15 +73,15 @@ By implementing the ServicesProperties i
and is implemented by most of the current enhancement engines. Its currently only use is to provide information about the engine ordering within the enhancement process. This information is exposed by using the key "org.apache.stanbol.enhancer.engine.order" that is defined as value by the constant <code>ENHANCEMENT_ENGINE_ORDERING</code> defined directly by the services properties interface. Values are expected to be integer within the ranges
-* __ORDERING_PRE_PROCESSING__: All values >= 200 are considered for engines that do some kind of preprocessing of the Content. This includes e.g. the conversation of media formats such as extracting the plain text from HTML, keyframes from videos, wave form from mp3 ...; extracting metadata directly encoded within the parsed content such as ID3 tags from MP3 or RDFa, microdata provided by HTML content.
-* __ORDERING_CONTENT_EXTRACTION__: This range includes values form < 200 and >= 100 and shall be used by enhancement engine that need to analyze the parsed content to extract additional metadata. Examples would be Language detection, Natural Language Processing, Named Entity Recognition, Face Detection in Images, Speech to text â¦
+* __ORDERING_PRE_PROCESSING__: All values >= 200 are considered for engines that do some kind of preprocessing of the content. This includes e.g. the conversion of media formats such as extracting the plain text from HTML, keyframes from videos, wave form from mp3 ...; extracting metadata directly encoded within the parsed content such as ID3 tags from MP3 or RDFa, microdata provided by HTML content.
+* __ORDERING_CONTENT_EXTRACTION__: This range includes values form < 200 and >= 100 and shall be used by enhancement engines that need to analyze the parsed content to extract additional metadata. Examples would be Language detection, Natural Language Processing, Named Entity Recognition, Face Detection in Images, Speech to text â¦
* __ORDERING_EXTRACTION_ENHANCEMENT__: This range includes values from < 100 and >= 1 and shall be used by enhancement engines to provide semantic lifting of preexisting enhancement such as linking named entities extracted by an NER engine with entities defines in a controlled vocabulary or lifting artist names, song titles ... extracted from mp3 files with the according Entities defined in an music database.
* __ORDERING_DEFAULT__: This represents the value 0 and shall be used as default value for all enhancement engines that do not provide ordering information or do not implement the ServicesProperties interface.
* __ORDERING_POST_PROCESSING__: This range includes valued form < 0 and >= -100 and is intended to be used by all enhancement engines that do post processing of enhancement results such as schema translation, filtering of Enhancements ...
The engine ordering information as described here are used by the [Default Chain](../chains/defaultchain.html) and the [Weighted Chain](../chains/weightedchain.html) to calculate the [Execution Plan](../chains/executionplan.html).
-Basically this features allows the implementor of an enhancement engine to define the correct position of his engine within an typical enhancement chain and therefore ensure that users that add this engine to a enhancer installation to immediately use this engine with the [Default Chain](../chains/defaultchain.html).
+Basically this features allows the implementor of an enhancement engine to define the correct position of his engine within an typical enhancement chain and therefore ensure that users who add this engine to an enhancer installation to immediately use this engine with the [Default Chain](../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 [List Chain](../chains/listchain.html) and the [Graph Chain](../chains/graphchain.html) do also allow to directly define the oder of execution. For these chains the ordering information provided by enhancement engines are ignored.
@@ -92,11 +92,11 @@ This section describes how enhancement e
Enhancement engines are registered as OSGi services and managed by using the following service properties:
-* __Name:__ Defined by the value of the property "stanbol.enhancer.engine.name" it will be used to access Engines on the Stanbol RESTful interface
+* __Name:__ Defined by the value of the property "stanbol.enhancer.engine.name" it will be used to access engines on the Stanbol RESTful interface
* __Service Ranking:__ The service ranking property defined by OSGI will be used to decide which engine to use in case several active enhancement engines do use the same name. In such cases only the Engine with the highest ranking will be used to enhance ContentItems.
<!-- TODO: The Configuration is not yet defined
-* __Configuration:__ Each EnhacementEngien MAY provide an RDF graph with its configuration. This graph will be returned on GET request on the URL of the enhancement engine. If no configuration is known for the engine this MUST at least return a single triple with the name for the engine.
+* __Configuration:__ Each EnhancementEngine MAY provide an RDF graph with its configuration. This graph will be returned on GET request on the URL of the enhancement engine. If no configuration is known for the engine this MUST at least return a single triple with the name for the engine.
_TODO:_ To correctly construct this graph the Engine needs to know this URL. This could e.g. be provided by some OSGI environment parameter set by the JerseyApplication. As an alternative we could also parse this URI as an parameter to the getEngineConfig method.
-->
@@ -105,14 +105,14 @@ Other components such as enhancement cha
### Enhancement Engine Name Conflicts
-As enhancement engines are identified by the value of the "stanbol.enhancer.engine.name" property - the name - there might be cases where multiple enhancement engine are registered for the same name. In such cases the normal OSGi procedure to select the default service instance of several possible matches is used. This means that
+As enhancement engines are identified by the value of the "stanbol.enhancer.engine.name" property - the name - there might be cases where multiple enhancement engine are registered with the same name. In such cases the normal OSGi procedure to select the default service instance of several possible matches is used. This means that
1. the enhancement engine with the highest "service.ranking" and
2. the enhancement engine with the lowest "service.id"
will be selected on requests for a enhancement engine with a given name. Requests on the RESTful service API will always answer with the enhancement engine selected as default. When using the Java API there are also means to retrieve all enhancement engines for a given name via the [Enhancement Engine Manager](enhancementenginemanager.html) interface.
-Out of a user perspective there is one major use case for configuring multiple enhancement engines for the same name. This is to allow the definition of fallback engines if the main one becomes unavailable. e.g. lets assume that a user has a local cache of geonames.org loaded into the [Entityhub](../../entityhub/) and configures an [Named Entity Linking](keywordlinkingengine.html) engine to perform semantic lifting of extracted locations. However Apache Stanbol also provides the [geonames.org Engine](geonamesengine.html) that provides a similar functionality by directly accessing [geonames.org](http://geonames.org). By configuring both engines for the same name, but specifying a higher service ranking for the one using the local cache one can ensure that the local cache is used for the enhancement under normal circumstances. However in case the local cache becomes unavailable the other engine using the remote service will be used for enhancement.
+Out of a user perspective there is one major use case for configuring multiple enhancement engines with the same name. This is to allow the definition of fallback engines if the main one becomes unavailable. E.g. lets assume that a user has a local cache of geonames.org loaded into the [Entityhub](../../entityhub/) and configures an [Named Entity Linking](keywordlinkingengine.html) engine to perform semantic lifting of extracted locations. However Apache Stanbol also provides the [geonames.org Engine](geonamesengine.html) that provides a similar functionality by directly accessing [geonames.org](http://geonames.org). By configuring both engines for the same name, but specifying a higher service ranking for the one using the local cache one can ensure that the local cache is used for the enhancement under normal circumstances. However in case the local cache becomes unavailable the other engine using the remote service will be used for enhancement.
### Enhancement Engine Manager Interface
@@ -120,12 +120,7 @@ The [Enhancement Engine Manager](enhance
## Enhancement Engine Implementations
-A list of enhancement engine implementations maintained directly by the Apache Stanbol community can be found [here](engines/list.html).
+A list of enhancement engine implementations maintained directly by the Apache Stanbol community can be found [here](list.html).
However the enhancement engine interface is designed in a way that it should be possible for advanced Apache Stanbol users to implement own enhancement engine implementations fulfilling their special needs.
-The Apache Stanbol community would be very happy if users decide to share thoughts about possible enhancement engines or even would like to contribute addition engines to the Apache Stanbol project.
-
-
-
-
-
+The Apache Stanbol community would be very happy if users decide to share thoughts about possible enhancement engines or even would like to contribute additional engines to the Apache Stanbol project.
\ No newline at end of file
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/keywordlinkingengine.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/keywordlinkingengine.mdtext?rev=1292276&r1=1292275&r2=1292276&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/keywordlinkingengine.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/engines/keywordlinkingengine.mdtext Wed Feb 22 13:25:13 2012
@@ -1,10 +1,10 @@
Title: The Keyword Linking Engine: custom vocabularies and multiple languages
-The [KeywordLinkingEngine](http://svn.apache.org/repos/asf/incubator/stanbol/trunk/enhancer/engines/keywordextraction/) is a re-implementation of the [TaxonomyLinkingEngine](http://svn.apache.org/repos/asf/incubator/stanbol/trunk/enhancer/engines/taxonomylinking/) that is more modular and therefore better suited for future improvements and extensions as requested by [STANBOL-303](https://issues.apache.org/jira/browse/STANBOL-303).
+The [KeywordLinkingEngine](http://svn.apache.org/repos/asf/incubator/stanbol/trunk/enhancer/engines/keywordextraction/) is a re-implementation of the [TaxonomyLinkingEngine](http://svn.apache.org/repos/asf/incubator/stanbol/trunk/enhancer/engines/taxonomylinking/) which is more modular and therefore better suited for future improvements and extensions as requested by [STANBOL-303](https://issues.apache.org/jira/browse/STANBOL-303).
Currently the main advantage of using this engine is its ability to support multiple languages and provide enhancement results specific to custom vocabulary.
-## Multiple Language Support ##
+## Multiple Language Support
The KeywordLinkingEngine supports the extraction of keywords in multiple languages. However, the performance and to some extend also the quality of the enhancements depend on how well a language is supported by the used NLP framework (currently OpenNLP).
The following list provides a short overview about the different language specific component/configurations: