OSGi 8.1.0 · org.osgi.service.cm.Configuration · APIdia, the JavaDoc alternative

The configuration information for a ManagedService or ManagedServiceFactory object. The Configuration Admin service uses this interface to represent the configuration information for a ManagedService or for a service instance of a ManagedServiceFactory.

A Configuration object contains a configuration dictionary and allows the properties to be updated via this object. Bundles wishing to receive configuration dictionaries do not need to use this class - they register a ManagedService or ManagedServiceFactory. Only administrative bundles, and bundles wishing to update their own configurations need to use this class.

The properties handled in this configuration have case insensitive String objects as keys. However, case must be preserved from the last set key/value.

A configuration can be bound to a specific bundle or to a region of bundles using the location. In its simplest form the location is the location of the target bundle that registered a Managed Service or a Managed Service Factory. However, if the location starts with ? then the location indicates multiple delivery. In such a case the configuration must be delivered to all targets. If security is on, the Configuration Permission can be used to restrict the targets that receive updates. The Configuration Admin must only update a target when the configuration location matches the location of the target's bundle or the target bundle has a Configuration Permission with the action ConfigurationPermission#TARGET and a name that matches the configuration location. The name in the permission may contain wildcards ( '*') to match the location using the same substring matching rules as Filter. Bundles can always create, manipulate, and be updated from configurations that have a location that matches their bundle location.

If a configuration's location is null, it is not yet bound to a location. It will become bound to the location of the first bundle that registers a ManagedService or ManagedServiceFactory object with the corresponding PID.

The same Configuration object is used for configuring both a Managed Service Factory and a Managed Service. When it is important to differentiate between these two the term "factory configuration" is used.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	Configuration.ConfigurationAttribute Configuration Attributes.

Method Summary

Modifier and Type	Method and Description
public void	addAttributes(Configuration.ConfigurationAttribute... The attributes to add. attrs) Add attributes to the configuration.
public void	delete() Delete this `Configuration` object.
public boolean	Returns: `true` if equal, `false` if not a `Configuration` object or one with a different PID. equals(Object `Configuration` object to compare against other) Equality is defined to have equal PIDs Two Configuration objects are equal when their PIDs are equal.
public Set<Configuration.ConfigurationAttribute>	Returns: The set of attributes. getAttributes() Get the attributes of this configuration.
public String	Returns: location to which this configuration is bound, or `null`. getBundleLocation() Get the bundle location.
public long	Returns: A monotonically increasing value reflecting changes in this Configuration. getChangeCount() Get the change count.
public String	Returns: factory PID or `null` getFactoryPid() For a factory configuration return the PID of the corresponding Managed Service Factory, else return `null`.
public String	Returns: the PID for this `Configuration` object. getPid() Get the PID for this `Configuration` object.
public Dictionary<String, Object>	Returns: A private copy of the processed properties for the caller or `null`. These properties must not contain the "service.bundleLocation" property. The value of this property may be obtained from the `getBundleLocation()` method. getProcessedProperties(ServiceReference<?> The reference to the Managed Service or Managed Service Factory to pass to the registered `ConfigurationPlugin`s handling this configuration. Must not be `null`. reference) Return the processed properties of this `Configuration` object.
public Dictionary<String, Object>	Returns: A private copy of the properties for the caller or `null`. These properties must not contain the "service.bundleLocation" property. The value of this property may be obtained from the `getBundleLocation()` method. getProperties() Return the properties of this `Configuration` object.
public int	Returns: hash code for this Configuration object hashCode() Hash code is based on PID.
public void	removeAttributes(Configuration.ConfigurationAttribute... The attributes to remove. attrs) Remove attributes from this configuration.
public void	setBundleLocation(String a location, region, or `null` location) Bind this `Configuration` object to the specified location.
public void	update(Dictionary<String, ?> the new set of properties for this configuration properties) Update the properties of this `Configuration` object.
public void	update() Update the `Configuration` object with the current properties.
public boolean	Returns: If the properties are different and the configuration is updated `true` is returned. If the properties are the same, `false` is returned. updateIfDifferent(Dictionary<String, ?> The new set of properties for this configuration. properties) Update the properties of this `Configuration` object if the provided properties are different than the currently stored set.

