org.apache.felix.dm.annotation.api

Annotation Type Component

@Retention(value=CLASS)
 @Target(value=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();
     }
  }
 

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.String	factoryMethod Sets the static method used to create the components implementation instance.
java.lang.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.
java.lang.Class<?>[]	provides Sets list of provided interfaces.
ServiceScope	scope The service scope for the service of this Component.
java.lang.String	updated The Update method to invoke (defaulting to "updated"), when a factory configuration is created or updated.

Element Detail

provides

public abstract java.lang.Class<?>[] provides

Sets list of provided interfaces. By default, the directly implemented interfaces are provided.

Returns:

the provided interfaces

Default:

{}

factoryMethod

public abstract java.lang.String factoryMethod

Sets the static method used to create the components implementation instance.

Returns:

the factory method used to instantiate the component

Default:

""

factoryPid

public abstract java.lang.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

public abstract java.lang.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

public abstract 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

public abstract ServiceScope scope

The service scope for the service of this Component.

If not specified, the singleton service scope is used.

Default:

org.apache.felix.dm.annotation.api.ServiceScope.SINGLETON

properties

public abstract 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:

{}