org.apache.stanbol.enhancer.servicesapi.helper
Class EnginesTracker

java.lang.Object
  org.apache.stanbol.enhancer.servicesapi.helper.EnginesTracker

All Implemented Interfaces:

EnhancementEngineManager

public class EnginesTracker
extends java.lang.Object
implements EnhancementEngineManager

Utility similar to ServiceTracker that allows to track one/some/all EnhancementEngines. As convenience this also implements the EnhancementEngineManager interface however the intended usage scenarios for this utility are considerable different to the using the EnhancementEngineManager interface as a service.

This utility especially allows to

• track only EnhancementEngine with names as parsed in the constructor. This allows e.g. a Chain implementation to keep only track of EnhancementEngine that are actually referenced by this chain.
• A ServiceTrackerCustomizer can be parsed to this utility. The methods of this interface will be called on changes to any service tracked by this instance. This allows users of this utility to update there internal state on any change of the state of tracked engines. This might be especially useful for Chain implementations that need to update there execution plan on such changes. However this can also be used by EnhancementJobManager implementations that want to get notified about enhancement engines referenced by the Chain the are currently using to enhance an ContentItem.

Please not that calls to open() and close() are required to start and stop the tracking of this class. In general the same rules as for the ServiceTracker apply also to this utility.

Author:

Rupert Westenthaler

Constructor Summary

