The main purpose of this interface is to store bundle configuration * data persistently. This information is * represented in Configuration objects. The actual configuration * data is a Dictionary of properties inside a Configuration * object. * *
There are two principally different ways to manage * configurations. First there is the concept of a Managed Service, * where configuration data is uniquely associated with an object * registered with the service registry. * *
Next, there is the concept of a factory where the Configuration Admin * service will maintain 0 or more Configuration objects for a * Managed Service Factory that is registered with the Framework. * *
The first concept is intended for configuration data * about "things/services" whose existence is defined * externally, e.g. a specific printer. Factories are * intended for "things/services" that can be created any number of * times, e.g. a configuration for a DHCP server for different * networks. * *
Bundles that require configuration should register a * Managed Service or a Managed Service Factory in the service * registry. A registration property named service.pid (persistent * identifier or PID) must be used to identify this Managed Service or * Managed Service Factory to the Configuration Admin service. * *
When the ConfigurationAdmin detects the registration of a * Managed Service, it checks its persistent storage for a configuration * object whose PID matches the PID registration property (service.pid) of the * Managed Service. If found, it calls {@link ManagedService#updated} method * with the new properties. The implementation of a Configuration Admin service * must run these call-backs asynchronously to allow proper synchronization. * *
When the Configuration Admin service detects a Managed Service Factory * registration, it checks its storage for configuration objects whose * factoryPid matches the PID of the * Managed Service Factory. For each such Configuration objects, it * calls the ManagedServiceFactory.updated method asynchronously * with the new properties. The calls to the updated method * of a ManagedServiceFactory must be executed sequentially and not * overlap in time. * *
In general, bundles having permission to use the * Configuration Admin service can only access and modify their own * configuration information. Accessing or modifying the * configuration of another bundle requires AdminPermission. * *
Configuration objects can be bound to a specified bundle * location. In this case, if a matching Managed Service or * Managed Service Factory is registered by a bundle with a different * location, then the Configuration Admin service must not do the normal * callback, and it should log an error. In the case where a * Configuration object is not bound, its location field is null, the * Configuration Admin service will bind it to the location of the bundle that * registers the first Managed Service or Managed Service Factory that * has a corresponding PID property. * When a Configuration object is bound to a bundle location in this * manner, the Confguration Admin service must detect if the bundle corresponding * to the location is uninstalled. If this occurs, the Configuration * object is unbound, that is its location field is set back to null. * *
The method descriptions of this class refer to a concept of * "the calling bundle". This is a loose way of referring to the * bundle which obtained the Configuration Admin service from the * service registry. Implementations of ConfigurationAdmin * must use a {@link org.osgi.framework.ServiceFactory} to support this concept. * * @version $Revision: 1.1.1.1 $ * @author Open Services Gateway Initiative */ public interface ConfigurationAdmin { /** * Service property naming the Factory PID in the configuration dictionary. * The property's value is of type String. * * @since 1.1 */ public final static String SERVICE_FACTORYPID = "service.factoryPid"; /** * Service property naming the location of the bundle that is associated * with a a Configuration object. This property can be searched for * but must not appear in the configuration dictionary for security reason. * The property's value is of type String. * * @since 1.1 */ public final static String SERVICE_BUNDLELOCATION = "service.bundleLocation"; /** * Create a new factory Configuration object with a new PID. * * The properties of the new Configuration object are null until the first * time that its {@link Configuration#update} method is called. * *
It is not required that the factoryPid maps to a registered * Managed Service Factory. *
The Configuration object is bound to the location of the calling * bundle. * * @param factoryPid PID of factory (not null). * @return a new Configuration object. * @throws IOException if access to persistent storage fails. * @throws SecurityException if caller does not have AdminPermission and factoryPid is bound to another bundle. */ Configuration createFactoryConfiguration( String factoryPid ) throws IOException; /** * Create a new factory Configuration object with a new PID. * * The properties of the new Configuration object are null until the first * time that its {@link Configuration#update} method is called. * *
It is not required that the factoryPid maps to a registered * Managed Service Factory. * *
The Configuration is bound to the location specified. * If this location is null it will be bound to the location * of the first bundle that registers a Managed Service Factory with * a corresponding PID. * *
This method requires AdminPermission. * * @param factoryPid PID of factory (not null). * @param location a bundle location string, or null. * @return a new Configuration object. * @throws IOException if access to persistent storage fails. * @throws SecurityException if caller does not have AdminPermission. */ Configuration createFactoryConfiguration( String factoryPid, String location ) throws IOException; /** * Get an existing Configuration object from the persistent store, * or create a new Configuration object. * *
If a Configuration with this PID already exists in * Configuration Admin service return it. The location parameter is * ignored in this case. * *
Else, return a new Configuration object. This new object is * bound to the location and the properties are set to null. If the * location parameter is null, it will be set when a Managed Service with * the corresponding PID is registered for the first time. * *
This method requires AdminPermission. * @param pid persistent identifier. * @param location the bundle location string, or null. * @return an existing or new Configuration object. * @throws IOException if access to persistent storage fails. * @throws SecurityException if the caller does not have AdminPermission. */ Configuration getConfiguration( String pid, String location ) throws IOException; /** * Get an existing or new Configuration object from the persistent store. * * If the Configuration object for this PID does not exist, create a new * Configuration object for that PID, where properties are null. Bind * its location to the calling bundle's location. * *
Else, if the location of the existing Configuration object is null, * set it to the calling bundle's location. *
If the location of the Configuration object does not match the calling bundle, * throw a SecurityException. * * @param pid persistent identifier. * @return an existing or new Configuration matching the PID. * @throws IOException if access to persistent storage fails. * @throws SecurityException if the Configuration object is bound to a location different from that of the calling bundle and it has no AdminPermission. */ Configuration getConfiguration( String pid ) throws IOException; /** * List the current Configuration objects which match the filter. * *
Only Configuration objects with non-null properties are considered current. That is, * Configuration.getProperties() is guaranteed not to return null for each of the * returned Configuration objects. * *
Normally only Configuration objects that are bound to the location * of the calling bundle are returned. If the caller has AdminPermission, * then all matching Configuration objects are returned. * *
The syntax of the filter string is as defined in the Filter class. The * filter can test any configuration parameters including * the following system properties: *