Configuration (Knopflerfish OSGi 6.1.0 javadoc)

```
@ProviderType
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 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.

Author:

$Id: b9057fdde860ef0f0cd1cea06d1ba83da7498d52 $

ThreadSafe

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`delete()` Delete this `Configuration` object.
`boolean`	`equals(java.lang.Object other)` Equality is defined to have equal PIDs Two Configuration objects are equal when their PIDs are equal.
`java.lang.String`	`getBundleLocation()` Get the bundle location.
`long`	`getChangeCount()` Get the change count.
`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<java.lang.String,java.lang.Object>`	`getProperties()` Return the properties of this `Configuration` object.
`int`	`hashCode()` Hash code is based on PID.
`void`	`setBundleLocation(java.lang.String location)` Bind this `Configuration` object to the specified location.
`void`	`update()` Update the `Configuration` object with the current properties.
`void`	`update(java.util.Dictionary<java.lang.String,?> properties)` Update the properties of this `Configuration` object.

- Method Detail
  - getPid
```
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
```
java.util.Dictionary<java.lang.String,java.lang.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:
    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.
    
    Throws:
    
    java.lang.IllegalStateException - If this configuration has been deleted.
  - update
```
void update(java.util.Dictionary<java.lang.String,?> 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.
    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 - 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 or contains case variants of the same key name.
    
    java.lang.IllegalStateException - If this configuration has been deleted.
  - delete
```
void delete()
            throws java.io.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.
    
    Throws:
    
    java.io.IOException - If delete fails.
    
    java.lang.IllegalStateException - If this configuration has been deleted.
  - getFactoryPid
```
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
```
void update()
            throws java.io.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.
    
    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
```
void setBundleLocation(java.lang.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 - a location, region, or null
    
    Throws:
    
    java.lang.IllegalStateException - If this configuration has been deleted.
    
    java.lang.SecurityException - when the required permissions are not available
    
    java.lang.SecurityException - when the required permissions are not available
    Required Permissions
    
    ConfigurationPermission[this.location,CONFIGURE] if this.location is not null, ConfigurationPermission[location,CONFIGURE] if location is not null, ConfigurationPermission["*",CONFIGURE] if this.location is null or if location is null
  - getBundleLocation
```
java.lang.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:
    location to which this configuration is bound, or null.
    
    Throws:
    
    java.lang.IllegalStateException - If this configuration has been deleted.
    
    java.lang.SecurityException - when the required permissions are not available
    Required Permissions
    
    ConfigurationPermission[this.location,CONFIGURE] if this.location is not null, ConfigurationPermission["*",CONFIGURE] if this.location is null
  - getChangeCount
```
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:
    A monotonically increasing value reflecting changes in this Configuration.
    
    Throws:
    
    java.lang.IllegalStateException - If this configuration has been deleted.
    Since:
    
    1.5
  - equals
```
boolean equals(java.lang.Object other)
```
    Equality is defined to have equal PIDs Two Configuration objects are equal when their PIDs are equal.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    other - Configuration object to compare against
    
    Returns:
    true if equal, false if not a Configuration object or one with a different PID.
  - hashCode
```
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.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    hash code for this Configuration object

Interface Configuration

Method Summary

Method Detail

getPid

getProperties

update

delete

getFactoryPid

update

setBundleLocation

getBundleLocation

getChangeCount

equals

hashCode