fr.liglab.adele.cilia.dependency

Class DependencyModel

java.lang.Object

fr.liglab.adele.cilia.dependency.DependencyModel

All Implemented Interfaces:

org.apache.felix.ipojo.util.TrackerCustomizer

Direct Known Subclasses:

Dependency

public abstract class DependencyModel
extends Object
implements org.apache.felix.ipojo.util.TrackerCustomizer

Abstract dependency model. This class is the parent class of every service dependency. It manages the most part of dependency management. This class creates an interface between the service tracker and the concrete dependency.

Author:

Felix Project Team

Field Summary

Fields

Modifier and Type	Field and Description
static int	BROKEN Dependency state : BROKEN.
static int	DYNAMIC_BINDING_POLICY Binding policy : Dynamic.
static int	DYNAMIC_PRIORITY_BINDING_POLICY Binding policy : Dynamic-Priority.
protected static org.slf4j.Logger	logger
static int	RESOLVED Dependency state : RESOLVED.
static int	STATIC_BINDING_POLICY Binding policy : Static.
static int	UNRESOLVED Dependency state : UNRESOLVED.

Constructor Summary

Constructors

Constructor and Description
DependencyModel(Class specification, boolean aggregate, boolean optional, org.osgi.framework.Filter filter, Comparator comparator, int policy, org.osgi.framework.BundleContext context, DependencyStateListener listener, org.apache.felix.ipojo.ComponentInstance ci) Creates a DependencyModel.

Method Summary

Methods

Modifier and Type	Method and Description
void	addedService(org.osgi.framework.ServiceReference ref) Service Tracker added service callback.
boolean	addingService(org.osgi.framework.ServiceReference ref) Service tracker adding service callback.
int	getBindingPolicy() Gets the used binding policy.
String	getComparator() Gets the used comparator name.
static Comparator	getComparator(org.apache.felix.ipojo.metadata.Element dep, org.osgi.framework.BundleContext context) Helper method parsing the comparator attribute and returning the comparator object.
String	getFilter() Returns the dependency filter (String form).
int	getMaxServiceInjected()
static int	getPolicy(org.apache.felix.ipojo.metadata.Element dep) Helper method parsing the binding policy.
static int	getPolicy(String policy) Helper method parsing the binding policy.
Object	getService(org.osgi.framework.ServiceReference ref) Gets a service object for the given reference.
org.osgi.framework.ServiceReference	getServiceReference() Gets the next matching service reference.
org.osgi.framework.ServiceReference[]	getServiceReferences() Gets matching service references.
int	getSize() Gets the number of actual matching references.
Class	getSpecification() Gets the tracked specification.
int	getState() Gets the actual state of the dependency.
List	getUsedServiceReferences() Gets the list of currently used service references.
boolean	isAggregate()
boolean	isFrozen() Is the reference set frozen (cannot change anymore)? This method must be override by concrete dependency to support the static binding policy.
boolean	isImmediate()
boolean	isOptional()
boolean	isServicesInWaitToInject()
static Class	loadSpecification(String specification, org.osgi.framework.BundleContext context) Loads the given specification class.
void	manageModification(org.osgi.framework.ServiceReference ref) This method can be override by the concrete dependency to be notified of service modification.
boolean	match(org.osgi.framework.ServiceReference ref) Does the service reference match ? This method must be override by concrete dependencies if they need advanced testing on service reference (that cannot be expressed in the LDAP filter).
void	modifiedService(org.osgi.framework.ServiceReference ref, Object arg1) Service tracker modified service callback.
abstract void	onDependencyReconfiguration(org.osgi.framework.ServiceReference[] departs, org.osgi.framework.ServiceReference[] arrivals) Concrete dependency callback.
abstract void	onServiceArrival(org.osgi.framework.ServiceReference ref) Concrete dependency callback.
abstract void	onServiceDeparture(org.osgi.framework.ServiceReference ref) Concrete dependency callback.
abstract void	onServiceModification(org.osgi.framework.ServiceReference ref) Concrete dependency callback.
void	removedService(org.osgi.framework.ServiceReference ref, Object arg1) Service tracker removed service callback.
void	setAggregate(boolean isAggregate) Sets the aggregate attribute of the current dependency.
void	setBindingPolicy() Sets the binding policy.
void	setBundleContext(org.osgi.framework.BundleContext context) Sets the bundle context used by this dependency.
void	setComparator(Comparator cmp)
void	setFilter(org.osgi.framework.Filter filter) Sets the filter of the dependency.
void	setOptionality(boolean isOptional) Sets the optionality attribute of the current dependency.
void	setSpecification(Class specification) Sets the required specification of this service dependency.
void	start() Opens the tracking.
void	stop() Closes the tracking.
void	unfreeze() Unfreezes the dependency.
void	ungetService(org.osgi.framework.ServiceReference ref) Ungets a used service reference.

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected static org.slf4j.Logger logger

