Package org.apache.felix.dm.runtime

Class ServiceLifecycleHandler

java.lang.Object

org.apache.felix.dm.runtime.ServiceLifecycleHandler

public class ServiceLifecycleHandler
extends Object

Caution: this class *MUST* be immutable, because it may be shared between Aspects/Adapters and concrete Aspect/Adapter instance. This class allows Services to configure dynamically their dependency filters from their init() method. Basically, this class acts as a service implementation lifecycle handler. When we detect that the Service is called in its init() method, and if init() returns a Map, then the Map is assumed to contain dependency filters, which will be applied to all named dependencies. The Map optionally returned by Service's init method may contain the following keys:

• name.filter: the value must be a valid OSGi filter, and the "name" prefix must match a ServiceDependency name attribute
• name.required: the value is a boolean ("true"|"false") and the "name" prefix must match a ServiceDependency name attribute

Dependencies which provide a name attribute will be activated after the init method returns. Other dependencies are injected before the init method.

Example of a Service whose dependency filter is configured from ConfigAdmin:

  /**
    * A Service whose service dependency filter/require attribute may be configured from ConfigAdmin
    */
  @Service
  class X {
      private Dictionary m_config;
      
      @ConfigurationDependency(pid="MyPid")
      void configure(Dictionary conf) {
           // Initialize our service from config ...
           
           // And store the config for later usage (from our init method)
           m_config = config;
      }
      
      @ServiceDependency(name="dependency1") 
      void bindOtherService(OtherService other) {
         // the filter and required flag will be configured from our init method.
      }

      // The returned Map will be used to configure our "dependency1" Dependency.
      @Init
      Map init() {
          return new HashMap() {{
              put("dependency1.filter", m_config.get("filter"));
              put("dependency1.required", m_config.get("required"));
          }};
      } 
  }
  

Author:

Felix Project Team

Constructor Summary

Constructors

Constructor	Description
ServiceLifecycleHandler(org.apache.felix.dm.Component srv, org.osgi.framework.Bundle srvBundle, org.apache.felix.dm.DependencyManager dm, MetaData srvMeta, List<MetaData> depMeta)	Makes a new ServiceLifecycleHandler object.

Method Summary

Modifier and Type	Method	Description
void	destroy(org.apache.felix.dm.Component service)	Handles the Service's destroy lifecycle callback.
void	init(org.apache.felix.dm.Component c)	Handles an "init" lifecycle service callback.
void	start(org.apache.felix.dm.Component service)	Handles the Service's start lifecycle callback.
void	stop(org.apache.felix.dm.Component service)	Handles the Service's stop lifecycle callback.

Methods inherited from class java.lang.Object

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

Constructor Details

ServiceLifecycleHandler

public ServiceLifecycleHandler(org.apache.felix.dm.Component srv,
 org.osgi.framework.Bundle srvBundle,
 org.apache.felix.dm.DependencyManager dm,
 MetaData srvMeta,
 List<MetaData> depMeta)

Makes a new ServiceLifecycleHandler object. This objects allows to decorate the "init" service callback, in order to see if "init" callback returns a dependency customization map.

Parameters:

srv - The Service for the annotated class

srvBundle - the Service bundle

dm - The DependencyManager that was used to create the service

srvMeta - The Service MetaData

depMeta - The Dependencies MetaData

Method Details

init

public void init(org.apache.felix.dm.Component c)
          throws Exception

Handles an "init" lifecycle service callback. We just catch the "init" method, and callback the actual Service' init method, to see if a dependency customization map is returned. We also check if a Lifecycle Controller is used. In this case, we add a hidden custom dependency, allowing to take control of when the component is actually started/stopped. We also handle an edge case described in FELIX-4050, where component state calculation may mess up if some dependencies are added using the API from the init method.

Parameters:

c - The Annotated Component

Throws:

Exception

start

public void start(org.apache.felix.dm.Component service)
           throws IllegalArgumentException,
IllegalAccessException,
InvocationTargetException

Handles the Service's start lifecycle callback. We just invoke the service "start" service callback on the service instance, as well as on all eventual service composites. We take care to check if a start callback returns a Map, which is meant to contain some additional properties which must be appended to existing service properties. Such extra properties takes precedence over existing service properties.

Throws:

IllegalArgumentException

IllegalAccessException

InvocationTargetException

stop

public void stop(org.apache.felix.dm.Component service)
          throws IllegalArgumentException,
IllegalAccessException,
InvocationTargetException

Handles the Service's stop lifecycle callback. We just invoke the service "stop" callback on the service instance, as well as on all eventual service composites.

Throws:

IllegalArgumentException

IllegalAccessException

InvocationTargetException

destroy

public void destroy(org.apache.felix.dm.Component service)
             throws IllegalArgumentException,
IllegalAccessException,
InvocationTargetException

Handles the Service's destroy lifecycle callback. We just invoke the service "destroy" callback on the service instance, as well as on all eventual service composites.

Throws:

IllegalArgumentException

IllegalAccessException

InvocationTargetException