Annotations - Writing Components

Component Types

Before diving into all annotations, we must first introduce the different types of components DependencyManager is supporting. In Dependency Manager, you may use the following types of components, depending on what you need:

• Component: Components are the main building blocks for OSGi applications. They can publish themselves as a service, and/or they can have dependencies. These dependencies will influence their life cycle as component will only be activated when all required dependencies are available.

• Aspect Service: A service that provides a non-functional aspect on top of an existing service. In aspect oriented programming, an aspect, or interceptor can sit between a client and another target service used by the client. An Aspect Service first tracks a target service and is created once the target service is detected. Then the Aspect Service is provided, but with a higher ranking, and the client is transparently updated with the aspect. Aspects can be chained and may apply to the same target service (and in this case, the ranking of the Aspect service is used to chain aspects in the proper order).

• Adapter Service: A Service that adapts another existing service into a new one. Like with aspects, sometimes you want to create adapters for certain services, which add certain behavior that results in the publication of (in this case) a different service. Adapters can dynamically be added and removed and allow you to keep your basic services implementations clean and simple, adding extra features on top of them in a modular way.

Now we have introduced the different types of components, here is the list of annotations, allowing to declare DependencyManager service components:

• @Component: for declaring a Component that eventually publishes a singleton OSGi service as long as its dependencies are resolved.
• @AspectService: provides a non-functional aspect on top of an existing service.
• @AdapterService: creates an OSGi service that adapts another existing service into a new interface.
• @BundleAdapterService: creates an OSGi service a service on top of a given bundle.
• @ResourceAdapterService: creates an OSGi service on top of a specific Resource.
• @FactoryConfigurationAdapterService: creates an OSGi service from ConfigAdmin, using a factoryPid, and a ManagedServiceFactory.

@Component

This annotation annotates an implementation class that optionally publishes an OSGi service, and optionally has some dependencies, with a managed lifecycle. The annotation has the following attributes:

• provides: By default, the component is registered into the OSGi registry under all directly implemented interfaces. If no interfaces are implemented, then the component is not registered, but it still has a managed lifecycle, and may have some dependencies. If you need to explicitly define the list of interfaces (or classes) under which the component must be registered in the OSGi registry, then use the provides attribute. You can also set this property to an empty array of classes if you don't want at all your component to be exposed in the OSGi registry (even if it implements some interfaces).
• properties: enumerates the list of properties that are part of the Service exposed by the component in the OSGi Registry. Each property is defined using the @Property annotation, which represents a key/value pair. When a value is actually an array of strings, then the values attribute of the @Property annotation can be used. This attribute is not the only way to specify OSGi Service properties (see Setting Service properties in the lifecycle section).
• factoryMethod: may match a static method name from the annotated class which can be used to instantiate the component instance. Normally, DependencyManager instantiates the component using its class name, and with the default constructor of the class, but there are some cases where it is required to take control of how the component is created. For instance, this method may be used to create the component as a dynamic proxy ...
• factorySet: The component factory ID. By default, a component is automatically instantiated as a singleton when the bundle is started, and when all required dependencies are satisfied. But when a component must be created, configured, or disposed dynamically, and when multiple instances of the same component are needed, a factorySet should be used. When you use this attribute, a java.util.Set<Dictionary> object is registered into the OSGi regitry, with a specific dm.factory.name property matching the ID you specify in the attribute. This Set<Dictionary> will act as a Factory API, and another component may define a dependency on this Set and add some configuration dictionaries in it, in order to fire some component instantiation/activation. There is one component instantiated per added dictionary, which is passed to component instances via a configurable callback method (using the factoryConfigure attribute). All public properties will be propagated along with eventual published service. A public property is a property which does not start with a dot ("."). Properties starting with a dot are considered private to the component, and won't be propagated to published service. This model is actually similar to the Declarative Service "Component Factories" concept, except that you don't have a dependency on a specific API, but rather on a basic jdk class (java.util.Set<Dictionary>). Notice that, unlike in Declarative Service, the component factory is provided once the component bundle is started, even if required dependencies are not satisfied. This is useful when the component want to dynamically configure its dependency filters. So, to summarize:
  • Each time a new Dictionary is added into the Set, then a new instance of the annotated component will be instantiated, and this dictionary is passed to the component callback specified with the factoryConfigure attribute.
  • Each time an existing Dictionary is re-added into the Set, then the corresponding component instance is updated, and the updated dictionary is also passed to the callback specified in the factoryConfigure attribute.
  • Each time an existing Dictionary is removed from the Set, then the corresponding component instance will be stopped and destroyed.
