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