Method Detail

addAttributes	back to summary
public void addAttributes(Configuration.ConfigurationAttribute... attrs) throws IOException Add attributes to the configuration. Parameters attrs:Configuration.ConfigurationAttribute[] The attributes to add. Exceptions IOException: If the new state cannot be persisted. IllegalStateException: If this configuration has been deleted. SecurityException: when the required permissions are not available Since 1.6

addAttributes

back to summary

public void addAttributes(Configuration.ConfigurationAttribute... attrs) throws IOException

Add attributes to the configuration.

Parameters

attrs:Configuration.ConfigurationAttribute[]: The attributes to add.

Exceptions

IOException:: If the new state cannot be persisted.
IllegalStateException:: If this configuration has been deleted.
SecurityException:: when the required permissions are not available

Since

1.6

delete back to summary

delete	back to summary
public void delete() throws IOException Delete this `Configuration` object. Removes this configuration object from the persistent store. Notify asynchronously the corresponding Managed Service or Managed Service Factory. A `ManagedService` object is notified by a call to its `updated` method with a `null` properties argument. A `ManagedServiceFactory` object is notified by a call to its `deleted` method. Also notifies all Configuration Listeners with a `ConfigurationEvent#CM_DELETED` event. Exceptions IOException: If delete fails. ReadOnlyConfigurationException: If the configuration is `read only`. IllegalStateException: If this configuration has been deleted.

public void delete() throws IOException

Delete this Configuration object.

Removes this configuration object from the persistent store. Notify asynchronously the corresponding Managed Service or Managed Service Factory. A ManagedService object is notified by a call to its updated method with a null properties argument. A ManagedServiceFactory object is notified by a call to its deleted method.

Also notifies all Configuration Listeners with a ConfigurationEvent#CM_DELETED event.

Exceptions

IOException:: If delete fails.
ReadOnlyConfigurationException:: If the configuration is read only.
IllegalStateException:: If this configuration has been deleted.

equals back to summary

equals	back to summary
public boolean equals(Object other) Equality is defined to have equal PIDs Two Configuration objects are equal when their PIDs are equal. Parameters other:Object `Configuration` object to compare against Returns:boolean `true` if equal, `false` if not a `Configuration` object or one with a different PID. Annotations @Override

public boolean equals(Object other)

Equality is defined to have equal PIDs Two Configuration objects are equal when their PIDs are equal.

Parameters

other:Object: Configuration object to compare against

Returns:boolean

true if equal, false if not a Configuration object or one with a different PID.

Annotations

@Override

getAttributes	back to summary
public Set<Configuration.ConfigurationAttribute> getAttributes() Get the attributes of this configuration. Returns:Set<Configuration.ConfigurationAttribute> The set of attributes. Exceptions IllegalStateException: If this configuration has been deleted. Since 1.6

getAttributes

back to summary

public Set<Configuration.ConfigurationAttribute> getAttributes()

Get the attributes of this configuration.

Returns:Set<Configuration.ConfigurationAttribute>

The set of attributes.

Exceptions

IllegalStateException:: If this configuration has been deleted.

Since

1.6

getBundleLocation back to summary

getBundleLocation	back to summary
public String getBundleLocation() Get the bundle location. Returns the bundle location or region to which this configuration is bound, or `null` if it is not yet bound to a bundle location or region. If the location starts with `?` then the configuration is delivered to all targets and not restricted to a single bundle. Returns:String location to which this configuration is bound, or `null`. Exceptions IllegalStateException: If this configuration has been deleted. SecurityException: when the required permissions are not available

public String getBundleLocation()

Get the bundle location. Returns the bundle location or region to which this configuration is bound, or null if it is not yet bound to a bundle location or region. If the location starts with ? then the configuration is delivered to all targets and not restricted to a single bundle.

Returns:String

location to which this configuration is bound, or null.

Exceptions

IllegalStateException:: If this configuration has been deleted.
SecurityException:: when the required permissions are not available

