org.osgi.service.cm.Configuration Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2001, 2008). 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 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.
*
* 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: 5673 $
*/
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
*/
public 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
*/
public Dictionary getProperties();
/**
* 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 initiates an asynchronous call to all
* ConfigurationListeners with a
* ConfigurationEvent.CM_UPDATED event.
*
* @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 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 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 initiates an asynchronous call to all
* ConfigurationListeners with a
* ConfigurationEvent.CM_DELETED 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 null.
*
* @return factory PID or null
* @throws IllegalStateException if this configuration has been deleted
*/
public 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 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.
*
* @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 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.
*
* @param bundleLocation a bundle location or null
* @throws IllegalStateException If this configuration has been deleted.
* @throws SecurityException If the caller does not have
* ConfigurationPermission[*,CONFIGURE].
*/
public 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.
*
* @return location to which this configuration is bound, or
* null.
* @throws IllegalStateException If this Configuration object
* has been deleted.
* @throws SecurityException If the caller does not have
* ConfigurationPermission[*,CONFIGURE].
*/
public 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.
*/
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();
}