BROKEN

public static final int BROKEN

Dependency state : BROKEN. A broken dependency cannot be fulfilled anymore. The dependency becomes broken when a used service disappears in the static binding policy.

See Also:

Constant Field Values

UNRESOLVED

public static final int UNRESOLVED

Dependency state : UNRESOLVED. A dependency is unresolved if the dependency is not valid and no service providers are available.

See Also:

Constant Field Values

RESOLVED

public static final int RESOLVED

Dependency state : RESOLVED. A dependency is resolved if the dependency is optional or at least one provider is available.

See Also:

Constant Field Values

DYNAMIC_BINDING_POLICY

public static final int DYNAMIC_BINDING_POLICY

Binding policy : Dynamic. In this policy, services can appears and departs without special treatment.

See Also:

Constant Field Values

STATIC_BINDING_POLICY

public static final int STATIC_BINDING_POLICY

Binding policy : Static. Once a service is used, if this service disappears the dependency becomes BROKEN. The instance needs to be recreated.

See Also:

Constant Field Values

DYNAMIC_PRIORITY_BINDING_POLICY

public static final int DYNAMIC_PRIORITY_BINDING_POLICY

Binding policy : Dynamic-Priority. In this policy, services can appears and departs. However, once a service with a highest ranking (according to the used comparator) appears, this new service is re-injected.

See Also:

Constant Field Values

Constructor Detail

DependencyModel

public DependencyModel(Class specification,
               boolean aggregate,
               boolean optional,
               org.osgi.framework.Filter filter,
               Comparator comparator,
               int policy,
               org.osgi.framework.BundleContext context,
               DependencyStateListener listener,
               org.apache.felix.ipojo.ComponentInstance ci)

Creates a DependencyModel. If the dependency has no comparator and follows the DYNAMIC_PRIORITY_BINDING_POLICY policy the OSGi Service Reference Comparator is used.

Parameters:

specification - the required specification

aggregate - is the dependency aggregate ?

optional - is the dependency optional ?

filter - the LDAP filter

comparator - the comparator object to sort references

policy - the binding policy

context - the bundle context (or service context)

listener - the dependency lifecycle listener to notify from dependency

ci - instance managing the dependency state changes.

Method Detail

start

public void start()

Opens the tracking. This method computes the dependency state

See Also:

computeDependencyState()

stop

public void stop()

Closes the tracking. The dependency becomes UNRESOLVED at the end of this method.

isFrozen

public boolean isFrozen()

Is the reference set frozen (cannot change anymore)? This method must be override by concrete dependency to support the static binding policy. In fact, this method allows optimizing the static dependencies to become frozen only when needed. This method returns false by default. The method must always return false for non-static dependencies.

Returns:

true if the reference set is frozen.

isImmediate

public boolean isImmediate()

getMaxServiceInjected

public int getMaxServiceInjected()

isServicesInWaitToInject

public boolean isServicesInWaitToInject()

unfreeze

public void unfreeze()

Unfreezes the dependency. This method must be overide by concrete dependency to support the static binding policy. This method is called after tracking restarting.

match

public boolean match(org.osgi.framework.ServiceReference ref)

Does the service reference match ? This method must be override by concrete dependencies if they need advanced testing on service reference (that cannot be expressed in the LDAP filter). By default this method returns true.

Parameters:

ref - the tested reference.

