Author: rwesten
Date: Tue Jan 31 09:03:51 2012
New Revision: 1238288
URL: http://svn.apache.org/viewvc?rev=1238288&view=rev
Log:
updates regarding execution metadata
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.mdtext
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.mdtext?rev=1238288&r1=1238287&r2=1238288&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementjobmanager.mdtext
Tue Jan 31 09:03:51 2012
@@ -20,19 +20,20 @@ Note that the parsed ContentItem will be
While the [ExecutionPlan](chains/executionplan.html) defines what
EnhancementEgnies are used and how they depend on each the
EnhancementJobManager is responsible for the actual execution of the
enhancement process based on this plan. This section provides detailed
information about requirements and expectations that MUST BE considered.
-The EnhancementJobManager is also responsible to create and update the
[ExecutionMetadata](executionmetadata.html) in the metadata of the processed
[ContentItem](contentitem.html).
+The EnhancementJobManager is also responsible to create and update the
[ExecutionMetadata](executionmetadata.html) in the metadata of the processed
[ContentItem](contentitem.html). Details about this are provided in the section
"[Creation/Management of
ExecutionMetadata](executionmetadata.html#creationmanagement_of_executionmetadata)"
of the ExecutionMetadata documentation.
-### Retrieving the ExecutionPlan
+### Initializing the Enhancement Process
-The [ExecutionPlan](chains/executionplan.html) is provided by the Chain in a
final graph that is guaranteed to be not changed. However because the
configuration of a Chain might be change at any time the EnhancementJobManager
MUST retrieve the execution plan only once and used it during the whole
enhancement process.
+Here one needs to distinguish two costs:
-Before the start of the enhancement process the EnhancementJobManager needs
first to initialize the [ExecutionMetadata](executionmetadata.html) for the
[ContentItem](contentitem.html). This includes
+1. Initialisation of an new Enhancement process and
+2. Continuation of an existing Enhancement process.
-1. copying the execution plan as returned by the Chain to the metadata of the
content item
-2. create an 'em:ChainExecutin' instance and set the 'em:enhances' property to
the URI of the ContentItem
-3. creating 'em:EngineExecution' instances for all 'ep:ExecutionNodes' and set
the 'em:status' of those to 'em:StatusSheduled'. Also define such instances as
'em:executionPart' to the chain execution and link them to the according
execution node of the execution plan.
+The two cases can be easily detected by the EnhancementJobManager by
evaluating if a content part with the URI
"http://stanbol.apache.org/ontology/enhancer/executionMetadata#ChainExecution";
is present within the parsed [ContentItem](contentitem.html).
-See the documentation of the [ExecutionMetadata](executionmetadata.html) for
more information.
+In the first case the [ExecutionPlan](chains/executionplan.html) to be used by
for the enhancement process is provided by the Chain in a final graph that is
guaranteed to be not changed. However because the configuration of a Chain
might be change at any time the EnhancementJobManager MUST retrieve the
execution plan only once and used it during the whole enhancement process. In
addition the ExecutionPlan MUST BE also added to the graph containing the
[EnahcementMetadata](executionmetadata.html). In case of continuing on an
previously aborted enhancement process the ExecutionPlan MUST BE initialized
from the ExecutionMetadata provided by the ContentItem.
+
+For details on how to initialize/load the execution metadata see the section
"[Creation/Management of
ExecutionMetadata](executionmetadata.html#creationmanagement_of_executionmetadata)"
of the ExecutionMetadata documentation.
### Engine Execution
@@ -55,16 +56,20 @@ This code snippet assumes to be called a
} // else already running -> ignore
}
+_NOTE_ that the NonLiterals contained in the two collections are
'ep:ExecutionNode' instances and NOT 'em:EngineExecution' instances. Each
'em:EngineExecution' instance in the the ExecutionMetadata' is linked by the
'em:executionNode' property to the corresponding 'ep:ExecutionNode' of the
ExecutionPlan.
+
Before executing an [EnhancementEngine](engines/enhancementengine.html) the
EnhancementJobManager needs to check if and how the engine can enhance a
content item. This is indicated by the integer returned by the
"canEnhance(ContentItem ci)" method:
-* __CANNOT_ENHANCE__: Indicates that this engines can not process the parsed
content item. In this case the EnhancementJobManager needs to skip this engine
and mark the EngineExectuion as skipt with a status message that the
EnhancementEngine was unable to process the content item. If this engine is
marked as optional the enhancement process can continue if not, than the
execution MUST be marked as failed and an according Exception needs to be
thrown.
+* __CANNOT_ENHANCE__: Indicates that this engines can not process the parsed
content item. In this case the EnhancementJobManager needs to skip this engine
and mark the EngineExectuion as skipped with a status message that the
EnhancementEngine was unable to process the content item. If this engine is
marked as optional the enhancement process can continue if not, than the
execution MUST be marked as failed and an according Exception needs to be
thrown.
* __ENHANCE_SYNCHRONOUS__: Indicates that the engines needs exclusive access
to the parsed content item. The EnhancementJobManager needs to ensure that in
some way. Typically by calling the "computeEnhancement(ContentItem ci)" method
within an write lock.
* __ENHANCE_ASYNC__: Indicates that this engine supports asynchronous
execution and takes itself care to acquire read and write locks on the parsed
content item. However this does not require the JobManager to execute the
engine asynchronously.
-If the execution of an EnhancementEngine completes the JobManager needs to set
the state of the execution to completed and update the other metadata
accordingly.
+If the execution of an EnhancementEngine completes the JobManager needs to set
the state of the execution to completed and update the execution metadata
accordingly.
If a call to "computeEnhancement(ContentItem ci)" results in an Exception the
EnhancementJobManager must mark the execution of the engine as failed with a
decryption of the occurred exception. If the the execution of the affected
engine was optional the enhancement process is continued. Otherwise the
enhancement process needs to be stopped and the Error needs to rethrown by the
"enhanceContent(..)" method.
+For all the details on how to reflect state changes in the Execution metadata
see [this section](executionmetadata.html#execution_state_management) of the
documentation of the ExecutionMetadata.
+
### Multi Threaded enhancement processes
In case the EnhancementJobManager supports to simultaneously call
[EnhancementEngine](engines/enhancementengine.html)s for the same content item
in multiple threads it is important to correctly use the ReadWriteLock as
provided by the ContentItem.getLock() method.