getChangeCount	back to summary
public long getChangeCount() Get the change count. Each Configuration must maintain a change counter that is incremented with a positive value every time the configuration is updated and its properties are stored. The counter must be incremented before the targets are updated and events are sent out. Returns:long A monotonically increasing value reflecting changes in this Configuration. Exceptions IllegalStateException: If this configuration has been deleted. Since 1.5

getChangeCount

back to summary

public long getChangeCount()

Get the change count. Each Configuration must maintain a change counter that is incremented with a positive value every time the configuration is updated and its properties are stored. The counter must be incremented before the targets are updated and events are sent out.

Returns:long

A monotonically increasing value reflecting changes in this Configuration.

Exceptions

IllegalStateException:: If this configuration has been deleted.

Since

1.5

getFactoryPid back to summary

getFactoryPid	back to summary
public String getFactoryPid() For a factory configuration return the PID of the corresponding Managed Service Factory, else return `null`. Returns:String factory PID or `null` Exceptions IllegalStateException: If this configuration has been deleted.

public String getFactoryPid()

For a factory configuration return the PID of the corresponding Managed Service Factory, else return null.

Returns:String

factory PID or null

Exceptions

IllegalStateException:: If this configuration has been deleted.

getPid back to summary

getPid	back to summary
public String getPid() Get the PID for this `Configuration` object. Returns:String the PID for this `Configuration` object. Exceptions IllegalStateException: if this configuration has been deleted

public String getPid()

Get the PID for this Configuration object.

Returns:String

the PID for this Configuration object.

Exceptions

IllegalStateException:: if this configuration has been deleted

getProcessedProperties back to summary

getProcessedProperties	back to summary
public Dictionary<String, Object> getProcessedProperties(ServiceReference<?> reference) Return the processed properties of this `Configuration` object. The `Dictionary` object returned is a private copy for the caller and may be changed without influencing the stored configuration. The keys in the returned dictionary are case insensitive and are always of type `String`. Before the properties are returned they are processed by all the registered `ConfigurationPlugin`s handling this configuration. If called just after the configuration is created and before update has been called, this method returns `null`. Parameters reference:ServiceReference<?> The reference to the Managed Service or Managed Service Factory to pass to the registered `ConfigurationPlugin`s handling this configuration. Must not be `null`. Returns:Dictionary<String, Object> A private copy of the processed properties for the caller or `null`. These properties must not contain the "service.bundleLocation" property. The value of this property may be obtained from the `getBundleLocation()` method. Exceptions IllegalStateException: If this configuration has been deleted. Since 1.6

public Dictionary<String, Object> getProcessedProperties(ServiceReference<?> reference)

Return the processed properties of this Configuration object.

The Dictionary object returned is a private copy for the caller and may be changed without influencing the stored configuration. The keys in the returned dictionary are case insensitive and are always of type String.

Before the properties are returned they are processed by all the registered ConfigurationPlugins handling this configuration.

If called just after the configuration is created and before update has been called, this method returns null.

Parameters

reference:ServiceReference<?>: The reference to the Managed Service or Managed Service Factory to pass to the registered ConfigurationPlugins handling this configuration. Must not be null.

Returns:Dictionary<String, Object>

A private copy of the processed properties for the caller or null. These properties must not contain the "service.bundleLocation" property. The value of this property may be obtained from the getBundleLocation() method.

Exceptions

IllegalStateException:: If this configuration has been deleted.

Since

1.6

getProperties back to summary

getProperties	back to summary
public Dictionary<String, Object> getProperties() Return the properties of this `Configuration` object. The `Dictionary` object returned is a private copy for the caller and may be changed without influencing the stored configuration. The keys in the returned dictionary are case insensitive and are always of type `String`. If called just after the configuration is created and before update has been called, this method returns `null`. Returns:Dictionary<String, Object> A private copy of the properties for the caller or `null`. These properties must not contain the "service.bundleLocation" property. The value of this property may be obtained from the `getBundleLocation()` method. Exceptions IllegalStateException: If this configuration has been deleted.

public Dictionary<String, Object> getProperties()

Return the properties of this Configuration object. The Dictionary object returned is a private copy for the caller and may be changed without influencing the stored configuration. The keys in the returned dictionary are case insensitive and are always of type String.

