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 factorySet annotation attribute.

If a factorySet attribute is set, the component is not started automatically during bundle startup, and a java.util.Set<Dictionary> object is registered into the OSGi registry on behalf of the component. This Set will act as a Factory API, and another component may use this Set and add some configuration dictionaries in it, in order to fire some component activations (there is one component instantiated per dictionary, which is passed to component instances via a configurable callback method).

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 factorySet() attribute:

  /**
    * All component instances will be created/updated/removed by the "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 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() {
          // ...
      }   
  }
 
  /**
    * 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 x1/x2 components (Notice that invoking XFactory.clear() will destroy all X component  instances).
          _XFactory.remove(x1);
          _XFactory.remove(x2); 
      }
  }
 


Optional Element Summary
 String factoryConfigure
          Sets "configure" callback method name to be called with the factory configuration.
 String factoryMethod
          Sets the static method used to create the components implementation instance.
 String factorySet
          Returns the name of the Factory Set used to dynamically instantiate this component.
 Property[] properties
          Sets list of provided service properties.
 Class<?>[] provides
          Sets list of provided interfaces.
 

provides

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

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.

Default:
""

factoryConfigure

public abstract String factoryConfigure
Sets "configure" callback 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 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 String factoryMethod
Sets the static method used to create the components implementation instance.

Default:
""


Copyright © 2006-2011 Apache Software Foundation. All Rights Reserved.