org.apache.felix.dm

Interface ConfigurationDependency

All Superinterfaces:

ComponentDependencyDeclaration, Dependency

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)

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

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.String callback) 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 always invoked with an already instantiated component (the component implementation class(es) are always instantiated before the updated callback is invoked).

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 called with a component that is not yet instantiated. This allows factory objects to get injected with a configuration before its create method is called.

Parameters:

instance - the instance to call the callbacks 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 component instance is instantiated before the callback is invoked only the the needsInstance parameter is set to true.

Parameters:

instance - the instance to call the callback on

callback - the name of the callback method

needsInstance - true if the component implementation class(es) must be created before the callback instance is invoked, else false.

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.