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 factoryName attribute is set, the component is not started automatically during bundle startup, and a org.apache.felix.dm.runtime.api.ComponentFactory object is registered into the OSGi registry on behalf of the component. This ComponentFactory can then be used by another component in order to instantiate multiple instances of the component (DM ComponentFactory are really similar to DS ComponentFactory).

Usage Examples

Here is a sample showing a X 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 X implements Z {
     @ConfigurationDependency(pid="MyPid")
     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 Z service.
     }
   
     public void doService() {
         // ...
     }   
 }

Here is a sample showing how a Y component may dynamically instantiate several X component instances, using the factoryName() attribute:

  /**
    * All component instances will be created/updated/removed by the "Y" component
    */
  @Component(factoryName="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 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() {
          // ...
      }   
  }
 
  import import org.apache.felix.dm.runtime.api.ComponentFactory;

  /**
    * This class will instantiate some X component instances
    */
  @Component 
  class Y {
      @ServiceDependency(filter="(" + Component.FACTORY_NAME + "=MyComponentFactory)")
      ComponentFactory _XFactory;
    
      @Start
      void start() {
          // Instantiate a X component instance
          Dictionary instance1Conf = new Hashtable() {{ put("foo", "bar1"); }};
          ComponentInstance instance1 = _XFactory.newInstance(instance1Conf);
      
          // Instantiate another X component instance
          Dictionary instance2Conf = new Hashtable() {{ put("foo2", "bar2"); }};
          ComponentInstance instance2 = _XFactory.newInstance(instance2Conf);
      
          // Update the first X component instance
          instance1Conf = new Hashtable() {{ put("foo", "bar1 modified"); }};
          instance1.update(instance1Conf);
          
          // Instantiate a third X instance, by explicitly providing the implementation object
          Dictionary instance3Conf = new Hashtable() {{ put(Component.FACTORY_INSTANCE, new X()); }};
          ComponentInstance instance3 = _XFactory.newInstance(instance3Conf);
      
          // Destroy x1/x2/x3 components
          instance1.dispose();
          instance2.dispose();
          instance3.dispose();
      }
  }

Optional Element Summary

Optional Elements
Modifier and Type	Optional Element and Description
`java.lang.String`	`factoryConfigure` Sets "configure" callback method name to be called with the factory configuration.
`java.lang.String`	`factoryMethod` Sets the static method used to create the components implementation instance.
`java.lang.String`	`factoryName` Returns the name of the `ComponentFactory` used to dynamically instantiate this component.
`java.lang.String`	`factorySet` Deprecated. use `factoryName()` instead of a factorySet.
`Property[]`	`properties` Sets list of provided service properties.
`java.lang.Class<?>[]`	`provides` Sets list of provided interfaces.

- Element Detail
  - provides
```
public abstract java.lang.Class<?>[] provides
```
    Sets list of provided interfaces. By default, the directly implemented interfaces are provided.
    
    Default:
    
    {}
  - properties
```
public abstract Property[] properties
```
    Sets list of provided service properties.
    
    Default:
    
    {}
  - factorySet
```
public abstract java.lang.String factorySet
```
    Deprecated. use factoryName() instead of a factorySet.
    Returns the name of the Factory Set used to dynamically instantiate this component. When you set this attribute, a java.util.Set<java.lang.Dictionary> OSGi Service will be provided with a dm.factory.name service property matching your specified factorySet attribute. This Set will be provided once the component bundle is started, even if required dependencies are not available, and the Set will be unregistered from the OSGi registry once the component bundle is stopped or being updated.
    So, basically, another component may then be injected with this set in order to dynamically instantiate some component instances:
    - Each time a new Dictionary is added into the Set, then a new instance of the annotated component will be instantiated.
    - Each time an existing Dictionary is re-added into the Set, then the corresponding component instance will be updated.
    - Each time an existing Dictionary is removed from the Set, then the corresponding component instance will be destroyed.
    The dictionary registered in the Set will be provided to the created component instance using a callback method that you can optionally specify in the factoryConfigure() attribute. Each public properties from that dictionary (which don't start with a dot) will be propagated along with the annotated component service properties.
    Optionally, the dictionary registered into the factory set may provide an implementation instance for the component to be created, using the "dm.factory.instance" key.
    Default:
    
    ""
  - factoryName
```
public abstract java.lang.String factoryName
```
    Returns the name of the ComponentFactory used to dynamically instantiate this component. When you set this attribute, a org.apache.felix.dm.runtime.api.ComponentFactory OSGi Service will be provided with a dm.factory.name service property matching your specified factoryName attribute. The ComponentFactory will be provided once the component bundle is started, even if required dependencies are not available, and the ComponentFactory will be unregistered from the OSGi registry once the component bundle is stopped or being updated.
    So, another component may then be injected with this ComponentFactory in order to dynamically instantiate some component instances:
    The dictionary passed to the ComponentFactory.newInstance method will be provided to the created component instance using a callback method that you can optionally specify in the factoryConfigure() attribute. Each public properties from that dictionary (which don't start with a dot) will be propagated along with the annotated component service properties.
    Optionally, the dictionary registered into the factory set may provide an implementation instance for the component to be created, using a "dm.runtime.factory.instance" key.
    
    Default:
    
    ""
  - factoryConfigure
```
public abstract java.lang.String factoryConfigure
```
    Sets "configure" callback method name to be called with the factory configuration. This attribute only makes sense if the factoryName() attribute is used. If specified, then this attribute references a callback method, which is called for providing the configuration supplied by the factory that instantiated this component. The current component service properties will be also updated with all public properties (which don't start with a dot).
    
    Default:
    
    ""
  - factoryMethod
```
public abstract java.lang.String factoryMethod
```
    Sets the static method used to create the components implementation instance.
    
    Default:
    
    ""

Annotation Type Component

Usage Examples

Optional Element Summary

Element Detail

provides

properties

factorySet

factoryName

factoryConfigure

factoryMethod