Author: rwesten
Date: Wed Feb 15 07:29:20 2012
New Revision: 1244385
URL: http://svn.apache.org/viewvc?rev=1244385&view=rev
Log:
Added Documentation of the MultiPart MIME serialisation for ContentItems; Added
Figures for ExecutionMetadata and ExecutionPlan
Added:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.png
(with props)
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/contentitemmultipartmime.png
(with props)
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.png
(with props)
Modified:
incubator/stanbol/site/trunk/ (props changed)
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/contentitem.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.mdtext
Propchange: incubator/stanbol/site/trunk/
------------------------------------------------------------------------------
--- svn:ignore (added)
+++ svn:ignore Wed Feb 15 07:29:20 2012
@@ -0,0 +1,3 @@
+.project
+
+.settings
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=1244385&r1=1244384&r2=1244385&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 15 07:29:20 2012
@@ -6,6 +6,8 @@ The ExecutionPlan is represented as an R
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:hasExecutionNode__ (domain: ep:ExecutionPlan; range:
ep:ExecutionNode; inverseOf: ep:inExecutionPlan): links the execution plan with
all the execution nodes.
Added:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.png
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.png?rev=1244385&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/chains/executionplan.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
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=1244385&r1=1244384&r2=1244385&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 15 07:29:20 2012
@@ -83,3 +83,49 @@ However, whenever components need to ens
}
While accessing content items within an [enhancement
engine](engines/enhancementengine.html) there is an exception to this rule. If
an engine declares that is only supports the <code>SYNCHRONOUS</code>
enhancement mode the [enhancement job manager](enhancementjobmanager.html)
needs to take care the an engine has exclusive access to the content item. In
that case implementors of enhancement engines need not to care about using
read/write locks.
+
+## Multipart MIME serialization
+
+Stanbol supports the serialization of ContentItems as Multipart MIME. This
serialization is used by the RESTful API of the Stanbol Enhancer. This section
provides details about how ContentItems are represented using Multipart MIME.
For more information on how to send/receive multipart content items via the
RESTful Serivces provided by the Stanbol Enhancer please see the documentation
provided in the Web Interface (e.g. http://localhost:8080/enhancer).
+
+The following figure provides an overview on how ContentItems are represented
using MultiPart MIME.
+
+
+
+Serialization Rules:
+
+* ContentItems are con tainted within an "multipart/from-data" container
+* Apache Stanbol uses "contentItem" as "boundary", but users may use any as
long as the "boundary" parameter in the "Content-Type" header is set correctly.
+* Stanbol uses UTF-8 as charset, but users might use any supported encoding as
long as the "charset" parameter in the "Content-Type" header is set accordingly.
+
+The default Content-Type for serialized ContentItems is therefore
"multipart/form-data; boundary=contentItem; charset=UTF-8"
+
+### Metadata:
+
+* If present this MUST BE the first MIME part within the "multipart/from-data"
container representing the ContentItem.
+* The "name" parameter of the "Content-Disposition" header MUST BE "metadata"
+* If the "fileName" parameter of the "Content-Disposition" header is present
it MUST BE the URI of the ContentItem. Users are typically required to set this
header in case the want to parse existing metadata with enhancement requests.
This is because is such cases it is important that the URI of the ContentItem
created by the Stanbol Enhancer is equals to the URI used to describe the
Content within the parsed Metadata. The Stanbol Enhancer MUST set to "fileName"
parameter of the metadata to the URI of the processed ContentItem.
+* The "Content-Type" of the metadata can be any RDF serialization supported by
Apache Stanbol. UTF-8 is used as default charset.
+* The RDF data serialized in this MIME part represent the enhancement results.
+
+### Content
+
+* If present the MIME part representing the Content MUST directly follow the
Metadata. If the Metadata are not present the Content MUST BE the first MIME
part within the "multipart/from-data" container representing the ContentItem.
+* Because multiple Content variants can be included within a ContentItem a
"multipart/alternate" container is used to represent the content.
+* The "name" parameter of the "Content-Disposition" header MUST BE "content".
The "fileName" parameter is not used and therefore not present/ignored. The
Stanbol Enhancer uses "contentParts" as boundary but users may use any boundary
as long as it is correctly set within the "Content-Type" header.
+
+The different content elements are contained within the "multipart/from-data"
container. The ordering is important. For serialized ContentItems it is assumed
that the first element is the original document for the ConentItem. All further
MIME parts are considered alternate - e.g. transcoded/transformed - versions.
For serialized ContentItems provided as Response to requests to the Stanbol
Enhancer the ordering of the MIME parts is the same as the indexes of the
ContentParts in the ContentItem.
+
+* the "name" parameter of the "Content-Disposition" is set to the URI of the
ContentPart in the ContentItem.
+* the "Content-Type" header must correspond to the media type of the content
+
+Note that users that want to send a single ContentPart AND Metadata to the
Stanbol Enhancer can also directly add the content to the "multipart/from-data"
container of the ContentItem. In this case the "name" parameter MUST BE still
set to "content" but the "Content-Type" header needs to be directly set to the
media type of the parsed ContentPart. The Stanbol Enhancer does NOT use this
option when serializing ContentItems. It will ALWAYS use a
"multipart/alternate" container for the "content" even when only a single
ContnetPart is included in an Response.
+
+### Additional Metadata
+
+The [ContentPart API](#contentparts) of the Stanbol ContentItem allows to
register content parts of any type. The MultiPart MIME serialization of
ContentItems supports the serialization of such additional parts as long as
they are encoded as RDF graphs (compatible to the Clerezza TripleCollection
class). Additional ContentParts that are not encoded as RDF data are currently
not supported by the Multipart MIME serialization.
+
+* MimeParts representing such ContentParts MUST BE added after the MIME parts
for the "metadata" AND the "content"
+* The "name" parameter of the "Content-Disposition" MUST BE set to the URI of
the ContentPart in the ContentItem.
+* the "Content-Type" header must correspond to the media type of the content.
The Stanbol Enhancer will always use the same RDF serialization as for the
"metadata" when serializing additional Metadata. Users are free to use any
supported serialization as long as they set the "Content-Type" header
accordingly.
+* The ordering of parts representing additional Metadata is the same as the
ordering (index) of the ContentParts in the ContentItem.
Added:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/contentitemmultipartmime.png
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/contentitemmultipartmime.png?rev=1244385&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/contentitemmultipartmime.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
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=1244385&r1=1244384&r2=1244385&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
Wed Feb 15 07:29:20 2012
@@ -11,6 +11,8 @@ The execution metadata provide detailed
The RDFS schema used for the execution plan is defined as follows.
+
+
* 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
Added:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.png
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.png?rev=1244385&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/executionmetadata.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
