Package org.apache.felix.dm

Interface ConfigurationDependency

All Superinterfaces:
ComponentDependencyDeclaration, Dependency
@ProviderType public interface ConfigurationDependency extends Dependency, ComponentDependencyDeclaration
Configuration dependency that can track the availability of a (valid) configuration. To use it, specify a PID for the configuration. The dependency is required by default. If you define an optional configuration dependency, the updated callback will be invoked with an empty Dictionary, or with a type-safe configuration (which in this case can provide some default methods that you can use to inialize your component).

Also, only managed services are supported, not factories. If you need support for factories, then you can use DependencyManagerCompat.createFactoryConfigurationAdapterService(String, String, boolean). There are a couple of things you need to be aware of when implementing the updated(Dictionary) method:

  • Make sure it throws a ConfigurationException or any other exception when you get a configuration that is invalid. In this case, the dependency will not change: if it was not available, it will still not be. If it was available, it will remain available and implicitly assume you keep working with your old configuration.
  • This method will be called before all required dependencies are available. Make sure you do not depend on these to parse your settings.
  • When the configuration is lost, updated callback is invoked with a null dictionary parameter, and then the component stop lifecycle callback is invoked.
  • When the DM component is stopped, then updated(null) is not invoked.

The callback invoked when a configuration dependency is updated can supports the following signatures:

  • 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)

Support for a custom Configuration type is a new feature that allows you to specify an interface that is implemented by DM and such interface is then injected to your callback instead of the actual Dictionary. Using such configuration interface provides a way for creating type-safe configurations from a actual Dictionary that is normally injected by Dependency Manager. The callback accepts in argument an interface that you have to provide, and DM will inject a proxy that converts method calls from your configuration-type to lookups in the actual map or dictionary. The results of these lookups are then converted to the expected return type of the invoked configuration method.
As proxies are injected, no implementations of the desired configuration-type are necessary!

The lookups performed are based on the name of the method called on the configuration type. The method names are "mangled" to the following form: [lower case letter] [any valid character]*. Method names starting with get or is (JavaBean convention) are stripped from these prefixes. For example: given a dictionary with the key "foo" can be accessed from a configuration-type using the following method names: foo(), getFoo() and isFoo().

If the property contains a dot (which is invalid in java method names), then dots (".") can be converted using the following conventions:

  • if the method name follows the javabean convention and/or kamel casing convention, then each capital letter is assumed to map to a "dot", followed by the same letter in lower case. This means only lower case properties are supported in this case. Example: getFooBar() or fooBar() will map to "foo.bar" property.
  • else, if the method name follows the standard OSGi metatype specification, then dots are encoded as "_"; and "_" is encoded as "__". (see OSGi r6 compendium, chapter 105.9.2). Example: "foo_BAR()" is mapped to "foo.BAR" property; "foo__BAR_zoo()" is mapped to "foo_BAR.zoo" property.

The return values supported are: primitive types (or their object wrappers), strings, enums, arrays of primitives/strings, Collection types, Map types, Classes and interfaces. When an interface is returned, it is treated equally to a configuration type, that is, it is returned as a proxy.

Arrays can be represented either as comma-separated values, optionally enclosed in square brackets. For example: [ a, b, c ] and a, b,c are both considered an array of length 3 with the values "a", "b" and "c". Alternatively, you can append the array index to the key in the dictionary to obtain the same: a dictionary with "arr.0" => "a", "arr.1" => "b", "arr.2" => "c" would result in the same array as the earlier examples.

Maps can be represented as single string values similarly as arrays, each value consisting of both the key and value separated by a dot. Optionally, the value can be enclosed in curly brackets. Similar to array, you can use the same dot notation using the keys. For example, a dictionary with 

"map" => "{key1.value1, key2.value2}"
and a dictionary with 

"map.key1" => "value1", "map2.key2" => "value2"
result in the same map being returned. Instead of a map, you could also define an interface with the methods getKey1() and getKey2 and use that interface as return type instead of a Map.

In case a lookup does not yield a value from the underlying map or dictionary, the following rules are applied:

  1. primitive types yield their default value, as defined by the Java Specification;
  2. string, Classes and enum values yield null;
  3. for arrays, collections and maps, an empty array/collection/map is returned;
  4. for other interface types that are treated as configuration type a null-object is returned.

