org.osgi.service.cm.ConfigurationPlugin 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.util.Dictionary;
import org.osgi.framework.ServiceReference;
/**
* A service interface for processing configuration dictionary before the
* update.
*
*
* A bundle registers a ConfigurationPlugin object in order to
* process configuration updates before they reach the Managed Service or
* Managed Service Factory. The Configuration Admin service will detect
* registrations of Configuration Plugin services and must call these services
* every time before it calls the ManagedService or
* ManagedServiceFactory
* updated method. The
* Configuration Plugin service thus has the opportunity to view and modify the
* properties before they are passed to the Managed Service or Managed Service
* Factory.
*
*
* Configuration Plugin (plugin) services have full read/write access to all
* configuration information. Therefore, bundles using this facility should be
* trusted. Access to this facility should be limited with
* ServicePermission[ConfigurationPlugin,REGISTER].
* Implementations of a Configuration Plugin service should assure that they
* only act on appropriate configurations.
*
*
* The Integer service.cmRanking registration
* property may be specified. Not specifying this registration property, or
* setting it to something other than an Integer, is the same as
* setting it to the Integer zero. The
* service.cmRanking property determines the order in which
* plugins are invoked. Lower ranked plugins are called before higher ranked
* ones. In the event of more than one plugin having the same value of
* service.cmRanking, then the Configuration Admin service
* arbitrarily chooses the order in which they are called.
*
*
* By convention, plugins with service.cmRanking< 0 or
* service.cmRanking > 1000 should not make modifications to
* the properties.
*
*
* The Configuration Admin service has the right to hide properties from
* plugins, or to ignore some or all the changes that they make. This might be
* done for security reasons. Any such behavior is entirely implementation
* defined.
*
*
* A plugin may optionally specify a cm.target registration
* property whose value is the PID of the Managed Service or Managed Service
* Factory whose configuration updates the plugin is intended to intercept. The
* plugin will then only be called with configuration updates that are targeted
* at the Managed Service or Managed Service Factory with the specified PID.
* Omitting the cm.target registration property means that the
* plugin is called for all configuration updates.
*
* @version $Revision: 5673 $
*/
public interface ConfigurationPlugin {
/**
* A service property to limit the Managed Service or Managed Service
* Factory configuration dictionaries a Configuration Plugin service
* receives.
*
* This property contains a String[] of PIDs. A Configuration
* Admin service must call a Configuration Plugin service only when this
* property is not set, or the target service's PID is listed in this
* property.
*/
public static final String CM_TARGET = "cm.target";
/**
* A service property to specify the order in which plugins are invoked.
*
* This property contains an Integer ranking of the plugin.
* Not specifying this registration property, or setting it to something
* other than an Integer, is the same as setting it to the
* Integer zero. This property determines the order in which
* plugins are invoked. Lower ranked plugins are called before higher ranked
* ones.
*
* @since 1.2
*/
public static final String CM_RANKING = "service.cmRanking";
/**
* View and possibly modify the a set of configuration properties before
* they are sent to the Managed Service or the Managed Service Factory. The
* Configuration Plugin services are called in increasing order of their
* service.cmRanking property. If this property is undefined
* or is a non- Integer type, 0 is used.
*
*
* This method should not modify the properties unless the
* service.cmRanking of this plugin is in the range
* 0 <= service.cmRanking <= 1000.
*
* If this method throws any Exception, the Configuration
* Admin service must catch it and should log it.
*
* @param reference reference to the Managed Service or Managed Service
* Factory
* @param properties The configuration properties. This argument must not
* contain the "service.bundleLocation" property. The value of this
* property may be obtained from the
* Configuration.getBundleLocation method.
*/
public void modifyConfiguration(ServiceReference reference,
Dictionary properties);
}