protected	EnginesTracker() Protected constructor intended to be used by subclasses that do not want to compete the initialisation as part of construction(e.g.
	EnginesTracker(org.osgi.framework.BundleContext context, java.util.Set<java.lang.String> engineNames, org.osgi.util.tracker.ServiceTrackerCustomizer customizer) Creates a new EnginesTracker for the parsed BundleContext and engine names.
	EnginesTracker(org.osgi.framework.BundleContext context, java.lang.String... engineNames) Creates a new EnginesTracker for the parsed BundleContext and engine names.

Method Summary

void	close() Closes this tracker
java.util.Set<java.lang.String>	getActiveEngineNames() Getter for all active and tracked engine names.
java.util.Map<java.lang.String,org.osgi.framework.ServiceReference>	getActiveEngineReferences() Getter for the map with the names and the ServiceReference of the engine with the highest priority for that name.
EnhancementEngine	getEngine(org.osgi.framework.ServiceReference engineReference) Getter for the EnhancementEngine service for the parsed service Reference.
EnhancementEngine	getEngine(java.lang.String name) Getter for the EnhancementEngine for the parsed name
protected NameBasedServiceTrackingState	getEngineTrackingState() Getter for the name based service tracker.
org.osgi.framework.ServiceReference	getReference(java.lang.String name) Getter for the ServiceReference of the EnhancementEngine for the parsed name
java.util.List<org.osgi.framework.ServiceReference>	getReferences(java.lang.String name) Getter for all ServiceReferences of the EnhancementEngines registered for the parsed name.
java.util.Set<java.lang.String>	getTrackedEngines() Getter for the list of tracked engine names.
protected void	initEngineTracker(org.osgi.framework.BundleContext context, java.util.Set<java.lang.String> engineNames, org.osgi.util.tracker.ServiceTrackerCustomizer customiser) Initialises the EnginesTracker by using the parsed parameter.
boolean	isEngine(java.lang.String name) Checks if an EnhancementEngine with the parsed name is active
void	open() Starts tracking based on the configuration parsed in the constructor

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EnginesTracker

protected EnginesTracker()

Protected constructor intended to be used by subclasses that do not want to compete the initialisation as part of construction(e.g. implementations of the EnhancementEngineManager interface the follow the OSGI component model).

Users that use this constructor MUST make sure to call #initEngineTracker(BundleContext, Set, ServiceTrackerCustomizer). Note that initEngineTracker method does NOT call {@link #open()}.

Access to the internal state is provided by the protected getters for the {@link ServiceTracker} and the {@link NameBasedServiceTrackingState} and the public {@link #getTrackedEngines()} method.

EnginesTracker

public EnginesTracker(org.osgi.framework.BundleContext context,
                      java.lang.String... engineNames)

Creates a new EnginesTracker for the parsed BundleContext and engine names. Examples:

     //Track all active engines
     new EnginesTracker(context);
     
     //Track only the langId engine
     new EnginesTracker(context,langId);
 

Parameters:

context - The bundle context used to track engines

engineNames - the name of the engines to track. If empty all engines are tracked.

EnginesTracker

public EnginesTracker(org.osgi.framework.BundleContext context,
                      java.util.Set<java.lang.String> engineNames,
                      org.osgi.util.tracker.ServiceTrackerCustomizer customizer)

Creates a new EnginesTracker for the parsed BundleContext and engine names. Examples:

     //Track all active engines with a customiser
     new EnginesTracker(context,null,customiser);
     
     //Track all engines referenced by a Chain and use the customiser
     //to react on changes
     new EnginesTracker(context,chain.getEngineNames(),customiser);
 

Parameters:

context - the bundle context used to track engines

engineNames - the names of the engines to track. Parse null or an Collections.emptySet() to track all engines

customizer - the ServiceTrackerCustomizer used with this tracker.

Method Detail

initEngineTracker

protected void initEngineTracker(org.osgi.framework.BundleContext context,
                                 java.util.Set<java.lang.String> engineNames,
                                 org.osgi.util.tracker.ServiceTrackerCustomizer customiser)

Initialises the EnginesTracker by using the parsed parameter.

This will create a copy of the parsed engineNames to avoid changes to the internal state due to external changes.

This Method can also be used to re-initialise an existing instance. Any existing ServiceTracker will be closed and the current state will be lost.

Parameters:

context - the BundleContext. MUST NOT be null.

engineNames - the engines to track. null or an empty Set to track all engines

customiser - an optional service tracker customiser.

Throws:

java.lang.IllegalStateException - it the parsed BundleContext is null

java.lang.IllegalArgumentException - if the parsed engineNames do only contain invalid engine names. Even through null values and empty values are removed without failing it is assumed as error if the parsed set only contains such values.

open

public void open()

Starts tracking based on the configuration parsed in the constructor

close

public void close()

Closes this tracker

getTrackedEngines

public final java.util.Set<java.lang.String> getTrackedEngines()

Getter for the list of tracked engine names. This set represents the names of engines tracked by this instance. It does not provide any indication if an EnhancementEngine with that name is available or not.

If all engines are tracked by this EngineTracker instance this is Indicated by returning an empty Set.

Returns:

the tracked engines or an empty set if all engines are tracked.

getReference

public org.osgi.framework.ServiceReference getReference(java.lang.String name)

Description copied from interface: EnhancementEngineManager

Getter for the ServiceReference of the EnhancementEngine for the parsed name

Specified by:

getReference in interface EnhancementEngineManager

Parameters:

name - The name - MUST NOT be null empty and tracked by this tracker

Returns:

the ServiceReference or null if no Engine with the given name is active

isEngine

public boolean isEngine(java.lang.String name)

Description copied from interface: EnhancementEngineManager

Checks if an EnhancementEngine with the parsed name is active

Specified by:

isEngine in interface EnhancementEngineManager

Parameters:

name - the name

Returns:

the state

getReferences

public java.util.List<org.osgi.framework.ServiceReference> getReferences(java.lang.String name)
                                                                  throws java.lang.IllegalArgumentException

Description copied from interface: EnhancementEngineManager

Getter for all ServiceReferences of the EnhancementEngines registered for the parsed name. The list of references is sorted by Constants.SERVICE_RANKING.

Specified by:

getReferences in interface EnhancementEngineManager

Parameters:

name - The name - MUST NOT be null empty and tracked by this tracker

Returns:

the list of ServiceReferences sorted by Constants.SERVICE_RANKING with the highest ranking in the first position. If no engine for the parsed name is active an empty list is returned. with the given name is active

Throws:

java.lang.IllegalArgumentException - if the parsed name is null, empty or not tracked by this tracker instance.

getActiveEngineNames

public java.util.Set<java.lang.String> getActiveEngineNames()

Description copied from interface: EnhancementEngineManager

Getter for all active and tracked engine names. This is a snapshot and this set will change if EnhancementEngines become active/inactive.

Users of this method should keep in mind to check if the ServiceReferences and/or EnhancementEngines retrieved by the names in the returned set may no longer be available. Therefore it is strongly recommended to checks for null values on results of subsequent calls to EnhancementEngineManager.getReference(String) or EnhancementEngineManager.getEngine(String).

Specified by:

getActiveEngineNames in interface EnhancementEngineManager

Returns:

the set with all names of currently active engines.

getActiveEngineReferences

public java.util.Map<java.lang.String,org.osgi.framework.ServiceReference> getActiveEngineReferences()

Getter for the map with the names and the ServiceReference of the engine with the highest priority for that name.

Returns:

the map with the names and ServiceReferences of all currently active and tracked engines

getEngine

public EnhancementEngine getEngine(java.lang.String name)

Description copied from interface: EnhancementEngineManager

Getter for the EnhancementEngine for the parsed name

Specified by:

getEngine in interface EnhancementEngineManager

Parameters:

name - The name - MUST NOT be null empty and tracked by this tracker

Returns:

The EnhancementEngine or null if no Engine with the given name is active

getEngine

public EnhancementEngine getEngine(org.osgi.framework.ServiceReference engineReference)

Description copied from interface: EnhancementEngineManager

Getter for the EnhancementEngine service for the parsed service Reference. This method allows to also retrieve the service for other engines than the one with the highest service ranking by using

     for(ServiceReference engineRef : tracker.getReferences("test")){
         EnhancementEngine engine = tracker.getEngine(engineRef)
         if(engine != null) { //may become inactive in the meantime
             //save the world by using this engine!
         }
     }
 

Specified by:

getEngine in interface EnhancementEngineManager

Parameters:

engineReference - the service reference for an engine tracked by this component

Returns:

the referenced EnhancementEngine or null if no longer available.

getEngineTrackingState

protected final NameBasedServiceTrackingState getEngineTrackingState()

Getter for the name based service tracker. ServiceReferences returned by this instance are guaranteed to refer to EnhancementEngine services with names that are tracked by this instance

Returns:

the engine tracking state