org.apache.felix.dm.annotation.api

Annotation Type ConfigurationDependency

@Retention(value=CLASS)
@Target(value=METHOD)
public @interface ConfigurationDependency

Annotates a method for injecting a Configuration Dependency. A configuration dependency is always required, and allows you to depend on the availability of a valid configuration for your component. This dependency requires the OSGi Configuration Admin Service.

Usage Examples

In the following example, the "Printer" component depends on a configuration whose PID name is "sample.PrinterConfiguration". This service will initialize its ip/port number from the provided configuration.

First, we define the configuration metadata, using standard bndtools metatatype annotations (see http://www.aqute.biz/Bnd/MetaType):

 package sample;
 import aQute.bnd.annotation.metatype.Meta.AD;
 import aQute.bnd.annotation.metatype.Meta.OCD;

 @OCD(description = "Declare here the Printer Configuration.")
 public interface PrinterConfiguration {
     @AD(description = "Enter the printer ip address")
     String ipAddress();

     @AD(description = "Enter the printer address port number.")
     int portNumber();
 }
 

Next, we define our Printer service which depends on the PrinterConfiguration:

 package sample;
 import aQute.bnd.annotation.metatype.*;

 @Component
 public class Printer {
     @ConfigurationDependency(pidClass = PrinterConfiguration.class) // Will use pid "sample.PrinterConfiguration"
     void updated(Dictionary props) {
         // load configuration from the provided dictionary, or throw an exception of any configuration error.
         PrinterConfig cnf = Configurable.createConfigurable(PrinterConfig.class, props);
         String ip = cnf.ipAddress();
         int port = cnf.portNumber();
         ...
     }
 }
 

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.String	description Deprecated. use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType)
java.lang.String	heading Deprecated. use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType)
PropertyMetaData[]	metadata Deprecated. use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType)
java.lang.String	name The name for this configuration dependency.
java.lang.String	pid Returns the pid for a given service (by default, the pid is the service class name).
java.lang.Class<?>	pidClass Returns the pid from a class name.
boolean	propagate Returns true if the configuration properties must be published along with the service.

Element Detail

pid

public abstract java.lang.String pid

Returns the pid for a given service (by default, the pid is the service class name).

Returns:

the pid for a given service (default = Service class name)

Default:

""

pidClass

public abstract java.lang.Class<?> pidClass

Returns the pid from a class name. The full class name will be used as the configuration PID. You can use this method when you use an interface annoted with standard bndtols metatype annotations. (see http://www.aqute.biz/Bnd/MetaType).

Default:

java.lang.Object.class

propagate

public abstract boolean propagate

Returns true if the configuration properties must be published along with the service. Any additional service properties specified directly are merged with these.

Returns:

true if configuration must be published along with the service, false if not.

Default:

false

name

public abstract java.lang.String name

The name for this configuration dependency. When you give a name a dependency, it won't be evaluated immediately, but after the component's init method has been called, and from the init method, you can then return a map in order to dynamically configure the configuration dependency (the map has to contain a "pid" and/or "propagate" flag, prefixed with the dependency name). Then the dependency will be evaluated after the component init method, and will be injected before the start method.

Usage example of a Configuration dependency whose pid and propagate flag is configured dynamically from init method:

  /**
    * A Service that dynamically defines an extra dynamic configuration dependency from its init method. 
    */
  @Component
  class X {
      private Dictionary m_config;
      
      // Inject initial Configuration (injected before any other required dependencies)
      @ConfigurationDependency
      void componentConfiguration(Dictionary config) {
           // you must throw an exception if the configuration is not valid
           m_config = config;
      }
      
      /**
       * All unnamed dependencies are injected: we can now configure our dynamic configuration whose dependency name is "global".
       */
      @Init
      Map init() {
          return new HashMap() {{
              put("global.pid", m_config.get("globalConfig.pid"));
              put("global.propagate", m_config.get("globalConfig.propagate"));
          }};
      } 
 
      // Injected after init, and dynamically configured by the init method.
      @ConfigurationDependency(name="global")
      void globalConfiguration(Dictionary globalConfig) {
           // you must throw an exception if the configuration is not valid
      }
 
      /**
       * All dependencies are injected and our service is now ready to be published.
       */
      @Start
      void start() {
      }
  }
  

Default:

""

heading

public abstract java.lang.String heading

Deprecated. use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType)

The label used to display the tab name (or section) where the properties are displayed. Example: "Printer Service".

Returns:

The label used to display the tab name where the properties are displayed.

Default:

""

description

public abstract java.lang.String description

Deprecated. use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType)

A human readable description of the PID this annotation is associated with. Example: "Configuration for the PrinterService bundle".

Returns:

A human readable description of the PID this annotation is associated with.

Default:

""

metadata

public abstract PropertyMetaData[] metadata

Deprecated. use standard bndtools metatype annotations instead (see http://www.aqute.biz/Bnd/MetaType)

The list of properties types used to expose properties in web console.

Returns:

The list of properties types used to expose properties in web console.

Default:

{}