org.osgi.service.cm.ConfigurationAdmin Maven / Gradle / Ivy
Show all versions of org.osgi.compendium Show documentation
/*
* Copyright (c) OSGi Alliance (2001, 2011). 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.Filter;
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 {@code Configuration}
* objects. The actual configuration data is a {@code Dictionary} of properties
* inside a {@code 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 {@code 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 {@code 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
* {@code service.pid} property matches the PID service property (
* {@code service.pid}) of the Managed Service. If found, it calls
* {@link ManagedService#updated(Dictionary)} 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
* {@code service.factoryPid} property matches the PID service property of the
* Managed Service Factory. For each such {@code Configuration} objects, it
* calls the {@code ManagedServiceFactory.updated} method asynchronously with
* the new properties. The calls to the {@code updated} method of a
* {@code 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 other bundles requires
* {@code ConfigurationPermission[location,CONFIGURE]}, where location is the
* configuration location.
*
*
* {@code Configuration} objects can be bound to a specified bundle
* location or to a region (configuration location starts with {@code ?}). If a
* location is not set, it will be learned the first time a target is
* registered. If the location is learned this way, the Configuration Admin
* service must detect if the bundle corresponding to the location is
* uninstalled. If this occurs, the {@code Configuration} object must be
* unbound, that is its location field is set back to {@code null}.
*
*
* If target's bundle location matches the configuration location it is always
* updated.
*
*
* If the configuration location starts with {@code ?}, that is, the location is
* a region, then the configuration must be delivered to all targets registered
* with the given PID. If security is on, the target bundle must have
* Configuration Permission[location,TARGET], where location matches given the
* configuration location with wildcards as in the Filter substring match. The
* security must be verified using the
* {@link org.osgi.framework.Bundle#hasPermission(Object)} method on the target
* bundle.
*
*
* If a target cannot be updated because the location does not match or it has
* no permission and security is active then the Configuration Admin service
* must not do the normal callback.
*
*
* 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
* {@code ConfigurationAdmin} must use a
* {@link org.osgi.framework.ServiceFactory} to support this concept.
*
* @noimplement
* @version $Id: 08e1fd36041666fc8c8c3ea2bd10341dbad7127d $
*/
public interface ConfigurationAdmin {
/**
* Configuration property naming the Factory PID in the configuration
* dictionary. The property's value is of type {@code 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 {@code 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 {@code String}.
*
* @since 1.1
*/
public final static String SERVICE_BUNDLELOCATION = "service.bundleLocation";
/**
* Create a new factory {@code Configuration} object with a new PID.
*
* The properties of the new {@code Configuration} object are {@code null}
* until the first time that its {@link Configuration#update(Dictionary)}
* method is called.
*
*
* It is not required that the {@code factoryPid} maps to a registered
* Managed Service Factory.
*
*
* The {@code Configuration} object is bound to the location of the calling
* bundle. It is possible that the same factoryPid has associated
* configurations that are bound to different bundles. Bundles should only
* see the factory configurations that they are bound to or have the proper
* permission.
*
* @param factoryPid PID of factory (not {@code null}).
* @return A new {@code Configuration} object.
* @throws IOException if access to persistent storage fails.
*/
public Configuration createFactoryConfiguration(String factoryPid)
throws IOException;
/**
* Create a new factory {@code Configuration} object with a new PID.
*
* The properties of the new {@code Configuration} object are {@code null}
* until the first time that its {@link Configuration#update(Dictionary)}
* method is called.
*
*
* It is not required that the {@code factoryPid} maps to a registered
* Managed Service Factory.
*
*
* The {@code Configuration} is bound to the location specified. If this
* location is {@code null} it will be bound to the location of the first
* bundle that registers a Managed Service Factory with a corresponding PID.
* It is possible that the same factoryPid has associated configurations
* that are bound to different bundles. Bundles should only see the factory
* configurations that they are bound to or have the proper permission.
*
*
* If the location starts with {@code ?} then the configuration must be
* delivered to all targets with the corresponding PID.
*
* @param factoryPid PID of factory (not {@code null}).
* @param location A bundle location string, or {@code null}.
* @return a new {@code Configuration} object.
* @throws IOException if access to persistent storage fails.
* @throws SecurityException when the require permissions are not available
* @security ConfigurationPermission[location,CONFIGURE] if location is not
* {@code null}
* @security ConfigurationPermission["*",CONFIGURE] if location is
* {@code null}
*/
public Configuration createFactoryConfiguration(String factoryPid,
String location) throws IOException;
/**
* Get an existing {@code Configuration} object from the persistent store,
* or create a new {@code Configuration} object.
*
*
* If a {@code Configuration} with this PID already exists in Configuration
* Admin service return it. The location parameter is ignored in this case though it is still used for a security check.
*
*
* Else, return a new {@code Configuration} object. This new object is bound
* to the location and the properties are set to {@code null}. If the
* location parameter is {@code null}, it will be set when a Managed Service
* with the corresponding PID is registered for the first time. If the
* location starts with {@code ?} then the configuration is bound to all
* targets that are registered with the corresponding PID.
*
* @param pid Persistent identifier.
* @param location The bundle location string, or {@code null}.
* @return An existing or new {@code Configuration} object.
* @throws IOException if access to persistent storage fails.
* @throws SecurityException when the require permissions are not available
* @security ConfigurationPermission[*,CONFIGURE] if location is
* {@code null} or if the returned configuration {@code c} already
* exists and c.location is {@code null}
* @security ConfigurationPermission[location,CONFIGURE] if location is not
* {@code null}
* @security ConfigurationPermission[c.location,CONFIGURE] if the returned
* configuration {@code c} already exists and c.location is not
* {@code null}
*/
public Configuration getConfiguration(String pid, String location)
throws IOException;
/**
* Get an existing or new {@code Configuration} object from the persistent
* store.
*
* If the {@code Configuration} object for this PID does not exist, create a
* new {@code Configuration} object for that PID, where properties are
* {@code null}. Bind its location to the calling bundle's location.
*
*
* Otherwise, if the location of the existing {@code Configuration} object
* is {@code null}, set it to the calling bundle's location.
*
* @param pid persistent identifier.
* @return an existing or new {@code Configuration} matching the PID.
* @throws IOException if access to persistent storage fails.
* @throws SecurityException when the required permission is not available
* @security ConfigurationPermission[c.location,CONFIGURE] If the
* configuration {@code c} already exists and c.location is not
* {@code null}
*/
public Configuration getConfiguration(String pid) throws IOException;
/**
* List the current {@code Configuration} objects which match the filter.
*
*
* Only {@code Configuration} objects with non- {@code null} properties are
* considered current. That is, {@code Configuration.getProperties()} is
* guaranteed not to return {@code null} for each of the returned
* {@code Configuration} objects.
*
*
* When there is no security on then all configurations can be returned. If
* security is on, the caller must have
* ConfigurationPermission[location,CONFIGURE].
*
*
* The syntax of the filter string is as defined in the {@link Filter}
* class. The filter can test any configuration properties including the
* following:
*
* - {@code service.pid} - the persistent identity
* - {@code service.factoryPid} - the factory PID, if applicable
* - {@code service.bundleLocation} - the bundle location
*
* The filter can also be {@code null}, meaning that all
* {@code Configuration} objects should be returned.
*
* @param filter A filter string, or {@code null} to retrieve all
* {@code Configuration} objects.
* @return All matching {@code Configuration} objects, or {@code null} if
* there aren't any.
* @throws IOException if access to persistent storage fails
* @throws InvalidSyntaxException if the filter string is invalid
* @security ConfigurationPermission[c.location,CONFIGURE] Only
* configurations {@code c} are returned for which the caller has
* this permission
*/
public Configuration[] listConfigurations(String filter)
throws IOException, InvalidSyntaxException;
}