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. * * @version $Revision: 1.1.1.1 $ * @author Open Services Gateway Initiative */ public interface Configuration { /** * Get the PID for this Configuration object. * * @return the PID for this Configuration object. * @throws IllegalStateException if this configuration has been deleted */ String getPid(); /** * 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. * * @return 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 */ Dictionary getProperties(); /** * Update the properties of this Configuration object. * * Stores the properties in persistent storage after adding or overwriting * the following properties: *
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. * * @param properties the new set of properties for this configuration * @throws IOException if update cannot be made persistent * @throws IllegalArgumentException if the Dictionary object contains invalid configuration types * @throws IllegalStateException if this configuration has been deleted */ void update(Dictionary properties) throws 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 IOException If delete fails * @throws IllegalStateException if this configuration has been deleted */ void delete() throws IOException; /** * For a factory configuration return the PID of the * corresponding Managed Service Factory, else return null. * * @return factory PID or null * @throws IllegalStateException if this configuration has been deleted */ String getFactoryPid(); /** * 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. * * @see ConfigurationPlugin * @throws IOException if update cannot access the properties in persistent storage * @throws IllegalStateException if this configuration has been deleted */ void update() throws IOException; /** * 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. * * @param bundleLocation a bundle location or null * @throws SecurityException if the caller does not have AdminPermission * @throws IllegalStateException if this configuration has been deleted */ void setBundleLocation( String bundleLocation ); /** * 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. * * @return location to which this configuration is bound, or null. * @throws SecurityException if the caller does not have AdminPermission. * @throws IllegalStateException if this Configuration object has been deleted. */ String getBundleLocation(); /** * Equality is defined to have equal PIDs * * Two Configuration objects are equal when their PIDs are equal. * @param other Configuration object to compare against * @return true if equal, false if not a Configuration object or one with a * different PID. */ boolean equals( Object other ); /** * Hash code is based on PID. * * The hashcode for two Configuration objects must be the same when the * Configuration PID's are the same. * @return hash code for this Configuration object */ int hashCode(); }