org.osgi.service.cm.ConfigurationAdmin Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2001, 2009). 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;
import org.osgi.framework.InvalidSyntaxException;
/**
* Service for administering configuration data.
*
*
* 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
* service.pid property matches the PID service 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
* service.factoryPid property matches the PID service property 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
* ConfigurationPermission[*,CONFIGURE].
*
*
* 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 Configuration 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: 8483 $
*/
public interface ConfigurationAdmin {
/**
* Configuration 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";
/**
* Configuration 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(Dictionary)} 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 ConfigurationPermission[*,CONFIGURE] and factoryPid is bound to another bundle.
*/
public 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(Dictionary)} 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.
*
* @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 ConfigurationPermission[*,CONFIGURE].
*/
public 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.
*
* @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 ConfigurationPermission[*,CONFIGURE].
*/
public 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.
*
*
* Otherwise, if the location of the existing Configuration object
* is null, set it to the calling bundle's location.
*
* @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 ConfigurationPermission[*,CONFIGURE].
*/
public 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, or all if the caller has
* ConfigurationPermission[*,CONFIGURE].
*
*
* The syntax of the filter string is as defined in the
* {@link org.osgi.framework.Filter} class. The filter can test any
* configuration properties including the following:
*
* service.pid-String- the PID under which
* this is registeredservice.factoryPid-String- the factory if
* applicableservice.bundleLocation-String- the bundle
* location
* The filter can also be null, meaning that all
* Configuration objects should be returned.
*
* @param filter A filter string, or null to retrieve all
* Configuration objects.
* @return All matching Configuration objects, or
* null if there aren't any.
* @throws IOException if access to persistent storage fails
* @throws InvalidSyntaxException if the filter string is invalid
*/
public Configuration[] listConfigurations(String filter) throws IOException,
InvalidSyntaxException;
}