Configuration
Date: 2016-06-25

org.osgi.service.cm

## Interface Configuration

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

- - ### 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

    - #### 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

    - #### 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