If called just after the configuration is created and before update has been called, this method returns null.

Returns:Dictionary<String, Object>

A private copy of the properties for the caller or null. These properties must not contain the "service.bundleLocation" property. The value of this property may be obtained from the getBundleLocation() method.

Exceptions

IllegalStateException:: If this configuration has been deleted.

hashCode	back to summary
public int hashCode() Hash code is based on PID. The hash code for two Configuration objects must be the same when the Configuration PID's are the same. Returns:int hash code for this Configuration object Annotations @Override

hashCode

back to summary

public int hashCode()

Hash code is based on PID. The hash code for two Configuration objects must be the same when the Configuration PID's are the same.

Returns:int

hash code for this Configuration object

Annotations

@Override

removeAttributes	back to summary
public void removeAttributes(Configuration.ConfigurationAttribute... attrs) throws IOException Remove attributes from this configuration. Parameters attrs:Configuration.ConfigurationAttribute[] The attributes to remove. Exceptions IOException: If the new state cannot be persisted. IllegalStateException: If this configuration has been deleted. SecurityException: when the required permissions are not available Since 1.6

removeAttributes

back to summary

public void removeAttributes(Configuration.ConfigurationAttribute... attrs) throws IOException

Remove attributes from this configuration.

Parameters

attrs:Configuration.ConfigurationAttribute[]: The attributes to remove.

Exceptions

IOException:: If the new state cannot be persisted.
IllegalStateException:: If this configuration has been deleted.
SecurityException:: when the required permissions are not available

Since

1.6

setBundleLocation back to summary

setBundleLocation	back to summary
public void setBundleLocation(String location) Bind this `Configuration` object to the specified location. If the location parameter is `null` then the `Configuration` object will not be bound to a location/region. It will be set to the bundle's location before the first time a Managed Service/Managed Service Factory receives this `Configuration` object via the updated method and before any plugins are called. The bundle location or region will be set persistently. If the location starts with `?` then all targets registered with the given PID must be updated. If the location is changed then existing targets must be informed. If they can no longer see this configuration, the configuration must be deleted or updated with `null`. If this configuration becomes visible then they must be updated with this configuration. Also notifies all Configuration Listeners with a `ConfigurationEvent#CM_LOCATION_CHANGED` event. Parameters location:String a location, region, or `null` Exceptions IllegalStateException: If this configuration has been deleted. SecurityException: when the required permissions are not available

public void setBundleLocation(String location)

Bind this Configuration object to the specified location. If the location parameter is null then the Configuration object will not be bound to a location/region. It will be set to the bundle's location before the first time a Managed Service/Managed Service Factory receives this Configuration object via the updated method and before any plugins are called. The bundle location or region will be set persistently.

If the location starts with ? then all targets registered with the given PID must be updated.

If the location is changed then existing targets must be informed. If they can no longer see this configuration, the configuration must be deleted or updated with null. If this configuration becomes visible then they must be updated with this configuration.

Also notifies all Configuration Listeners with a ConfigurationEvent#CM_LOCATION_CHANGED event.

Parameters

location:String: a location, region, or null

Exceptions

IllegalStateException:: If this configuration has been deleted.
SecurityException:: when the required permissions are not available

update back to summary

update	back to summary
public void update(Dictionary<String, ?> properties) throws IOException Update the properties of this `Configuration` object. Stores the properties in persistent storage after adding or overwriting the following properties: "service.pid" : is set to be the PID of this configuration. "service.factoryPid" : if this is a factory configuration it is set to the factory PID else it is not set. These system properties are all of type `String`. If the corresponding Managed Service/Managed Service Factory is registered, its updated method must be called asynchronously. Else, this callback is delayed until aforementioned registration occurs. Also notifies all Configuration Listeners with a `ConfigurationEvent#CM_UPDATED` event. Parameters properties:Dictionary<String, ?> the new set of properties for this configuration Exceptions IOException: if update cannot be made persistent ReadOnlyConfigurationException: If the configuration is `read only`. IllegalArgumentException: if the `Dictionary` object contains invalid configuration types or contains case variants of the same key name. IllegalStateException: If this configuration has been deleted.

