Package org.apache.felix.dm.annotation.api

Annotation Type Component

@Retention(CLASS) @Target(TYPE) public @interface Component
Annotates an OSGi Component class with its dependencies. 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. By default, all directly implemented interfaces are registered into the OSGi registry, and the component is instantiated automatically, when the component bundle is started and when the component dependencies are available. If you need to take control of when and how much component instances must be created, then you can use the factoryName annotation attribute.

If a factoryPid attribute is set, the component is not started automatically during bundle startup, and the component can then be instantiated multiple times using Configuration Admin "Factory Configurations".

Usage Examples

Here is a sample showing a Hello component, which depends on a configuration dependency: 
 /**
   * This component will be activated once the bundle is started and when all required dependencies
   * are available.
   */
 @Component
 class Hello implements HelloService {
     @ConfigurationDependency(pid="my.pid")
     void configure(Dictionary conf) {
          // Configure or reconfigure our component.
     }
   
     @Start
     void start() {
         // Our component is starting and is about to be registered in the OSGi registry as a HelloService service.
     }   
 }
Here is a sample showing how a HelloFactory component may dynamically instantiate several Hello component instances, using Configuration Admin "Factory Configurations": 
  /**
    * All component instances will be created/updated/removed by the "HelloFactory" component
    */
  @Component(factoryPid="my.factory.pid")
  class Hello implements HelloService {                 
      void updated(Dictionary conf) {
          // Configure or reconfigure our component. The conf is provided by the factory,
      }
       
      @Start
      void start() {
          // Our component is starting and is about to be registered in the OSGi registry as a Hello service.
      }       
  } 

  /**
    * This class will instantiate some Hello component instances
    */
  @Component 
  class HelloFactory {
     @ServiceDependency
     void bind(ConfigurationAdmin cm) {
          // instantiate a first instance of Hello component
          Configuration c1 = cm.createFactoryConfiguration("my.factory.pid", "?");
          Hashtable props = new Hashtable();
          newprops.put("key", "value1");
          c1.update(props);
          
          // instantiate another instance of Hello component
          Configuration c2 = cm.createFactoryConfiguration("my.factory.pid", "?");
          props = new Hashtable();
          newprops.put("key", "value2");
          c2.update(props);
          
          // destroy the two instances of X component
          c1.delete();
          c2.delete();
     }
  }
Author:
Felix Project Team

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    factoryMethod
    Sets the static method used to create the components implementation instance.
    String
    factoryPid
    Returns the factory pid whose configurations will instantiate the annotated service class.
    boolean
    propagate
    Returns true if the factory configuration properties must be published to the service properties.
    Property[]
    properties
    Deprecated.
    you can apply Property annotation directly on the component class.
    Class<?>[]
    provides
    Sets list of provided interfaces.
    ServiceScope
    scope
    The service scope for the service of this Component.
    String
    updated
    The Update method to invoke (defaulting to "updated"), when a factory configuration is created or updated.

  • Element Details

    • provides

      Class<?>[] provides
      Sets list of provided interfaces. By default, the directly implemented interfaces are provided.
      Returns:
      the provided interfaces
      Default:
      {}

    • factoryMethod

      String factoryMethod
      Sets the static method used to create the components implementation instance.
      Returns:
      the factory method used to instantiate the component
      Default:
      ""

    • factoryPid

      String factoryPid
      Returns the factory pid whose configurations will instantiate the annotated service class. Leaving this attribute unset means your component is a singleton. If you specify a factory pid, then this component will be instantiated each time a corresponding factory configuration is created.
      Returns:
      the factory pid
      Default:
      ""

    • updated

      String updated
      The Update method to invoke (defaulting to "updated"), when a factory configuration is created or updated. Only used if the factoryPid attribute is set. The updated callback supported signatures are the following:

      • callback(Dictionary)
      • callback(Component, Dictionary)
      • callback(Component, Configuration ... configTypes) // type safe configuration interface(s)
      • callback(Configuration ... configTypes) // type safe configuration interface(s)
      • callback(Dictionary, Configuration ... configTypes) // type safe configuration interfaces(s)
      • callback(Component, Dictionary, Configuration ... configTypes) // type safe configuration interfaces(s)
      Returns:
      the updated callback
      Default:
      "updated"

    • propagate

      boolean propagate
      Returns true if the factory configuration properties must be published to the service properties. Only used if the factoryPid attribute is set.
      Returns:
      true if configuration must be published along with the service, false if not.
      Default:
      false

    • scope

      ServiceScope scope
      The service scope for the service of this Component.

      If not specified, the singleton service scope is used.

      Default:
      SINGLETON

    • properties

      Property[] properties
      Deprecated.
      you can apply Property annotation directly on the component class.
      Sets list of provided service properties. Since R7 version, Property annotation is repeatable and you can directly apply it on top of the component class multiple times, instead of using the Component properties attribute.
      Returns:
      the component properties.
      Default:
      {}