Source code: org/osgi/service/cm/ConfigurationPlugin.java
1 /*
2 * $Header: /cvshome/repository/org/osgi/service/cm/ConfigurationPlugin.java,v 1.8 2002/10/08 06:43:03 pkriens Exp $
3 *
4 * Copyright (c) The Open Services Gateway Initiative (2001, 2002).
5 * All Rights Reserved.
6 *
7 * Implementation of certain elements of the Open Services Gateway Initiative
8 * (OSGI) Specification may be subject to third party intellectual property
9 * rights, including without limitation, patent rights (such a third party may
10 * or may not be a member of OSGi). OSGi is not responsible and shall not be
11 * held responsible in any manner for identifying or failing to identify any or
12 * all such third party intellectual property rights.
13 *
14 * This document and the information contained herein are provided on an "AS
15 * IS" basis and OSGI DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
16 * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL
17 * NOT INFRINGE ANY RIGHTS AND ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
18 * FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL OSGI BE LIABLE FOR ANY
19 * LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF
20 * BUSINESS, OR FOR DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTIAL,
21 * PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND IN CONNECTION WITH THIS
22 * DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED OF THE
23 * POSSIBILITY OF SUCH LOSS OR DAMAGE.
24 *
25 * All Company, brand and product names may be trademarks that are the sole
26 * property of their respective owners. All rights reserved.
27 */
28
29 package org.osgi.service.cm;
30 import java.util.*;
31 import org.osgi.framework.*;
32
33 /**
34 * A service interface for processing configuration dictionary before the update.
35 *
36 * <p>A bundle registers a <tt>ConfigurationPlugin</tt> object in order to process
37 * configuration updates before they reach the Managed Service or Managed Service Factory.
38 * The Configuration Admin service will detect registrations
39 * of Configuration Plugin services and must call these services every
40 * time before it calls the <tt>ManagedService</tt> or <tt>ManagedServiceFactory</tt>
41 * <tt>updated</tt> method. The
42 * Configuration Plugin service thus has the opportunity to view and modify
43 * the properties before they are passed to the ManagedS ervice or
44 * Managed Service Factory.
45 *
46 * <p>Configuration Plugin (plugin) services have full read/write access to all
47 * configuration information. Therefore, bundles using this facility should
48 * be trusted. Access to this facility should be limited with <tt>ServicePermission[REGISTER, ConfigurationPlugin]</tt>.
49 * Implementations of a Configuration Plugin service should assure that they
50 * only act on appropriate configurations.
51 *
52 * <p>The <tt>Integer</tt> <tt>service.cmRanking</tt> registration
53 * property may be specified. Not specifying this registration
54 * property, or setting it to something other than an <tt>Integer</tt>, is the
55 * same as setting it to the <tt>Integer</tt> zero. The
56 * <tt>service.cmRanking</tt> property determines the order in which
57 * plugins are invoked. Lower ranked plugins are called before
58 * higher ranked ones. In the event of more than one plugin having
59 * the same value of <tt>service.cmRanking</tt>, then the
60 * Configuration Admin service arbitrarily chooses the order in which they are
61 * called.
62 *
63 * <p>By convention, plugins with <tt>service.cmRanking< 0</tt>
64 * or <tt>service.cmRanking > 1000</tt> should not make
65 * modifications to the properties.
66 *
67 * <p>The Configuration Admin service has the right to hide properties from
68 * plugins, or to ignore some or all the changes that they make. This
69 * might be done for security reasons. Any such behavior is entirely
70 * implementation defined.
71 *
72 * <p>A plugin may optionally specify a <tt>cm.target</tt> registration
73 * property whose value is the PID of the Managed Service or
74 * Managed Service Factory whose configuration updates the plugin
75 * is intended to intercept. The plugin will then only be called
76 * with configuration updates that are targetted at the
77 * Managed Service or Managed Service Factory with the specified
78 * PID. Omitting the <tt>cm.target</tt> registration property means
79 * that the plugin is called for all configuration updates.
80 *
81 * @version $Revision: 1.8 $
82 * @author Open Services Gateway Initiative
83 */
84
85 public interface ConfigurationPlugin {
86 /**
87 * A service property to limit the Managed Service or Managed Service Factory
88 * configuration dictionaries a Configuration Plugin service receives.
89 *
90 * This property contains a <tt>String[]</tt> of PIDs. A Configuration
91 * Admin service must call a Configuration Plugin service only
92 * when this property is not set, or the target service's PID
93 * is listed in this property.
94 */
95 String CM_TARGET = "cm.target";
96
97 /**
98 * View and possibly modify the a set of configuration properties
99 * before they are sent to the Managed Service or the
100 * Managed Service Factory. The Configuration Plugin services are called
101 * in increasing order of their <tt>service.cmRanking</tt> property.
102 * If this property is undefined or is a non-<tt>Integer</tt> type, 0 is used.
103 *
104 * <p>This method should not modify the properties unless the
105 * <tt>service.cmRanking</tt> of this plugin is in the range
106 * <tt>0 <= service.cmRanking <= 1000</tt>.
107 * <p>If this method throws any <tt>Exception</tt>, the Configuration Admin service
108 * must catch it and should log it.
109 *
110 * @param reference reference to the Managed Service or Managed Service Factory
111 * @param configuration The configuration properties.
112 * This argument must not contain the
113 * "service.bundleLocation" property. The value of this property
114 * may be obtained from the <tt>Configuration.getBundleLocation</tt> method.
115 */
116 void modifyConfiguration( ServiceReference reference, Dictionary properties );
117 }
118
119