You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by rw...@apache.org on 2012/03/05 14:47:08 UTC
svn commit: r1297053 - in
/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer:
enhancerrest.mdtext executionmetadata.mdtext
Author: rwesten
Date: Mon Mar 5 13:47:08 2012
New Revision: 1297053
URL: http://svn.apache.org/viewvc?rev=1297053&view=rev
Log:
Updated Documentation of the Enhancer RESTful services by the new features introduced by STANBOL-431
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancerrest.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.mdtext
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancerrest.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancerrest.mdtext?rev=1297053&r1=1297052&r2=1297053&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancerrest.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancerrest.mdtext Mon Mar 5 13:47:08 2012
@@ -7,6 +7,7 @@ The RESTful interface described below is
* __'/enhancer':__ The main endpoint of the Stanbol Enhancer. Parsed content will get enhanced by using the default enhancement chain.
* __'/enhancer/chain/{chain-name}'__: The Stanbol Enhancer supports the configuration of multiple [Enhancement Chains](chains). Users can lookup active chains by requests to the 'enhancer/chain' endpoint.
+* __'/enhancer/engine/{engine-name}'__: This can be used to enhance parsed Content with a single [Enhancement Engine](engines). Note that the parsed Content MUST be processable by the referenced engine. So if the engine is not able to directly process the parsed content you might need to send existing metadata such as explained in the section [Parsing multiple ContentParts](#parsing_multiple_contentparts). This feature is e.g. useful to directly send a MP3 file to the [TikaEnigne](engines/tikaengine.html) to extract the metadata.
* __'/engines':__ Same as '/enhancer' this ensures backward compatibility to older Stanbol versions.
## Basic Enhancement Service
@@ -47,6 +48,64 @@ In addition this request is directed to
and people such as Bob Marley." \
"http://localhost:8080/enhancer/chain/dbpedia-keyword?uri=urn:fise-example-content-item&executionmetadata=true"
+## Enhancer Configuration
+
+The Stanbol Enhancer supports several RESTful services to inspect the configuration. This services allow to retrieve currently active [Enhancement Engines](engines) and [Enhancement Chains](chains).
+
+* __'/enhancer':__ GET requests to the main Stanbol Enhancer endpoint the do used an 'Accept' header compatible to one of the supported RDF serializations will return the current configuration as RDF.
+* __'/enhancer/engine':__ Same as above however the response will only include active enhancement engines
+* __'/enhancer/chain':__ Returns the currently active enhancement chains.
+* __'/enhancer/sparql':__ SPARQL endpoint that allows to query the configuration.
+
+Example Response as 'application/rdf' serialization of the default configuration of the Stanbol Enhancer.
+
+The request
+
+ :::bash
+ curl -v -X GET -H "Accept: application/rdf+xml" "http://localhost:8080/enhancer/ep"
+
+returns the following results
+
+ :::xml
+ <rdf:RDF
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:j.0="http://stanbol.apache.org/ontology/enhancer/enhancer#"
+ xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" >
+ <rdf:Description rdf:about="http://localhost:8080/enhancer/engine/langid">
+ <rdfs:label>langid</rdfs:label>
+ <rdf:type rdf:resource="http://stanbol.apache.org/ontology/enhancer/enhancer#EnhancementEngine"/>
+ </rdf:Description>
+ <rdf:Description rdf:about="http://localhost:8080/enhancer">
+ <rdf:type rdf:resource="http://stanbol.apache.org/ontology/enhancer/enhancer#Enhancer"/>
+ <j.0:hasEngine rdf:resource="http://localhost:8080/enhancer/engine/dbpediaLinking"/>
+ <j.0:hasEngine rdf:resource="http://localhost:8080/enhancer/engine/langid"/>
+ <j.0:hasEngine rdf:resource="http://localhost:8080/enhancer/engine/entityhubLinking"/>
+ <j.0:hasEngine rdf:resource="http://localhost:8080/enhancer/engine/tika"/>
+ <j.0:hasEngine rdf:resource="http://localhost:8080/enhancer/engine/metaxa"/>
+ <j.0:hasEngine rdf:resource="http://localhost:8080/enhancer/engine/ner"/>
+ <j.0:hasChain rdf:resource="http://localhost:8080/enhancer/chain/default"/>
+ <j.0:hasDefaultChain rdf:resource="http://localhost:8080/enhancer/chain/default"/>
+ <j.0:hasChain rdf:resource="http://localhost:8080/enhancer/chain/language"/>
+ </rdf:Description>
+ <rdf:Description rdf:about="http://localhost:8080/enhancer/chain/language">
+ <rdfs:label>language</rdfs:label>
+ <rdf:type rdf:resource="http://stanbol.apache.org/ontology/enhancer/enhancer#EnhancementChain"/>
+ </rdf:Description>
+ <rdf:Description rdf:about="http://localhost:8080/enhancer/engine/ner">
+ <rdf:type rdf:resource="http://stanbol.apache.org/ontology/enhancer/enhancer#EnhancementEngine"/>
+ <rdfs:label>ner</rdfs:label>
+ </rdf:Description>
+ [...]
+ </rdf:RDF>
+
+### Executionplan of Enhancement Chains
+
+The [ExecutionPlan](chains/executionplan.html) can be also requested by sending a GET request with an supported RDF serialization as 'Accept' header to
+
+* __'/enhancer/ep'__
+* __'/enhancer/chain/{chain-name}/ep'__
+* __'/engines/ep'__
+
## Multi-part ContentItem support
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.mdtext?rev=1297053&r1=1297052&r2=1297053&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.mdtext Mon Mar 5 13:47:08 2012
@@ -1,6 +1,6 @@
Title: Execution Metadata
-The execution metadata holds detailed information about an ongoing/completed enhancement process. Basically they describe how the [ExecutionPlan](chains/executionplan.html) provided by the [Chain](chains) was executed by the [EnhancementJobManager](enhancementjobmanager.html). Both the ExecutionMetadata and the ExecutionPlan are provided with the ContentItem as an own content part of the type MGraph with the URI "http://stanbol.apache.org/ontology/enhancer/executionMetadata#ChainExecution". For users of the Stanbol Enhancer the Execution Metadata are of interest to:
+The execution metadata holds detailed information about an ongoing/completed enhancement process. Basically they describe how the [ExecutionPlan](chains/executionplan.html) provided by the [Chain](chains) was executed by the [EnhancementJobManager](enhancementjobmanager.html). Both the ExecutionMetadata and the ExecutionPlan are provided with the ContentItem as an own content part of the type MGraph with the URI "http://stanbol.apache.org/ontology/enhancer/executionmetadata#ChainExecution". For users of the Stanbol Enhancer the Execution Metadata are of interest to:
* check progress of asynchronously started Enhancement Processes: Metadata for all planed executions of engines are created as soon as an ContentItem is parsed to the EnhancementJobManager and are updated as soon as the execution of engines start/complete/fail.
* Monitor the performance of different EnhancementEngines: The Execution Metadata provide detailed information about starting/completion time points for engine executions.
@@ -13,7 +13,7 @@ The RDFS schema used for the execution p
- * Namespace: em : http://stanbol.apache.org/ontology/enhancer/executionMetadata#
+ * Namespace: em : http://stanbol.apache.org/ontology/enhancer/executionmetadata#
* __em:Execution__ : Super class for all Executions
* __em:executionPart__ (domain:Execution, range: em:ChainExecution): Defines that this execution was part of the execution of a chain
* __em:status__(domain: em:Execution; range: em:ExecutionStatus): The status of an execution (used for both em:EngineExecution and em:ChainExecution
@@ -130,7 +130,7 @@ The Execution Plan: (copy from the examp
This section is primarily intended for implementors of EnhancementJobManager. However it might also provide insights for users that want/need to monitor the state of enhancement processes as it describes what information are added when to the Execution Metadata.
-When the [EnhancementJobManager](enhancementjobmanager.html) starts the Enhancement of a ContentItem it needs to check if the [ContentItem](contentitem.html) already contains ExecutionMetadata in the ContentPart with the URI "http://stanbol.apache.org/ontology/enhancer/executionMetadata#ChainExecution". If this is the case it needs to initialize itself based on the pre-existing information. If no ExecutionMetadata are present, a new EnhancementProcess needs to be created based on the parsed Chain. Differences between this two cases are explained in the following two sub sections.
+When the [EnhancementJobManager](enhancementjobmanager.html) starts the Enhancement of a ContentItem it needs to check if the [ContentItem](contentitem.html) already contains ExecutionMetadata in the ContentPart with the URI "http://stanbol.apache.org/ontology/enhancer/executionmetadata#ChainExecution". If this is the case it needs to initialize itself based on the pre-existing information. If no ExecutionMetadata are present, a new EnhancementProcess needs to be created based on the parsed Chain. Differences between this two cases are explained in the following two sub sections.
### Initialization
@@ -144,7 +144,7 @@ The ExecutionMetadataHelper utility of t
### Continuation
-If the parsed ContentItem does already contain ExecutionMetadata in the content part with the URI "http://stanbol.apache.org/ontology/enhancer/executionMetadata#ChainExecution" the EnhancementJobManager MUST follow the following steps to continue an EnhancementProcess.
+If the parsed ContentItem does already contain ExecutionMetadata in the content part with the URI "http://stanbol.apache.org/ontology/enhancer/executionmetadata#ChainExecution" the EnhancementJobManager MUST follow the following steps to continue an EnhancementProcess.
1. Check if the contained ExecutionMetadata are valid
* If a 'em:ChainExecution' node is present that 'em:enhances' the parsed ContentItem
@@ -196,7 +196,7 @@ This section provides some examples on h
### Accessing ExecutionMetadata
-The ExecutionMetadata and the [ExecutionPlan](chains/executionplan.html) are stored in a content part with with URI "http://stanbol.apache.org/ontology/enhancer/executionMetadata#ChainExecution" with the [ContentItem](contentitem.html). The following code segment can be used to retrieve the RDF graph with the ExecutionMetadata:
+The ExecutionMetadata and the [ExecutionPlan](chains/executionplan.html) are stored in a content part with with URI "http://stanbol.apache.org/ontology/enhancer/executionmetadata#ChainExecution" with the [ContentItem](contentitem.html). The following code segment can be used to retrieve the RDF graph with the ExecutionMetadata:
:::java
ContentItem ci; //the ContentItem