Interface Configuration
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 is preserved from the
last set key/value.
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.
- Version:
- $Revision: 5673 $
-
Method Summary
Modifier and TypeMethodDescriptionvoid
delete()
Delete thisConfiguration
object.boolean
Equality is defined to have equal PIDs Two Configuration objects are equal when their PIDs are equal.Get the bundle location.For a factory configuration return the PID of the corresponding Managed Service Factory, else returnnull
.getPid()
Get the PID for thisConfiguration
object.Return the properties of thisConfiguration
object.int
hashCode()
Hash code is based on PID.void
setBundleLocation
(String bundleLocation) Bind thisConfiguration
object to the specified bundle location.void
update()
Update theConfiguration
object with the current properties.void
update
(Dictionary properties) Update the properties of thisConfiguration
object.
-
Method Details
-
getPid
String getPid()Get the PID for thisConfiguration
object.- Returns:
- the PID for this
Configuration
object. - Throws:
IllegalStateException
- if this configuration has been deleted
-
getProperties
Dictionary getProperties()Return the properties of thisConfiguration
object. TheDictionary
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 typeString
.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
. These properties must not contain the "service.bundleLocation" property. The value of this property may be obtained from thegetBundleLocation
method. - Throws:
IllegalStateException
- if this configuration has been deleted
-
update
Update the properties of thisConfiguration
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.
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 initiates an asynchronous call to all
ConfigurationListener
s with aConfigurationEvent.CM_UPDATED
event.- Parameters:
properties
- the new set of properties for this configuration- Throws:
IOException
- if update cannot be made persistentIllegalArgumentException
- if theDictionary
object contains invalid configuration types or contains case variants of the same key name.IllegalStateException
- if this configuration has been deleted
-
delete
Delete thisConfiguration
object. Removes this configuration object from the persistent store. Notify asynchronously the corresponding Managed Service or Managed Service Factory. AManagedService
object is notified by a call to itsupdated
method with anull
properties argument. AManagedServiceFactory
object is notified by a call to itsdeleted
method.Also initiates an asynchronous call to all
ConfigurationListener
s with aConfigurationEvent.CM_DELETED
event.- Throws:
IOException
- If delete failsIllegalStateException
- if this configuration has been deleted
-
getFactoryPid
String getFactoryPid()For a factory configuration return the PID of the corresponding Managed Service Factory, else returnnull
.- Returns:
- factory PID or
null
- Throws:
IllegalStateException
- if this configuration has been deleted
-
update
Update theConfiguration
object with the current properties. Initiate theupdated
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.- Throws:
IOException
- if update cannot access the properties in persistent storageIllegalStateException
- if this configuration has been deleted- See Also:
-
setBundleLocation
Bind thisConfiguration
object to the specified bundle location. If the bundleLocation parameter isnull
then theConfiguration
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 thisConfiguration
object via the updated method and before any plugins are called. The bundle location will be set persistently.- Parameters:
bundleLocation
- a bundle location ornull
- Throws:
IllegalStateException
- If this configuration has been deleted.SecurityException
- If the caller does not haveConfigurationPermission[*,CONFIGURE]
.
-
getBundleLocation
String getBundleLocation()Get the bundle location. Returns the bundle location to which this configuration is bound, ornull
if it is not yet bound to a bundle location.- Returns:
- location to which this configuration is bound, or
null
. - Throws:
IllegalStateException
- If thisConfiguration
object has been deleted.SecurityException
- If the caller does not haveConfigurationPermission[*,CONFIGURE]
.
-
equals
Equality is defined to have equal PIDs Two Configuration objects are equal when their PIDs are equal. -
hashCode
int hashCode()Hash code is based on PID. The hashcode for two Configuration objects must be the same when the Configuration PID's are the same.
-