Author:
Felix Project Team

  • Method Details

    • setCallback

      ConfigurationDependency setCallback(String callback)
      Sets the name of the callback method that should be invoked when a configuration is available. The contract for this method is identical to that of ManagedService.updated(Dictionary) throws ConfigurationException. By default, if this method is not called, the callback name is "updated".

      The callback is invoked on the instantiated component.

      Parameters:
      callback - the name of the callback method

    • setCallback

      ConfigurationDependency setCallback(Object instance, String callback)
      Sets the name of the callback method that should be invoked when a configuration is available. The contract for this method is identical to that of ManagedService.updated(Dictionary) throws ConfigurationException.

      the callback is invoked on the callback instance, and the component is not yet instantiated at the time the callback is invoked.

      Parameters:
      instance - the object to invoke the callback on
      callback - the name of the callback method

    • setCallback

      ConfigurationDependency setCallback(Object instance, String callback, boolean needsInstance)
      Sets the name of the callback method that should be invoked when a configuration is available. The contract for this method is identical to that of ManagedService.updated(Dictionary) throws ConfigurationException.

      the callback is invoked on the callback instance, and if needsInstance is true, the component is instantiated at the time the callback is invoked

      Parameters:
      instance - the object to invoke the callback on.
      callback - the name of the callback method
      needsInstance - true if the component must be instantiated before the callback is invoked on the callback instance.

    • setCallback

      ConfigurationDependency setCallback(String callback, Class<?> configType)
      Sets the name of the callback method that should be invoked when a configuration is available. The contract for this method is identical to that of ManagedService.updated(Dictionary) throws ConfigurationException with the difference that instead of a Dictionary it accepts an interface of the given configuration type.
      By default, the pid is assumed to match the fqdn of the configuration type.

      The callback is invoked on the instantiated component.

      Parameters:
      callback - the name of the callback method
      configType - the configuration type that the callback method accepts.

    • setCallback

      ConfigurationDependency setCallback(Object instance, String callback, Class<?> configType)
      Sets the name of the callback method that should be invoked when a configuration is available. The contract for this method is identical to that of ManagedService.updated(Dictionary) throws ConfigurationException with the difference that instead of a Dictionary it accepts an interface of the given configuration type.

      The callback is invoked on the callback instance, and at this point the component is not yet instantiated.

      Parameters:
      instance - the object to invoke the callback on.
      callback - the name of the callback method
      configType - the configuration type that the callback method accepts.

    • setCallback

      ConfigurationDependency setCallback(Object instance, String callback, Class<?> configType, boolean needsInstance)
      Sets the name of the callback method that should be invoked when a configuration is available. The contract for this method is identical to that of ManagedService.updated(Dictionary) throws ConfigurationException with the difference that instead of a Dictionary it accepts an interface of the given configuration type.

      the callback is invoked on the callback instance, and if needsInstance is true, the component is instantiated at the time the callback is invoked

      Parameters:
      instance - the object to invoke the callback on.
      callback - the name of the callback method
      configType - the configuration type that the callback method accepts.
      needsInstance - true if the component must be instantiated before the callback is invoked on the callback instance.

    • setPid

      ConfigurationDependency setPid(String pid)
      Sets the service.pid of the configuration you are depending on.

    • setPropagate

      ConfigurationDependency setPropagate(boolean propagate)
      Sets propagation of the configuration properties to the service properties. Any additional service properties specified directly are merged with these. Configuration properties are not propagated by default. When configuration is propagated, component service properties won't be overriden by configuration properties having the same name, unless you invoke setPropagate(true, false) method.
      Parameters:
      propagate - true if configuration properties should be propagated to the component service properties. Configuration starting with a dot won't be propagated (because such property is considered as private, see Configuration Admin spec).
      See Also:

    • setPropagate

      ConfigurationDependency setPropagate(boolean propagate, boolean overrideServiceProperties)
      Sets propagation of the configuration properties to the service properties. Any additional service properties specified directly are merged with these. Configuration properties are not propagated by default.
      Parameters:
      propagate - true if the configuration properties must be propagated to the component service properties. Configuration starting with a dot won't be propagated (because such property is considered as private, see Configuration Admin spec).
      overrideServiceProperties - true if propagated configuration properties should override the component service properties having the same property name

    • setHeading

      ConfigurationDependency setHeading(String heading)
      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 (may be localized)

    • setDescription

      ConfigurationDependency setDescription(String description)
      A human readable description of the PID this configuration is associated with. Example: "Configuration for the PrinterService bundle".
      Returns:
      A human readable description of the PID this configuration is associated with (may be localized)

    • setLocalization

      ConfigurationDependency setLocalization(String path)
      Points to the basename of the Properties file that can localize the Meta Type informations. The default localization base name for the properties is OSGI-INF/l10n/bundle, but can be overridden by the manifest Bundle-Localization header (see core specification, in section Localization on page 68). You can specify a specific localization basename file using this method (e.g. setLocalization("person") will match person_du_NL.properties in the root bundle directory.

    • add

      ConfigurationDependency add(PropertyMetaData properties)
      Adds a MetaData regarding a given configuration property.

    • setRequired

      ConfigurationDependency setRequired(boolean required)
      Sets the required flag which determines if this configuration dependency is required or not. A configuration dependency is required by default.
      Parameters:
      required - the required flag
      Returns:
      this service dependency

    • needsInstance

      ConfigurationDependency needsInstance(boolean needsInstance)
      Specifies if the component instance should be instantiated when this dependency is started. The component is always instantiated when a Configuration dependency is defined, except if you set a callback instance or if you invoke this method with false

    • setConfigType

      ConfigurationDependency setConfigType(Class<?>... configType)
      Sets the configuration property type(s) that are passed to the updated callback parameters
      Parameters:
      configType - the configuration type(s) that the callback method accepts.