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 always required, because if it is + not, it does not make sense to use the dependency manager. In that scenario, simply register + your component as a ManagedService(Factory) and handle everything yourself. Also, + only managed services are supported, not factories. If you need support for factories, then + you can use + DependencyManager.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.
- unlike all other DM dependency callbacks, the update method is called from the CM configuration + update thread, and is not serialized with the internal queue maintained by the DM component. + So, take care to concurrent calls between updated callback and your other lifecycle callbacks. +
- 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:
+
- updated(Dictionary) +
- updated(Component, Dictionary) +
- updated(ConfigurationType) +
- updated(Component, ConfigurationType) +
+ +
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(). +
+
+ 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. +
+
+

+ +

+ + +
Field Summary
+
- + + +
  Fields inherited from interface org.apache.felix.dm.ComponentDependencyDeclaration
  +STATE_AVAILABLE_OPTIONAL, STATE_AVAILABLE_REQUIRED, STATE_NAMES, STATE_OPTIONAL, STATE_REQUIRED, STATE_UNAVAILABLE_OPTIONAL, STATE_UNAVAILABLE_REQUIRED
+

+ +

Method Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`ConfigurationDependency`	`add(PropertyMetaData properties)` + Adds a MetaData regarding a given configuration property. +
`ConfigurationDependency`	`setCallback(java.lang.Object instance, + java.lang.String callback)` + Sets the name of the callback method that should be invoked when a configuration + is available. +
`ConfigurationDependency`	`setCallback(java.lang.Object instance, + java.lang.String callback, + boolean needsInstance)` + Sets the name of the callback method that should be invoked when a configuration + is available. +
`ConfigurationDependency`	`setCallback(java.lang.Object instance, + java.lang.String callback, + java.lang.Class<?> configType)` + Sets the name of the callback method that should be invoked when a configuration + is available. +
`ConfigurationDependency`	`setCallback(java.lang.Object instance, + java.lang.String callback, + java.lang.Class<?> configType, + boolean needsInstance)` + Sets the name of the callback method that should be invoked when a configuration + is available. +
`ConfigurationDependency`	`setCallback(java.lang.String callback)` + Sets the name of the callback method that should be invoked when a configuration + is available. +
`ConfigurationDependency`	`setCallback(java.lang.String callback, + java.lang.Class<?> configType)` + Sets the name of the callback method that should be invoked when a configuration + is available. +
`ConfigurationDependency`	`setDescription(java.lang.String description)` + A human readable description of the PID this configuration is associated + with. +
`ConfigurationDependency`	`setHeading(java.lang.String heading)` + The label used to display the tab name (or section) where the properties + are displayed. +
`ConfigurationDependency`	`setLocalization(java.lang.String path)` + Points to the basename of the Properties file that can localize the Meta + Type informations. +
`ConfigurationDependency`	`setPid(java.lang.String pid)` + Sets the `service.pid` of the configuration you are depending on. +
`ConfigurationDependency`	`setPropagate(boolean propagate)` + Sets propagation of the configuration properties to the service + properties. +

+ + +
Methods inherited from interface org.apache.felix.dm.Dependency
+getAutoConfigName, getProperties, isAutoConfig, isAvailable, isPropagated, isRequired

+ + +
Methods inherited from interface org.apache.felix.dm.ComponentDependencyDeclaration
+getFilter, getName, getSimpleName, getState, getType

+ +
- + + +
  Method Detail
  + + + +
  - +
    setCallback
    +
```
ConfigurationDependency setCallback(java.lang.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(java.lang.Object instance,
+                                    java.lang.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(java.lang.Object instance,
+                                    java.lang.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(java.lang.String callback,
+                                    java.lang.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(java.lang.Object instance,
+                                    java.lang.String callback,
+                                    java.lang.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(java.lang.Object instance,
+                                    java.lang.String callback,
+                                    java.lang.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(java.lang.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.
    +
  + + + +
  - +
    setHeading
    +
```
ConfigurationDependency setHeading(java.lang.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(java.lang.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(java.lang.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.
    +
  +
+

+
+
All Known Subinterfaces:
+
BundleDependency, ConfigurationDependency, DependencyContext, ResourceDependency, ServiceDependency
+
+
+
All Known Implementing Classes:
+
AbstractDependency
+
+
+
+
```
public interface Dependency
```
+
Generic dependency for a component. + Can be added to a single component. Can be available, or not..
+

+ +

+ + +

Method Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`java.lang.String`	`getAutoConfigName()` + Returns the name of the member in the class of the component instance + to inject into. +
`<K,V> java.util.Dictionary<K,V>`	`getProperties()` + Returns the properties associated with this dependency. +
`boolean`	`isAutoConfig()` + Returns `true` if auto configuration is enabled for this dependency. +
`boolean`	`isAvailable()` + Returns `true` if the dependency is available. +
`boolean`	`isPropagated()` + Determines if the properties associated with this dependency should be propagated to + the properties of the service registered by the component they belong to. +
`boolean`	`isRequired()` + Returns `true` if this a required dependency. +

+ +
- + + +
  Method Detail
  + + + +
  - +
    isRequired
    +
```
boolean isRequired()
```
    +
    Returns true if this a required dependency. Required dependencies + are dependencies that must be available before the component can be activated.
    +
    +
    Returns:
    +
    true if the dependency is required
    +
    +
  + + + +
  - +
    isAvailable
    +
```
boolean isAvailable()
```
    +
    Returns true if the dependency is available.
    +
    +
    Returns:
    +
    true if the dependency is available
    +
    +
  + + + +
  - +
    isAutoConfig
    +
```
boolean isAutoConfig()
```
    +
    Returns true if auto configuration is enabled for this dependency. + Auto configuration means that a dependency is injected in the component instance + when it's available, and if it's unavailable, a "null object" will be inserted + instead.
    +
    +
    Returns:
    +
    true if auto configuration is enabled for this dependency
    +
    +
  + + + +
  - +
    getAutoConfigName
    +
```
java.lang.String getAutoConfigName()
```
    +
    Returns the name of the member in the class of the component instance + to inject into. If you specify this, not all members of the right + type will be injected, only the member whose name matches.
    +
    +
    Returns:
    +
    the name of the member in the class of the component instance to inject into
    +
    +
  + + + +
  - +
    isPropagated
    +
```
boolean isPropagated()
```
    +
    Determines if the properties associated with this dependency should be propagated to + the properties of the service registered by the component they belong to.
    +
    +
    Returns:
    +
    true if the properties should be propagated
    +
    See Also:
    +
    getProperties()
    +
    +
  + + + +
  - +
    getProperties
    +
```
<K,V> java.util.Dictionary<K,V> getProperties()
```
    +
    Returns the properties associated with this dependency.
    +
    +
    Returns:
    +
    the properties
    +
    See Also:
    +
    isPropagated()
    +
    +
  +
+

Interface ConfigurationDependency

Field Summary

Fields inherited from interface org.apache.felix.dm.ComponentDependencyDeclaration

Method Summary

Methods inherited from interface org.apache.felix.dm.Dependency

Methods inherited from interface org.apache.felix.dm.ComponentDependencyDeclaration

Method Detail

setCallback

setCallback

setCallback

setCallback

setCallback

setCallback

setPid

setPropagate

setHeading

setDescription

setLocalization

add

Interface Dependency

Method Summary

Method Detail

isRequired

isAvailable

isAutoConfig

getAutoConfigName

isPropagated

getProperties