org.apache.felix.ipojo.util
Class DependencyModel

java.lang.Object
  extended by org.apache.felix.ipojo.util.DependencyModel
All Implemented Interfaces:
TrackerCustomizer
Direct Known Subclasses:
Dependency

public abstract class DependencyModel
extends java.lang.Object
implements 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 insterface between the service tracker and the concrete dependency.

Author:
Felix Project Team

Field Summary
static int BROKEN
          Dependency state : BROKEN.
static int DYNAMIC_BINDING_POLICY
          Binding policy : Dynamic.
static int DYNAMIC_PRIORITY_BINDING_POLICY
          Binding policy : Dynamic-Priority.
static int RESOLVED
          Dependency state : RESOLVED.
static int STATIC_BINDING_POLICY
          Binding policy : Static.
static int UNRESOLVED
          Dependency state : UNRESOLVED.
 
Constructor Summary
DependencyModel(java.lang.Class specification, boolean aggregate, boolean optional, org.osgi.framework.Filter filter, java.util.Comparator comparator, int policy, org.osgi.framework.BundleContext context, DependencyStateListener listener)
          Constructor.
 
Method Summary
 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()
          Return the used binding policy.
static java.util.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.
 java.lang.String getFilter()
          Return the dependency filter (String form).
static int getPolicy(org.apache.felix.ipojo.metadata.Element dep)
          Helper method parsing the binding policy.
 java.lang.Object getService(org.osgi.framework.ServiceReference ref)
          Get a service object for the given reference.
 org.osgi.framework.ServiceReference getServiceReference()
          Get the next matching service reference.
 org.osgi.framework.ServiceReference[] getServiceReferences()
          Get matching service references.
 int getSize()
          Get the number of actual matching references.
 java.lang.Class getSpecification()
          Get the tracked specification.
 int getState()
          Get the actual state of the dependency.
 java.util.List getUsedServiceReferences()
          Get 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 isOptional()
           
