org.osgi.service.cm
Interface Configuration

public interface Configuration

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 set of 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 is preserved from the last set key/value. The value of the property may be of the following types:

 type        = String | Integer | Long 
  | Float | Double | Byte 
  | Short | BigInteger
  | BigDecimal | Character 
  | Boolean | vector | arrays
 primitive   = long | int | short 
  | char | byte | double | float
 arrays      = primitive '[]' | type '[]'
 vector      = Vector of type
 

A configuration can be bound to a bundle location (Bundle.getLocation()). The purpose of binding a Configuration object to a location is to make it impossible for another bundle to forge a PID that would match this configuration. When a configuration is bound to a specific location, and a bundle with a different location registers a corresponding ManagedService object or ManagedServiceFactory object, then the configuration is not passed to the updated method of that object.

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.

Method Summary

void	delete() Delete this Configuration object.
java.lang.String	getBundleLocation() Get the bundle location.
java.lang.String	getFactoryPid() For a factory configuration return the PID of the corresponding Managed Service Factory, else return null.
java.lang.String	getPid() Get the PID for this Configuration object.
java.util.Dictionary	getProperties() Return the properties of this Configuration object.
void	setBundleLocation(java.lang.String bundleLocation) Bind this Configuration object to the specified bundle location.
void	update() Update the Configuration object with the current properties.
void	update(java.util.Dictionary properties) Update the properties of this Configuration object.

Method Detail

getPid

public java.lang.String getPid()

Get the PID for this Configuration object.

Returns:

the PID for this Configuration object.

Throws:

java.lang.IllegalStateException - if this configuration has been deleted

getProperties

public java.util.Dictionary 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:

A private copy of the properties for the caller or null.

Throws:

java.lang.IllegalStateException - if this configuration has been deleted

update

public void update(java.util.Dictionary properties)
            throws java.io.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.
• "service.bundleLocation" is set to the location to which this Configuration object is bound. If the location is null, this property is not set.

These system properties are all of type String.

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

Parameters:

properties - the new set of properties for this configuration

Throws:

java.io.IOException - if update cannot be made persistent

java.lang.IllegalArgumentException - if the Dictionary object contains invalid configuration types

java.lang.IllegalStateException - if this configuration has been deleted

delete

public void delete()
            throws java.io.IOException

Delete this Configuration object. Removes this configuration object from the persistent store. Notify on a different thread 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.

Throws:

java.io.IOException - If delete fails

java.lang.IllegalStateException - if this configuration has been deleted

getFactoryPid

public java.lang.String getFactoryPid()

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

Returns:

factory PID or null

Throws:

java.lang.IllegalStateException - if this configuration has been deleted

update

public void update()
            throws java.io.IOException

Update the Configuration object with the current properties. Initate the updated callback to the Managed Service or Managed Service Factory with the current properties on a different thread.

This is the only way for a bundle that uses a Configuration Plugin service to initate 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.

Throws:

java.io.IOException - if update cannot access the properties in persistent storage

java.lang.IllegalStateException - if this configuration has been deleted

See Also:

ConfigurationPlugin

setBundleLocation

public void setBundleLocation(java.lang.String bundleLocation)

Bind this Configuration object to the specified bundle location. If the bundleLocation parameter is null then the Configuration object will not be bound to a location. 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.

This method requires AdminPermission.

Parameters:

bundleLocation - a bundle location or null

Throws:

java.lang.SecurityException - if the caller does not have AdminPermission

java.lang.IllegalStateException - if this configuration has been deleted

getBundleLocation

public java.lang.String getBundleLocation()

Get the bundle location. Returns the bundle location to which this configuration is bound, or null if it is not yet bound to a bundle location.

This call requires AdminPermission.

Returns:

location to which this configuration is bound, or null.

Throws:

java.lang.SecurityException - if the caller does not have AdminPermission.

java.lang.IllegalStateException - if this Configuration object has been deleted.