| /* |
| * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/Configuration.java,v 1.17 2006/06/16 16:31:28 hargrave Exp $ |
| * |
| * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.osgi.service.cm; |
| |
| import java.io.IOException; |
| import java.util.Dictionary; |
| |
| /** |
| * The configuration information for a <code>ManagedService</code> or |
| * <code>ManagedServiceFactory</code> object. |
| * |
| * The Configuration Admin service uses this interface to represent the |
| * configuration information for a <code>ManagedService</code> or for a |
| * service instance of a <code>ManagedServiceFactory</code>. |
| * |
| * <p> |
| * A <code>Configuration</code> 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 <code>ManagedService</code> or |
| * <code>ManagedServiceFactory</code>. Only administrative bundles, and |
| * bundles wishing to update their own configurations need to use this class. |
| * |
| * <p> |
| * The properties handled in this configuration have case insensitive |
| * <code>String</code> objects as keys. However, case is preserved from the |
| * last set key/value. |
| * <p> |
| * A configuration can be <i>bound </i> to a bundle location ( |
| * <code>Bundle.getLocation()</code>). The purpose of binding a |
| * <code>Configuration</code> 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 <code>ManagedService</code> object or |
| * <code>ManagedServiceFactory</code> object, then the configuration is not |
| * passed to the updated method of that object. |
| * |
| * <p> |
| * If a configuration's location is <code>null</code>, it is not yet bound to |
| * a location. It will become bound to the location of the first bundle that |
| * registers a <code>ManagedService</code> or |
| * <code>ManagedServiceFactory</code> object with the corresponding PID. |
| * <p> |
| * The same <code>Configuration</code> 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.17 $ |
| */ |
| public interface Configuration { |
| /** |
| * Get the PID for this <code>Configuration</code> object. |
| * |
| * @return the PID for this <code>Configuration</code> object. |
| * @throws IllegalStateException if this configuration has been deleted |
| */ |
| public String getPid(); |
| |
| /** |
| * Return the properties of this <code>Configuration</code> object. |
| * |
| * The <code>Dictionary</code> 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 <code>String</code>. |
| * |
| * <p> |
| * If called just after the configuration is created and before update has |
| * been called, this method returns <code>null</code>. |
| * |
| * @return A private copy of the properties for the caller or |
| * <code>null</code>. These properties must not contain the |
| * "service.bundleLocation" property. The value of this property may |
| * be obtained from the <code>getBundleLocation</code> method. |
| * @throws IllegalStateException if this configuration has been deleted |
| */ |
| public Dictionary getProperties(); |
| |
| /** |
| * Update the properties of this <code>Configuration</code> object. |
| * |
| * Stores the properties in persistent storage after adding or overwriting |
| * the following properties: |
| * <ul> |
| * <li>"service.pid" : is set to be the PID of this configuration.</li> |
| * <li>"service.factoryPid" : if this is a factory configuration it is set |
| * to the factory PID else it is not set.</li> |
| * </ul> |
| * These system properties are all of type <code>String</code>. |
| * |
| * <p> |
| * 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. |
| * |
| * <p> |
| * Also intiates an asynchronous call to all |
| * <code>ConfigurationListener</code>s with a |
| * <code>ConfigurationEvent.CM_UPDATED</code> event. |
| * |
| * @param properties the new set of properties for this configuration |
| * @throws IOException if update cannot be made persistent |
| * @throws IllegalArgumentException if the <code>Dictionary</code> object |
| * contains invalid configuration types or contains case variants of |
| * the same key name. |
| * @throws IllegalStateException if this configuration has been deleted |
| */ |
| public void update(Dictionary properties) throws IOException; |
| |
| /** |
| * Delete this <code>Configuration</code> object. |
| * |
| * Removes this configuration object from the persistent store. Notify |
| * asynchronously the corresponding Managed Service or Managed Service |
| * Factory. A <code>ManagedService</code> object is notified by a call to |
| * its <code>updated</code> method with a <code>null</code> properties |
| * argument. A <code>ManagedServiceFactory</code> object is notified by a |
| * call to its <code>deleted</code> method. |
| * |
| * <p> |
| * Also intiates an asynchronous call to all |
| * <code>ConfigurationListener</code>s with a |
| * <code>ConfigurationEvent.CM_DELETED</code> event. |
| * |
| * @throws IOException If delete fails |
| * @throws IllegalStateException if this configuration has been deleted |
| */ |
| public void delete() throws IOException; |
| |
| /** |
| * For a factory configuration return the PID of the corresponding Managed |
| * Service Factory, else return <code>null</code>. |
| * |
| * @return factory PID or <code>null</code> |
| * @throws IllegalStateException if this configuration has been deleted |
| */ |
| public String getFactoryPid(); |
| |
| /** |
| * Update the <code>Configuration</code> object with the current |
| * properties. |
| * |
| * Initiate the <code>updated</code> callback to the Managed Service or |
| * Managed Service Factory with the current properties asynchronously. |
| * |
| * <p> |
| * 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 <code>ConfigurationPlugin</code> object. |
| * |
| * @see ConfigurationPlugin |
| * @throws IOException if update cannot access the properties in persistent |
| * storage |
| * @throws IllegalStateException if this configuration has been deleted |
| */ |
| public void update() throws IOException; |
| |
| /** |
| * Bind this <code>Configuration</code> object to the specified bundle |
| * location. |
| * |
| * If the bundleLocation parameter is <code>null</code> then the |
| * <code>Configuration</code> 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 <code>Configuration</code> |
| * object via the updated method and before any plugins are called. The |
| * bundle location will be set persistently. |
| * |
| * @param bundleLocation a bundle location or <code>null</code> |
| * @throws IllegalStateException If this configuration has been deleted. |
| * @throws SecurityException If the caller does not have |
| * <code>ConfigurationPermission[*,CONFIGURE]</code>. |
| */ |
| public void setBundleLocation(String bundleLocation); |
| |
| /** |
| * Get the bundle location. |
| * |
| * Returns the bundle location to which this configuration is bound, or |
| * <code>null</code> if it is not yet bound to a bundle location. |
| * |
| * @return location to which this configuration is bound, or |
| * <code>null</code>. |
| * @throws IllegalStateException If this <code>Configuration</code> object |
| * has been deleted. |
| * @throws SecurityException If the caller does not have |
| * <code>ConfigurationPermission[*,CONFIGURE]</code>. |
| */ |
| public String getBundleLocation(); |
| |
| /** |
| * Equality is defined to have equal PIDs |
| * |
| * Two Configuration objects are equal when their PIDs are equal. |
| * |
| * @param other <code>Configuration</code> object to compare against |
| * @return <code>true</code> if equal, <code>false</code> if not a |
| * <code>Configuration</code> object or one with a different PID. |
| */ |
| public 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 |
| */ |
| public int hashCode(); |
| } |