static java.lang.Class loadSpecification(java.lang.String specification, org.osgi.framework.BundleContext context)
          Load the given specification class.
 boolean match(org.osgi.framework.ServiceReference ref)
          Does the service reference match ? This method must be override by concrete dependency if they need to advanced testing on service reference (that cannot be express in the LDAP filter).
 void modifiedService(org.osgi.framework.ServiceReference ref, java.lang.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.
 void onServiceModification(org.osgi.framework.ServiceReference ref)
          This method can be override by the concrete dependency to be notified of service modification.
 void removedService(org.osgi.framework.ServiceReference ref, java.lang.Object arg1)
          Service tracker removed service callback.
 void setAggregate(boolean isAggregate)
          Set the aggregate attribute of the current dependency.
 void setBindingPolicy()
          Set the binding policy.
 void setBundleContext(org.osgi.framework.BundleContext context)
          Set the bundle context used by this dependency.
 void setComparator(java.util.Comparator cmp)
           
 void setFilter(org.osgi.framework.Filter filter)
          Set the filter of the dependency.
 void setOptionality(boolean isOptional)
          Set the optionality attribute of the current dependency.
 void setSpecification(java.lang.Class specification)
          Set the required specification of this service dependency.
 void start()
          Open the tracking.
 void stop()
          Close the tracking.
 void ungetService(org.osgi.framework.ServiceReference ref)
          Unget a used service reference.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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(java.lang.Class specification,
                       boolean aggregate,
                       boolean optional,
                       org.osgi.framework.Filter filter,
                       java.util.Comparator comparator,
                       int policy,
                       org.osgi.framework.BundleContext context,
                       DependencyStateListener listener)
Constructor.

Parameters:
specification - : required specification
aggregate - : is the dependency aggregate ?
optional - : is the dependency optional ?
filter - : LDAP filter
comparator - : comparator object to sort references
policy - : binding policy
context - : bundle context (or service context)
listener - : dependency lifecycle listener to notify from dependency state changes.
Method Detail

start

public void start()
Open the tracking.


stop

public void stop()
Close the tracking.


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. This method is just used by default. The method must always return false for non-static dependency.

Returns:
true if the reference set is frozen.

match

public boolean match(org.osgi.framework.ServiceReference ref)
Does the service reference match ? This method must be override by concrete dependency if they need to advanced testing on service reference (that cannot be express in the LDAP filter). By default this method return true.

Parameters:
ref - : tested reference.
Returns:
true

addingService

public boolean addingService(org.osgi.framework.ServiceReference ref)
Service tracker adding service callback. We accept the service only if we aren't broken or frozen.

Specified by:
addingService in interface TrackerCustomizer
Parameters:
ref - : the new dependency.
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, manage the arrival.

Specified by:
addedService in interface TrackerCustomizer
Parameters:
ref - : new references.
See Also:
TrackerCustomizer.addedService(org.osgi.framework.ServiceReference)

removedService

public void removedService(org.osgi.framework.ServiceReference ref,
                           java.lang.Object arg1)
Service tracker removed service callback. A service goes away. The depart need to be managed only if the reference was used.

Specified by:
removedService in interface TrackerCustomizer
Parameters:
ref - : leaving service reference
arg1 - : service object if the service was get
See Also:
TrackerCustomizer.removedService(org.osgi.framework.ServiceReference, java.lang.Object)

modifiedService

public void modifiedService(org.osgi.framework.ServiceReference ref,
                            java.lang.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 TrackerCustomizer
Parameters:
ref - : modified reference
arg1 - : service object if already get.
See Also:
TrackerCustomizer.modifiedService(org.osgi.framework.ServiceReference, java.lang.Object)

getServiceReference

public org.osgi.framework.ServiceReference getServiceReference()
Get the next matching service reference.

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

getServiceReferences

public org.osgi.framework.ServiceReference[] getServiceReferences()
Get matching service references.

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

getUsedServiceReferences

public java.util.List getUsedServiceReferences()
Get the list of currently used service references.

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

getSize

public int getSize()
Get 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 need to be re-injected in the underlying concrete dependency.

Parameters:
ref - : 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 void onServiceModification(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 - : 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 - : service leaving the matching set.
arrivals - : service arriving in the matching set.

getState

public int getState()
Get the actual state of the dependency.

Returns:
: the state of the dependency.

getSpecification

public java.lang.Class getSpecification()
Get the tracked specification.

Returns:
the Class object tracked by the dependency.

setSpecification

public void setSpecification(java.lang.Class specification)
Set the required specification of this service dependency. This operation is not supported if the dependency tracking has already begun.

Parameters:
specification - : required specification.

setFilter

public void setFilter(org.osgi.framework.Filter filter)
Set the filter of the dependency. This method recompute the matching set and call the onDependencyReconfiguration callback.

Parameters:
filter - : new LDAP filter.

getFilter

public java.lang.String getFilter()
Return 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)
Set the aggregate attribute of the current dependency. If the tracking is open, it will call arrival and departure callbacks.

Parameters:
isAggregate - : new aggregate attribute value.

isAggregate

public boolean isAggregate()

setOptionality

public void setOptionality(boolean isOptional)
Set the optionality attribute of the current dependency.

Parameters:
isOptional - : the new optional attribute value.

isOptional

public boolean isOptional()

getBindingPolicy

public int getBindingPolicy()
Return the used binding policy.

Returns:
the current binding policy.

setBindingPolicy

public void setBindingPolicy()
Set the binding policy. Not yet supported.


setComparator

public void setComparator(java.util.Comparator cmp)

setBundleContext

public void setBundleContext(org.osgi.framework.BundleContext context)
Set the bundle context used by this dependency. This operation is not supported if the tracker is already opened.

Parameters:
context - : bundle context or service context to use

getService

public java.lang.Object getService(org.osgi.framework.ServiceReference ref)
Get a service object for the given reference.

Parameters:
ref - : wanted service reference
Returns:
: the service object attached to the given reference

ungetService

public void ungetService(org.osgi.framework.ServiceReference ref)
Unget a used service reference.

Parameters:
ref - : reference to unget.

getComparator

public static java.util.Comparator getComparator(org.apache.felix.ipojo.metadata.Element dep,
                                                 org.osgi.framework.BundleContext context)
                                          throws 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 - : Element describing the dependency
context - : bundle context (to load the comparator class)
Returns:
the comparator object, null if not set.
Throws:
ConfigurationException - the comparator class cannot be load or the comparator cannot be instantiated correctly.

loadSpecification

public static java.lang.Class loadSpecification(java.lang.String specification,
                                                org.osgi.framework.BundleContext context)
                                         throws ConfigurationException
Load the given specification class.

Parameters:
specification - : specification class name to load
context - : bundle context
Returns:
: the class object for the given specification
Throws:
ConfigurationException - : the class cannot be loaded correctly.

getPolicy

public static int getPolicy(org.apache.felix.ipojo.metadata.Element dep)
                     throws 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 - : Element describing the dependency
Returns:
: the policy attached to this dependency
Throws:
ConfigurationException - : an unknown biding policy was described.