public void update(Dictionary<String, ?> properties) throws IOException

Update the properties of this Configuration object.

Stores the properties in persistent storage after adding or overwriting the following properties:

"service.pid" : is set to be the PID of this configuration.
"service.factoryPid" : if this is a factory configuration it is set to the factory PID else it is not set.

These system properties are all of type String.

If the corresponding Managed Service/Managed Service Factory is registered, its updated method must be called asynchronously. Else, this callback is delayed until aforementioned registration occurs.

Also notifies all Configuration Listeners with a ConfigurationEvent#CM_UPDATED event.

Parameters

properties:Dictionary<String, ?>: the new set of properties for this configuration

Exceptions

IOException:: if update cannot be made persistent
ReadOnlyConfigurationException:: If the configuration is read only.
IllegalArgumentException:: if the Dictionary object contains invalid configuration types or contains case variants of the same key name.
IllegalStateException:: If this configuration has been deleted.

update back to summary

update	back to summary
public void update() throws IOException Update the `Configuration` object with the current properties. Initiate the `updated` callback to the Managed Service or Managed Service Factory with the current properties asynchronously. This is the only way for a bundle that uses a Configuration Plugin service to initiate a callback. For example, when that bundle detects a change that requires an update of the Managed Service or Managed Service Factory via its `ConfigurationPlugin` object. Exceptions IOException: if update cannot access the properties in persistent storage IllegalStateException: If this configuration has been deleted. See Also `ConfigurationPlugin`

public void update() throws IOException

Update the Configuration object with the current properties. Initiate the updated callback to the Managed Service or Managed Service Factory with the current properties asynchronously.

This is the only way for a bundle that uses a Configuration Plugin service to initiate a callback. For example, when that bundle detects a change that requires an update of the Managed Service or Managed Service Factory via its ConfigurationPlugin object.

Exceptions

IOException:: if update cannot access the properties in persistent storage
IllegalStateException:: If this configuration has been deleted.

See Also

ConfigurationPlugin

updateIfDifferent back to summary

updateIfDifferent	back to summary
public boolean updateIfDifferent(Dictionary<String, ?> properties) throws IOException Update the properties of this `Configuration` object if the provided properties are different than the currently stored set. Properties are compared as follows. Scalars are compared using `equals` Arrays are compared using `Arrays.equals` Collections are compared using `equals` If the new properties are not different than the current properties, no operation is performed. Otherwise, the behavior of this method is identical to the `update(Dictionary)` method. Parameters properties:Dictionary<String, ?> The new set of properties for this configuration. Returns:boolean If the properties are different and the configuration is updated `true` is returned. If the properties are the same, `false` is returned. Exceptions IOException: If update cannot be made persistent. ReadOnlyConfigurationException: If the configuration is `read only`. IllegalArgumentException: If the `Dictionary` object contains invalid configuration types or contains case variants of the same key name. IllegalStateException: If this configuration has been deleted. Since 1.6

public boolean updateIfDifferent(Dictionary<String, ?> properties) throws IOException

Update the properties of this Configuration object if the provided properties are different than the currently stored set. Properties are compared as follows.

Scalars are compared using equals
Arrays are compared using Arrays.equals
Collections are compared using equals

If the new properties are not different than the current properties, no operation is performed. Otherwise, the behavior of this method is identical to the update(Dictionary) method.

Parameters

properties:Dictionary<String, ?>: The new set of properties for this configuration.

Returns:boolean

If the properties are different and the configuration is updated true is returned. If the properties are the same, false is returned.

Exceptions

IOException:: If update cannot be made persistent.
ReadOnlyConfigurationException:: If the configuration is read only.
IllegalArgumentException:: If the Dictionary object contains invalid configuration types or contains case variants of the same key name.
IllegalStateException:: If this configuration has been deleted.

Since

1.6

Modifier and Type	Method and Description
public static Configuration.ConfigurationAttribute	valueOf(String name)
public static Configuration.ConfigurationAttribute[]	values()

public Interface Configuration

Nested and Inner Type Summary

Method Summary

Method Detail

public final Enum Configuration.ConfigurationAttribute

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail