Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 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      | Character  | Boolean
      | vector     | arrays
     primitive   ::= long | int | short | char | byte | double | float
     arrays      ::= primitive '[]' | type '[]' | null
     vector      ::= Vector of type or null

This explicitly allows vectors and arrays of mixed types and containing `null`.

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.
`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.
`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.
`int` | `hashCode()` Hash code is based on PID.
`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:
    `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`. These properties must not contain the "service.bundleLocation" property. The value of this property may be obtained from the `getBundleLocation` method.
  Throws:
    `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.
  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.

  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
    `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 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.
  Throws:
    `java.io.IOException` - If delete fails
    `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:
    `IllegalStateException` - if this configuration has been deleted

### update

    public 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 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
    `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. The bundle location will be set persistently.

  This method requires `AdminPermission`.

  Parameters:
    `bundleLocation` - a bundle location or `null`
  Throws:
    `java.lang.SecurityException` - if the caller does not have `AdminPermission`
    `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`.
    `IllegalStateException` - if this `Configuration` object has been deleted.

### equals

    public 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

    public 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.
  Overrides:
    `hashCode` in class `java.lang.Object`
  Returns:
    hash code for this Configuration object

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) OSGi Alliance (2000, 2003). All Rights Reserved.