ConfigurationPlugin


1   /*
2    * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationPlugin.java,v 1.11 2006/06/16 16:31:28 hargrave Exp $
3    *
4    * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.osgi.service.cm;
19  
20  import java.util.Dictionary  ;
21  
22  import org.osgi.framework.ServiceReference;
23  
24  /**
25   * A service interface for processing configuration dictionary before the
26   * update.
27   * 
28   * <p>
29   * A bundle registers a <code>ConfigurationPlugin</code> object in order to
30   * process configuration updates before they reach the Managed Service or
31   * Managed Service Factory. The Configuration Admin service will detect
32   * registrations of Configuration Plugin services and must call these services
33   * every time before it calls the <code>ManagedService</code> or
34   * <code>ManagedServiceFactory</code>
35   * <code>updated</code> method. The
36   * Configuration Plugin service thus has the opportunity to view and modify the
37   * properties before they are passed to the ManagedS ervice or Managed Service
38   * Factory.
39   * 
40   * <p>
41   * Configuration Plugin (plugin) services have full read/write access to all
42   * configuration information. Therefore, bundles using this facility should be
43   * trusted. Access to this facility should be limited with
44   * <code>ServicePermission[ConfigurationPlugin,REGISTER]</code>.
45   * Implementations of a Configuration Plugin service should assure that they
46   * only act on appropriate configurations.
47   * 
48   * <p>
49   * The <code>Integer</code> <code>service.cmRanking</code> registration
50   * property may be specified. Not specifying this registration property, or
51   * setting it to something other than an <code>Integer</code>, is the same as
52   * setting it to the <code>Integer</code> zero. The
53   * <code>service.cmRanking</code> property determines the order in which
54   * plugins are invoked. Lower ranked plugins are called before higher ranked
55   * ones. In the event of more than one plugin having the same value of
56   * <code>service.cmRanking</code>, then the Configuration Admin service
57   * arbitrarily chooses the order in which they are called.
58   * 
59   * <p>
60   * By convention, plugins with <code>service.cmRanking&lt; 0</code> or
61   * <code>service.cmRanking &gt; 1000</code> should not make modifications to
62   * the properties.
63   * 
64   * <p>
65   * The Configuration Admin service has the right to hide properties from
66   * plugins, or to ignore some or all the changes that they make. This might be
67   * done for security reasons. Any such behavior is entirely implementation
68   * defined.
69   * 
70   * <p>
71   * A plugin may optionally specify a <code>cm.target</code> registration
72   * property whose value is the PID of the Managed Service or Managed Service
73   * Factory whose configuration updates the plugin is intended to intercept. The
74   * plugin will then only be called with configuration updates that are targetted
75   * at the Managed Service or Managed Service Factory with the specified PID.
76   * Omitting the <code>cm.target</code> registration property means that the
77   * plugin is called for all configuration updates.
78   * 
79   * @version $Revision: 1.11 $
80   */
81  public interface ConfigurationPlugin {
82      /**
83       * A service property to limit the Managed Service or Managed Service
84       * Factory configuration dictionaries a Configuration Plugin service
85       * receives.
86       * 
87       * This property contains a <code>String[]</code> of PIDs. A Configuration
88       * Admin service must call a Configuration Plugin service only when this
89       * property is not set, or the target service's PID is listed in this
90       * property.
91       */
92      public static final String    CM_TARGET   = "cm.target";
93      /**
94       * A service property to specify the order in which plugins are invoked.
95       * 
96       * This property contains an <code>Integer</code> ranking of the plugin.
97       * Not specifying this registration property, or setting it to something
98       * other than an <code>Integer</code>, is the same as setting it to the
99       * <code>Integer</code> zero. This property determines the order in which
100      * plugins are invoked. Lower ranked plugins are called before higher ranked
101      * ones.
102      * 
103      * @since 1.2
104      */
105     public static final String    CM_RANKING  = "service.cmRanking";
106 
107     /**
108      * View and possibly modify the a set of configuration properties before
109      * they are sent to the Managed Service or the Managed Service Factory. The
110      * Configuration Plugin services are called in increasing order of their
111      * <code>service.cmRanking</code> property. If this property is undefined
112      * or is a non- <code>Integer</code> type, 0 is used.
113      * 
114      * <p>
115      * This method should not modify the properties unless the
116      * <code>service.cmRanking</code> of this plugin is in the range
117      * <code>0 &lt;= service.cmRanking &lt;= 1000</code>.
118      * <p>
119      * If this method throws any <code>Exception</code>, the Configuration
120      * Admin service must catch it and should log it.
121      * 
122      * @param reference reference to the Managed Service or Managed Service
123      *        Factory
124      * @param properties The configuration properties. This argument must not
125      *        contain the "service.bundleLocation" property. The value of this
126      *        property may be obtained from the
127      *        <code>Configuration.getBundleLocation</code> method.
128      */
129     public void modifyConfiguration(ServiceReference reference,
130             Dictionary   properties);
131 }
132
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags