001 /*
002 * Copyright (c) OSGi Alliance (2001, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.cm;
017
018 import java.util.Dictionary;
019
020 import org.osgi.framework.ServiceReference;
021
022 /**
023 * A service interface for processing configuration dictionary before the
024 * update.
025 *
026 * <p>
027 * A bundle registers a <code>ConfigurationPlugin</code> object in order to
028 * process configuration updates before they reach the Managed Service or
029 * Managed Service Factory. The Configuration Admin service will detect
030 * registrations of Configuration Plugin services and must call these services
031 * every time before it calls the <code>ManagedService</code> or
032 * <code>ManagedServiceFactory</code>
033 * <code>updated</code> method. The
034 * Configuration Plugin service thus has the opportunity to view and modify the
035 * properties before they are passed to the Managed Service or Managed Service
036 * Factory.
037 *
038 * <p>
039 * Configuration Plugin (plugin) services have full read/write access to all
040 * configuration information. Therefore, bundles using this facility should be
041 * trusted. Access to this facility should be limited with
042 * <code>ServicePermission[ConfigurationPlugin,REGISTER]</code>.
043 * Implementations of a Configuration Plugin service should assure that they
044 * only act on appropriate configurations.
045 *
046 * <p>
047 * The <code>Integer</code> <code>service.cmRanking</code> registration
048 * property may be specified. Not specifying this registration property, or
049 * setting it to something other than an <code>Integer</code>, is the same as
050 * setting it to the <code>Integer</code> zero. The
051 * <code>service.cmRanking</code> property determines the order in which
052 * plugins are invoked. Lower ranked plugins are called before higher ranked
053 * ones. In the event of more than one plugin having the same value of
054 * <code>service.cmRanking</code>, then the Configuration Admin service
055 * arbitrarily chooses the order in which they are called.
056 *
057 * <p>
058 * By convention, plugins with <code>service.cmRanking< 0</code> or
059 * <code>service.cmRanking > 1000</code> should not make modifications to
060 * the properties.
061 *
062 * <p>
063 * The Configuration Admin service has the right to hide properties from
064 * plugins, or to ignore some or all the changes that they make. This might be
065 * done for security reasons. Any such behavior is entirely implementation
066 * defined.
067 *
068 * <p>
069 * A plugin may optionally specify a <code>cm.target</code> registration
070 * property whose value is the PID of the Managed Service or Managed Service
071 * Factory whose configuration updates the plugin is intended to intercept. The
072 * plugin will then only be called with configuration updates that are targeted
073 * at the Managed Service or Managed Service Factory with the specified PID.
074 * Omitting the <code>cm.target</code> registration property means that the
075 * plugin is called for all configuration updates.
076 *
077 * @version $Revision: 5673 $
078 */
079 public interface ConfigurationPlugin {
080 /**
081 * A service property to limit the Managed Service or Managed Service
082 * Factory configuration dictionaries a Configuration Plugin service
083 * receives.
084 *
085 * This property contains a <code>String[]</code> of PIDs. A Configuration
086 * Admin service must call a Configuration Plugin service only when this
087 * property is not set, or the target service's PID is listed in this
088 * property.
089 */
090 public static final String CM_TARGET = "cm.target";
091 /**
092 * A service property to specify the order in which plugins are invoked.
093 *
094 * This property contains an <code>Integer</code> ranking of the plugin.
095 * Not specifying this registration property, or setting it to something
096 * other than an <code>Integer</code>, is the same as setting it to the
097 * <code>Integer</code> zero. This property determines the order in which
098 * plugins are invoked. Lower ranked plugins are called before higher ranked
099 * ones.
100 *
101 * @since 1.2
102 */
103 public static final String CM_RANKING = "service.cmRanking";
104
105 /**
106 * View and possibly modify the a set of configuration properties before
107 * they are sent to the Managed Service or the Managed Service Factory. The
108 * Configuration Plugin services are called in increasing order of their
109 * <code>service.cmRanking</code> property. If this property is undefined
110 * or is a non- <code>Integer</code> type, 0 is used.
111 *
112 * <p>
113 * This method should not modify the properties unless the
114 * <code>service.cmRanking</code> of this plugin is in the range
115 * <code>0 <= service.cmRanking <= 1000</code>.
116 * <p>
117 * If this method throws any <code>Exception</code>, the Configuration
118 * Admin service must catch it and should log it.
119 *
120 * @param reference reference to the Managed Service or Managed Service
121 * Factory
122 * @param properties The configuration properties. This argument must not
123 * contain the "service.bundleLocation" property. The value of this
124 * property may be obtained from the
125 * <code>Configuration.getBundleLocation</code> method.
126 */
127 public void modifyConfiguration(ServiceReference reference,
128 Dictionary properties);
129 }