org.osgi.service.cm.ConfigurationAdmin Maven / Gradle / Ivy

Go to download
/*
 * 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;

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: 7356 $
 */
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 registered
	 * service.factoryPid-String- the factory if
	 * applicable
	 * service.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;
}