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

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

All Implemented Interfaces:

ChainManager

public class ChainsTracker
extends java.lang.Object
implements ChainManager

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

This utility especially allows to

• track only Chains with names as parsed in the constructor.
• 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 chains.

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

Field Summary

Fields inherited from interface org.apache.stanbol.enhancer.servicesapi.ChainManager

DEFAULT_CHAIN_NAME

Constructor Summary

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

Method Summary

void	close() Closes this tracker
java.util.Set<java.lang.String>	getActiveChainNames() Getter for the names of all currently active enhancement chains.
java.util.Map<java.lang.String,org.osgi.framework.ServiceReference>	getActiveChainReferences() Getter for the map with the names and the ServiceReference of the chain with the highest priority for that name.
Chain	getChain(org.osgi.framework.ServiceReference chainReference) Getter for the Chain service for the parsed service Reference.
Chain	getChain(java.lang.String name) Getter for the Chain with the highest Constants.SERVICE_RANKING registered for the parsed name.
protected NameBasedServiceTrackingState	getChainTrackingState() Getter for the name based service tracker.
Chain	getDefault() Getter for the default Chain.
org.osgi.framework.ServiceReference	getReference(java.lang.String name) Getter for the ServiceReference of the Chain for the parsed name
java.util.List<org.osgi.framework.ServiceReference>	getReferences(java.lang.String name) Getter for all ServiceReferences of the Chains registered for the parsed name.
java.util.Set<java.lang.String>	getTrackedChains() Getter for the list of tracked chain names.
protected void	initChainTracker(org.osgi.framework.BundleContext context, java.util.Set<java.lang.String> chainNames, org.osgi.util.tracker.ServiceTrackerCustomizer customiser) Initialises the ChainsTracker by using the parsed parameter.
boolean	isChain(java.lang.String name) Checks if at least a single Chain with the parsed name is currently registered as OSGI service.
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

ChainsTracker

protected ChainsTracker()

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 ChainManager interface the follow the OSGI component model).

Users that use this constructor MUST make sure to call initChainTracker(BundleContext, Set, ServiceTrackerCustomizer). Note that #initChainTracker() does NOT call open().

Access to the internal state is provided by the protected getters for the ServiceTracker and the NameBasedServiceTrackingState and the public getTrackedChains() method.

ChainsTracker

public ChainsTracker(org.osgi.framework.BundleContext context,
                     java.lang.String... chainNames)

Creates a new ChainsTracker for the parsed BundleContext and chain names. Examples:

     //Track all active chains
     new ChainsTracker(context);
     
     //Track only the chain with the name "dbpediaLinking"
     new ChainsTracker(context,"dbpediaLinking");
 

Parameters:

context - The bundle context used to track chains

chainNames - the name of the chains to track. If empty all chains are tracked.

ChainsTracker

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

Creates a new ChainsTracker for the parsed BundleContext and chain names. Examples:

     //Track all active chains with a customiser
     new ChainsTracker(context,null,customiser);
     
     //Track all chains with the names and use the customiser
     //to react on changes
     new ChainsTracker(context,chainNames,customiser);
 

Parameters:

context - the bundle context used to track chains

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

customizer - the ServiceTrackerCustomizer used with this tracker.

Method Detail

initChainTracker

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

Initialises the ChainsTracker by using the parsed parameter.

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

Parameters:

context - the BundleContext. MUST NOT be null.

chainNames - the chains to track. null or an empty Set to track all chains 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.

customiser - an optional service tracker customiser.

Throws:

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

java.lang.IllegalArgumentException - if the parsed chainNames do only contain invalid Chain 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

getTrackedChains

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

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

If all chains are tracked by this ChainTracker instance this is Indicated by returning an empty Set.

Returns:

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

getReference

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

Description copied from interface: ChainManager

Getter for the ServiceReference of the Chain for the parsed name

Specified by:

getReference in interface ChainManager

Parameters:

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

Returns:

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

isChain

public boolean isChain(java.lang.String name)

Description copied from interface: ChainManager

Checks if at least a single Chain with the parsed name is currently registered as OSGI service.

Specified by:

isChain in interface ChainManager

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: ChainManager

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

Specified by:

getReferences in interface ChainManager

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 chain 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.

getActiveChainNames

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

Description copied from interface: ChainManager

Getter for the names of all currently active enhancement chains. This is a snapshot and this set will change if Chains become active/inactive.

Users of this method should keep in mind to check if the ServiceReferences and/or Chains 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 ChainManager.getReference(String) or ChainManager.getChain(String).

Specified by:

getActiveChainNames in interface ChainManager

Returns:

the set with all names of currently active chains.

getActiveChainReferences

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

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

Returns:

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

getChain

public Chain getChain(java.lang.String name)

Description copied from interface: ChainManager

Getter for the Chain with the highest Constants.SERVICE_RANKING registered for the parsed name.

Specified by:

getChain in interface ChainManager

Parameters:

name - the name of the Chain

Returns:

the Chain or null if no Chain with this name is registered as OSGI service.

getChain

public Chain getChain(org.osgi.framework.ServiceReference chainReference)

Description copied from interface: ChainManager

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

     for(ServiceReference chainRef : tracker.getReferences("test")){
         Chain chain = tracker.getChain(chainRef)
         if(chain != null) { //may become inactive in the meantime
             //start the catastrophic chain of events that caused the Big Bang
         }
     }
 

Specified by:

getChain in interface ChainManager

Parameters:

chainReference - the service reference for a tracked chain

Returns:

the referenced Chain or null if no longer available.

getDefault

public Chain getDefault()

Description copied from interface: ChainManager

Getter for the default Chain. This is the Chain that MUST BE used to enhance ContentItem if the no Chain was explicitly parsed in the enhancement request.

The default Chain is the Chain with the value of the property Chain.PROPERTY_NAME is equals to ChainManager.DEFAULT_CHAIN_NAME and the highest Constants.SERVICE_RANKING. If no Chain with the name "default" exists the Chain with the highest service ranking (regardless of its name) is considered the default Chain.

Specified by:

getDefault in interface ChainManager

Returns:

the default Chain or null if no Chain is available

getChainTrackingState

protected final NameBasedServiceTrackingState getChainTrackingState()

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

Returns:

the chain tracking state