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, ServiceExporter, ServiceImporter, SvcInstance, TemporalDependency

public abstract class DependencyModel
extends 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 interface 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(Class specification, boolean aggregate, boolean optional, Filter filter, Comparator comparator, int policy, BundleContext context, DependencyStateListener listener, ComponentInstance ci)
          Creates a DependencyModel.
 
Method Summary
 void addedService(ServiceReference ref)
          Service Tracker added service callback.
 boolean addingService(ServiceReference ref)
          Service tracker adding service callback.
 int getBindingPolicy()
          Gets the used binding policy.
 String getComparator()
          Gets the used comparator name.
static Comparator getComparator(Element dep, BundleContext context)
          Helper method parsing the comparator attribute and returning the comparator object.
 String getFilter()
          Returns the dependency filter (String form).
static int getPolicy(Element dep)
          Helper method parsing the binding policy.
 Object getService(ServiceReference ref)
          Gets a service object for the given reference.
 ServiceReference getServiceReference()
          Gets the next matching service reference.
 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 isOptional()
           
static Class loadSpecification(String specification, BundleContext context)
          Loads the given specification class.
 void manageModification(ServiceReference ref)
          This method can be override by the concrete dependency to be notified of service modification.
 boolean match(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(ServiceReference ref, Object arg1)
          Service tracker modified service callback.
abstract  void onDependencyReconfiguration(ServiceReference[] departs, ServiceReference[] arrivals)
          Concrete dependency callback.
abstract  void onServiceArrival(ServiceReference ref)
          Concrete dependency callback.
abstract  void onServiceDeparture(ServiceReference ref)
          Concrete dependency callback.
abstract  void onServiceModification(ServiceReference ref)
          Concrete dependency callback.
 void removedService(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(BundleContext context)
          Sets the bundle context used by this dependency.
 void setComparator(Comparator cmp)
           
 void setFilter(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(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

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,
                       Filter filter,
                       Comparator comparator,
                       int policy,
                       BundleContext context,
                       DependencyStateListener listener,
                       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.

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(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(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 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(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 TrackerCustomizer
Parameters:
ref - : new references.
See Also:
TrackerCustomizer.addedService(org.osgi.framework.ServiceReference)

removedService

public void removedService(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 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(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 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 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 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(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(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(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(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(ServiceReference[] departs,
                                                 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(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(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(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(ServiceReference ref)
Ungets a used service reference.

Parameters:
ref - the reference to unget.

getComparator

public static Comparator getComparator(Element dep,
                                       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 - the Element describing the dependency
context - the 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 Class loadSpecification(String specification,
                                      BundleContext context)
                               throws 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:
ConfigurationException - if the class cannot be loaded correctly.

getPolicy

public static int getPolicy(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 - the Element describing the dependency
Returns:
the policy attached to this dependency
Throws:
ConfigurationException - if an unknown binding policy was described.


Copyright © 2013 The Apache Software Foundation. All Rights Reserved.