• factoryConfigure: Sets the "configure" method name to be called with the factory configuration. This attribute only makes sense if the factorySet() attribute is used. If specified, then this attribute references a component callback method, which is called for providing the configuration supplied by the factory that instantiated this component. The current Service properties will be also updated with all public properties (which don't start with a dot).

Usage example:

 /**
   * This component will be activated once the bundle is started and when all required dependencies
   * are available.
   */
 @Component
 class X implements Z {
     @ConfigurationDependency(pid="MyPid")
     void configure(Dictionary conf) {
          // Configure or reconfigure our service.
     }

     @Start
     void start() {
         // Our component is starting and is about to be registered in the OSGi registry as a Z service.
     }

     public void doService() {
         // ...
     }
 }

Example using a factorySet, where the X component is instantiated/updated/disposed by another Y component:

  @Component(factorySet="MyComponentFactory", factoryConfigure="configure")
  class X implements Z {
      void configure(Dictionary conf) {
          // Configure or reconfigure our component. The conf is provided by the factory,
          // and all public properties (which don't start with a dot) are propagated with the
          // Service properties eventually specified in the properties annotation attribute.
      }

      @ServiceDependency
      void bindOtherService(OtherService other) {
          // store this require dependency
      }

      @Start
      void start() {
          // Our component is starting and is about to be registered in the OSGi registry as a Z service.
      }

      public void doService() {
          // ... part of Z interface
      }
  }

  /**
    * This class will instantiate some X component instances
    */
  @Component
  class Y {
      @ServiceDependency(filter="(dm.factory.name=MyComponentFactory)")
      Set<Dictionary> _XFactory; // This Set acts as a Factory API for creating X component instances.

      @Start
      void start() {
          // Instantiate a X component instance
          Dictionary x1 = new Hashtable() {{ put("foo", "bar1"); }};
          _XFactory.add(x1);

          // Instantiate another X component instance
          Dictionary x2 = new Hashtable() {{ put("foo", "bar2"); }};
          _XFactory.add(x2);

          // Update the first X component instance
          x1.put("foo", "bar1_modified");
          _XFactory.add(x1);

          // Destroy all components (Notice that invoking _XFactory.clear() also destroys every X instances)
          _XFactory.remove(x1);
          _XFactory.remove(x2);
      }
  }

@AspectService

Aspects allow you to define an interceptor, or chain of interceptors for a service (to add features like caching or logging, etc ...). The dependency manager intercepts the original service, and allows you to execute some code before invoking the original service ... The aspect will be applied to any service that matches the specified interface and filter and will be registered with the same interface and properties as the original service, plus any extra properties you supply here. It will also inherit all dependencies, and if you declare the original service as a member it will be injected.

Annotation attributes:

• ranking: Sets the ranking of this aspect. Since aspects are chained, the ranking defines the order in which they are chained. Chain ranking is implemented as a service ranking so service lookups automatically retrieve the top of the chain.
• service: Sets the service interface to apply the aspect to. By default, the directly implemented interface is used.
• filter: Sets the filter condition to use with the service interface this aspect is applying to.
• properties: Sets Additional properties to use with the aspect service registration.
• field: Sets the field name where to inject the original service. By default, the original service is injected in any attributes in the aspect implementation that are of the same type as the aspect interface.
• factoryMethod: Sets the static method used to create the AspectService implementation instance. The default constructor of the annotated class is used. The factoryMethod can be used to provide a specific aspect implements, like a DynamicProxy.

Usage example:

 @AspectService(ranking=10), properties={@Property(name="param", value="value")})
 class AspectService implements InterceptedService {
     // The service we are intercepting (injected by reflection)
     protected InterceptedService intercepted;
   
     public void doWork() {
        intercepted.doWork();
     }
 }