Returns:

true if the service reference matches.

addingService

public boolean addingService(org.osgi.framework.ServiceReference ref)

Service tracker adding service callback. It accepts the service only if the dependency isn't broken or frozen.

Specified by:

addingService in interface org.apache.felix.ipojo.util.TrackerCustomizer

Parameters:

ref - the arriving service reference.

Returns:

true if the reference must be tracked.

See Also:

TrackerCustomizer.addingService(org.osgi.framework.ServiceReference)

addedService

public void addedService(org.osgi.framework.ServiceReference ref)

Service Tracker added service callback. If the service matches (against the filter and the match(ServiceReference), manages the provider arrival.

Specified by:

addedService in interface org.apache.felix.ipojo.util.TrackerCustomizer

Parameters:

ref - : new references.

See Also:

TrackerCustomizer.addedService(org.osgi.framework.ServiceReference)

removedService

public void removedService(org.osgi.framework.ServiceReference ref,
                  Object arg1)

Service tracker removed service callback. A service provider goes away. The depart needs to be managed only if the reference was used.

Specified by:

removedService in interface org.apache.felix.ipojo.util.TrackerCustomizer

Parameters:

ref - the leaving service reference

arg1 - the service object if the service was already get

See Also:

TrackerCustomizer.removedService(org.osgi.framework.ServiceReference, java.lang.Object)

modifiedService

public void modifiedService(org.osgi.framework.ServiceReference ref,
                   Object arg1)

Service tracker modified service callback. This method must handle if the modified service should be considered as a depart or an arrival. According to the dependency filter, a service can now match or can no match anymore.

Specified by:

modifiedService in interface org.apache.felix.ipojo.util.TrackerCustomizer

Parameters:

ref - the modified reference

arg1 - the service object if already get.

See Also:

TrackerCustomizer.modifiedService(org.osgi.framework.ServiceReference, java.lang.Object)

getServiceReference

public org.osgi.framework.ServiceReference getServiceReference()

Gets the next matching service reference.

Returns:

null if no more provider is available, else returns the first reference from the matching set.

getServiceReferences

public org.osgi.framework.ServiceReference[] getServiceReferences()

Gets matching service references.

Returns:

the sorted (if a comparator is used) array of matching service references, null if no references are available.

getUsedServiceReferences

public List getUsedServiceReferences()

Gets the list of currently used service references. If no service references, returns null

Returns:

the list of used reference (according to the service tracker).

getSize

public int getSize()

Gets the number of actual matching references.

Returns:

the number of matching references

onServiceArrival

public abstract void onServiceArrival(org.osgi.framework.ServiceReference ref)

Concrete dependency callback. This method is called when a new service needs to be re-injected in the underlying concrete dependency.

Parameters:

ref - the service reference to inject.

onServiceDeparture

public abstract void onServiceDeparture(org.osgi.framework.ServiceReference ref)

Concrete dependency callback. This method is called when a used service (already injected) is leaving.

Parameters:

ref - the leaving service reference.

onServiceModification

public abstract void onServiceModification(org.osgi.framework.ServiceReference ref)

Concrete dependency callback. This method is called when a used service (already injected) is modified.

Parameters:

ref - the modified service reference.

manageModification

public void manageModification(org.osgi.framework.ServiceReference ref)

This method can be override by the concrete dependency to be notified of service modification. This modification is not an arrival or a departure.

Parameters:

ref - the modified service reference.

onDependencyReconfiguration

public abstract void onDependencyReconfiguration(org.osgi.framework.ServiceReference[] departs,
                               org.osgi.framework.ServiceReference[] arrivals)

Concrete dependency callback. This method is called when the dependency is reconfigured and when this reconfiguration implies changes on the matching service set ( and by the way on the injected service).

Parameters:

departs - the service leaving the matching set.

arrivals - the service arriving in the matching set.

getState

public int getState()

Gets the actual state of the dependency.

Returns:

the state of the dependency.

getSpecification

public Class getSpecification()

Gets the tracked specification.

Returns:

the Class object tracked by the dependency.

setSpecification

public void setSpecification(Class specification)

Sets the required specification of this service dependency. This operation is not supported if the dependency tracking has already begun.

Parameters:

specification - the required specification.

setFilter

public void setFilter(org.osgi.framework.Filter filter)

Sets the filter of the dependency. This method recomputes the matching set and call the onDependencyReconfiguration callback.

Parameters:

filter - the new LDAP filter.

getFilter

public String getFilter()

Returns the dependency filter (String form).

Returns:

the String form of the LDAP filter used by this dependency, null if not set.

setAggregate

public void setAggregate(boolean isAggregate)

Sets the aggregate attribute of the current dependency. If the tracking is opened, it will call arrival and departure callbacks.

Parameters:

isAggregate - the new aggregate attribute value.

isAggregate

public boolean isAggregate()

setOptionality

public void setOptionality(boolean isOptional)

Sets the optionality attribute of the current dependency.

Parameters:

isOptional - the new optional attribute value.

isOptional

public boolean isOptional()

getBindingPolicy

public int getBindingPolicy()

Gets the used binding policy.

Returns:

the current binding policy.

setBindingPolicy

public void setBindingPolicy()

Sets the binding policy. Not yet supported.

setComparator

public void setComparator(Comparator cmp)

getComparator

public String getComparator()

Gets the used comparator name. Null if no comparator (i.e. the OSGi one is used).

Returns:

the comparator class name or null if the dependency doesn't use a comparator.

setBundleContext

public void setBundleContext(org.osgi.framework.BundleContext context)

Sets the bundle context used by this dependency. This operation is not supported if the tracker is already opened.

Parameters:

context - the bundle context or service context to use

getService

public Object getService(org.osgi.framework.ServiceReference ref)

Gets a service object for the given reference.

Parameters:

ref - the wanted service reference

Returns:

the service object attached to the given reference

ungetService

public void ungetService(org.osgi.framework.ServiceReference ref)

Ungets a used service reference.

Parameters:

ref - the reference to unget.

getComparator

public static Comparator getComparator(org.apache.felix.ipojo.metadata.Element dep,
                       org.osgi.framework.BundleContext context)
                                throws org.apache.felix.ipojo.ConfigurationException

Helper method parsing the comparator attribute and returning the comparator object. If the 'comparator' attribute is not set, this method returns null. If the 'comparator' attribute is set to 'osgi', this method returns the normal OSGi comparator. In other case, it tries to create an instance of the declared comparator class.

Parameters:

dep - the Element describing the dependency

context - the bundle context (to load the comparator class)

Returns:

the comparator object, null if not set.

Throws:

org.apache.felix.ipojo.ConfigurationException - the comparator class cannot be load or the comparator cannot be instantiated correctly.

loadSpecification

public static Class loadSpecification(String specification,
                      org.osgi.framework.BundleContext context)
                               throws org.apache.felix.ipojo.ConfigurationException

Loads the given specification class.

Parameters:

specification - the specification class name to load

context - the bundle context

Returns:

the class object for the given specification

Throws:

org.apache.felix.ipojo.ConfigurationException - if the class cannot be loaded correctly.

getPolicy

public static int getPolicy(org.apache.felix.ipojo.metadata.Element dep)
                     throws org.apache.felix.ipojo.ConfigurationException

Helper method parsing the binding policy. If the 'policy' attribute is not set in the dependency, the method returns the 'DYNAMIC BINDING POLICY'. Accepted policy values are : dynamic, dynamic-priority and static.

Parameters:

dep - the Element describing the dependency

Returns:

the policy attached to this dependency

Throws:

org.apache.felix.ipojo.ConfigurationException - if an unknown binding policy was described.

getPolicy

public static int getPolicy(String policy)
                     throws org.apache.felix.ipojo.ConfigurationException

Helper method parsing the binding policy. If the 'policy' attribute is not set in the dependency, the method returns the 'DYNAMIC BINDING POLICY'. Accepted policy values are : dynamic, dynamic-priority and static.

Parameters:

String - policy the Element describing the dependency

Returns:

the policy attached to this dependency

Throws:

org.apache.felix.ipojo.ConfigurationException - if an unknown binding policy was described.