Author: rwesten
Date: Wed Jan 11 17:37:32 2012
New Revision: 1230164
URL: http://svn.apache.org/viewvc?rev=1230164&view=rev
Log:
Updated EnhancementEngineManager section with the EngineTracker utility
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/STANBOL-414-specification.mdtext
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/STANBOL-414-specification.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/STANBOL-414-specification.mdtext?rev=1230164&r1=1230163&r2=1230164&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/STANBOL-414-specification.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/STANBOL-414-specification.mdtext
Wed Jan 11 17:37:32 2012
@@ -178,15 +178,83 @@ This changes will result in the followin
+ canEnhance(ContentItem ci) : int
+ computeEnhacements(ContentItem ci)
+In addition to this I would propose to also include properties currently only
provided by engines via the ServiceProperties interface the the properties of
the service registration. By this it would be possible to access such
information also via the ServiceReference without the need to retrieve the
EnhancementEngine first.
+
+This would e.g. allow to determine the execution order of Enignes by directly
retrieving the ServiceProperties#ENHANCEMENT_ENGINE_ORDERING directly
+from the ServiceReference
### EnhancementEngineManager
-New Utility that keeps track of all active EnhancementEngines and supports
lookup for Enhancement Engines based on the "stanbol.enhancer.engine.name"
property.
+With the addition of enhancement chains and the RESTful interfaces for engines
there will be much more components that will need to track active Enhancement
Engines by the "stanbol.enhancer.engine.name" property and sort active engines
by their service ranking. To satisfy this need one has two possible solutions:
+
+1. EnhancementEngineManager Service: OSGI Service that keeps track of all
active engines.
+2. EngineTracker: Utility that implements EnhancementEngineManager but would
be used similar to the
[ServiceTracker](http://www.osgi.org/javadoc/r4v42/org/osgi/util/tracker/ServiceTracker.html)
to track a single-, a specific set or all active EnhancementEngines.
+
+First lets define the EnhancementEngineManager interface
+ /** Getter for the reference to the engine with the parsed name */
+ + getReference(String name) : ServiceReference
+ /** Getter for all references to active engines with the parsed name */
+ + getReferences(String name) : List<ServiceReference>
+ /** Getter for the Engine for the given name */
+ getEngine(String name) : EnhancementEngine
- + getEngines(String name) : List<EnhancementEngine>
- + isEngine(String name) : boolean
- + getActiveEngines(Chain chain) : Map<String,EnhancementEngine>
+
+#### EngineTracker
+
+Utility that internally uses
[ServiceTracker](http://www.osgi.org/javadoc/r4v42/org/osgi/util/tracker/ServiceTracker.html)
to keep track of active EnhancementEngines there names and service rankings.
In addition to the implementation of the EnhancementEngineManager interface it
would define the following Methods to construct and start/stop the tracker.
+
+ /** Constructs a tracker for the parsed names. All if no names are parsed
*/
+ + EnginesTracker(BundleContext context,String...names)
+ /** Constructs a tracker for the parsed names. all if names is NULL or
empty */
+ + EnginesTracker(BundleContext context,Set<String> names,
ServiceTrackerCustomizer customizer)
+ /** Starts the tracking */
+ + open()
+ /** Stops tracking and closes the tracker */
+ + close()
+ /** Getter for the list of tracked engine names. Empty if all are tracked
*/
+ + getTrackedEngines() : Set<String>
+This utility can be used by Components that need to track a specific set of
Engines. In addition it also allows users to provide an own
ServiceTrackerCustomizer. This can be e.g. used to perform special actions on
any change to an tracked Engine.
+
+A typically usage if this would be by the _WeightedChain_ implementation that
needs to track changes in referenced EnhancementEgninges to update the
execution plan it needs to manage based on the
ServiceProperties#ENHANCEMENT_ENGINE_ORDERING values.
+
+#### EnhancementEngineManager Service
+
+A Component registered for the EnhancementEngineManager service.
Implementation could use an EngineTracker that tracks all EnhancementEngines.
This service will be typically used by using
+
+ @Reference
+ EnhancementEngineManager engineManager;
+
+A typical use would be to retrieve the engines needed to asynchronously
execute a chain
+
+ //during initialization of the execution
+ Set<String> engineNames = chain.getEngines();
+ //actually this should not check engines referenced by
+ //optional ExecutionNodes
+ for(String engineName : chain.getEngines()){
+ if(engineManager.getReference(engineName) == null){
+ //throw exception
+ }
+ }
+
+
+ //this is called after an engine completes execution
+ //and assumes the following execution states:
+ Collection<NonLiteral> executed; //already executed Engines
+ Collection<NonLiteral> running; //currently running Engines
+
+ Collection<NonLiteral> next = ExecutionPlanUtils.getExecuteable(plan,
executed);
+ for(NonLiteral node : next){
+ if(!running.contains(node)){
+ String engineName =
EnhancementEngineHelper.getString(executionPlan,node, EX_ENGINE));
+ EnhancementEngine engine = tracker.getEngine(engineName);
+ if(engine != null){
+ // asynchronously call this engine
+ } else {
+ //check if optional and throw error if not
+ }
+ } // else already running -> ignore
+ }
+
Enhancement Process
----