@AdapterService

Adapters, like with @AspectService, are used to "extend" existing services, and can publish different services based on the existing one. An example would be implementing a management interface for an existing service, etc .... When you annotate an adapter class with the @AdapterService annotation, it will be applied to any service that matches the implemented interface and filter. The adapter will be registered with the specified interface and existing properties from the original service plus any extra properties you supply here. If you declare the original service as a member it will be injected.

Annotation attributes:

• adapteeService: Sets the adaptee service interface this adapter is applying to.
• provides: Sets the adapter service interface(s). By default, the directly implemented interface(s) is (are) used.
• properties: Sets some additional properties to use with the adapter service registration. By default, the adapter will inherit all adaptee service properties.
• adapteeFilter: Sets the filter condition to use with the adapted service interface.
• factoryMethod: Sets the static method used to create the adapter service implementation instance. By default, the default constructor of the annotated class is used.

Usage example: Here, the AdapterService is registered into the OSGI registry each time an AdapteeService is found from the registry. The AdapterImpl class adapts the AdapteeService to the AdapterService. The AdapterService will also have a service property (param=value), and will also include eventual service properties found from the AdapteeService:

 @AdapterService(adapteeService = AdapteeService.class, properties={@Property(name="param", value="value")})
 class AdapterImpl implements AdapterService {
     // The service we are adapting (injected by reflection)
     protected AdapteeService adaptee;
   
     public void doWork() {
        adaptee.mehod1();
        adaptee.method2();
     }
 }

@BundleAdapterService

Bundle adapters are similar to AdapterService, but instead of adapting a service, they adapt a bundle with a certain set of states (STARTED|INSTALLED|...), and provide a service on top of it.

The bundle adapter will be applied to any bundle that matches the specified bundle state mask and filter conditions, which may match some of the bundle OSGi manifest headers. For each matching bundle an adapter will be created based on the adapter implementation class. The adapter will be registered with the specified interface and with service properties found from the original bundle OSGi manifest headers plus any extra properties you supply here. If you declare the original bundle as a member it will be injected.

Annotation attributes:

• filter: The filter used to match some OSGi manifest headers from a given bundle.
• provides: The interface(s) to use when registering adapters. By default, the interface(s) directly implemented by the annotated class is (are) used.
• properties: Additional properties to use with the service registration.
• stateMask: the bundle state mask to apply. The mask is made up of the flags provided by the org.osgi.framework.Bundle states (UNINSTALLED | INSTALLED | RESOLVED | STARTING | STARTED | ACTIVE).
• propagate: Specifies if manifest headers from the bundle should be propagated to the exposed service properties.
• factoryMethod: Sets the static method used to create the BundleAdapterService implementation instance.

Usage Examples

In the following example, a "VideoPlayer" Service is registered into the OSGi registry each time an active bundle containing a "Video-Path" manifest header is detected:

 @BundleAdapterService(filter = "(Video-Path=*)", stateMask = Bundle.ACTIVE, propagate=true)
 public class VideoPlayerImpl implements VideoPlayer {
     Bundle bundle; // Injected by reflection
         
     void play() {
         URL mpegFile = bundle.getEntry(bundle.getHeaders().get("Video-Path"));
         // play the video provided by the bundle ...
     }
       
     void stop() {}
 }

@ResourceAdapterService

@FactoryConfigurationAdapterService