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();
      }
  }

Field Summary

Fields
Modifier and Type	Fields and Description
`static java.lang.String`	`FACTORY_INSTANCE` Key used when providing an implementation when using a Component Factory .
`static java.lang.String`	`FACTORY_NAME` Service property name used to match a given Component Factory.

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.

- Field Detail
  - FACTORY_NAME
```
public static final java.lang.String FACTORY_NAME
```
    Service property name used to match a given Component Factory.
    
    See Also:
    
    for more information about factory sets.
- - FACTORY_INSTANCE
```
public static final java.lang.String FACTORY_INSTANCE
```
    Key used when providing an implementation when using a Component Factory .
    
    See Also:
    
    factoryName()
- 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:
    
    {}
- - properties
```
public abstract Property[] properties
```
    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:
    
    {}
- - 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.
    Returns:
    
    the factory set name
    
    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.
    
    Returns:
    
    the factory name
    
    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).
    
    Returns:
    
    the factory configure callback name
    
    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:
    
    ""

Annotation Type Component

Usage Examples

Field Summary

Optional Element Summary

Field Detail

FACTORY_NAME

FACTORY_INSTANCE

Element Detail

provides

properties

factorySet

factoryName

factoryConfigure

factoryMethod