felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r809193 - in /felix/trunk/configadmin: ./ src/main/java/org/osgi/ src/main/java/org/osgi/service/ src/main/java/org/osgi/service/cm/ src/main/resources/ src/main/resources/org/ src/main/resources/org/osgi/ src/main/resources/org/osgi/servic...
Date Sat, 29 Aug 2009 18:53:18 GMT
Author: fmeschbe
Date: Sat Aug 29 18:53:17 2009
New Revision: 809193

URL: http://svn.apache.org/viewvc?rev=809193&view=rev
Log:
FELIX-1541 Include official org.osgi.service.cm sources received
from BJ Hargrave with configadmin and ensure these are packaged
instead of the (older) ones from the org.osgi.compendium library.

Added:
    felix/trunk/configadmin/src/main/java/org/osgi/
    felix/trunk/configadmin/src/main/java/org/osgi/service/
    felix/trunk/configadmin/src/main/java/org/osgi/service/cm/
    felix/trunk/configadmin/src/main/java/org/osgi/service/cm/Configuration.java   (with props)
    felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java   (with props)
    felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java   (with props)
    felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java   (with props)
    felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java   (with props)
    felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java   (with props)
    felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java   (with props)
    felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedService.java   (with props)
    felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java   (with props)
    felix/trunk/configadmin/src/main/resources/
    felix/trunk/configadmin/src/main/resources/org/
    felix/trunk/configadmin/src/main/resources/org/osgi/
    felix/trunk/configadmin/src/main/resources/org/osgi/service/
    felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/
    felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/package.html   (with props)
    felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/packageinfo
Modified:
    felix/trunk/configadmin/pom.xml

Modified: felix/trunk/configadmin/pom.xml
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/pom.xml?rev=809193&r1=809192&r2=809193&view=diff
==============================================================================
--- felix/trunk/configadmin/pom.xml (original)
+++ felix/trunk/configadmin/pom.xml Sat Aug 29 18:53:17 2009
@@ -96,7 +96,7 @@
                         <Export-Package>
                             org.apache.felix.cm;
                             org.apache.felix.cm.file;version=1.0,
-                            org.osgi.service.cm;version=1.3
+                            org.osgi.service.cm;-split-package:=merge-first
                         </Export-Package>
                         <Private-Package>
                             org.apache.felix.cm.impl,

Added: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/Configuration.java
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/java/org/osgi/service/cm/Configuration.java?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/java/org/osgi/service/cm/Configuration.java (added)
+++ felix/trunk/configadmin/src/main/java/org/osgi/service/cm/Configuration.java Sat Aug 29 18:53:17 2009
@@ -0,0 +1,225 @@
+/*
+ * 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.io.IOException;
+import java.util.Dictionary;
+
+/**
+ * The configuration information for a <code>ManagedService</code> or
+ * <code>ManagedServiceFactory</code> object.
+ * 
+ * The Configuration Admin service uses this interface to represent the
+ * configuration information for a <code>ManagedService</code> or for a
+ * service instance of a <code>ManagedServiceFactory</code>.
+ * 
+ * <p>
+ * A <code>Configuration</code> object contains a configuration dictionary and
+ * allows the properties to be updated via this object. Bundles wishing to
+ * receive configuration dictionaries do not need to use this class - they
+ * register a <code>ManagedService</code> or
+ * <code>ManagedServiceFactory</code>. Only administrative bundles, and
+ * bundles wishing to update their own configurations need to use this class.
+ * 
+ * <p>
+ * The properties handled in this configuration have case insensitive
+ * <code>String</code> objects as keys. However, case is preserved from the
+ * last set key/value.
+ * <p>
+ * A configuration can be <i>bound </i> to a bundle location (
+ * <code>Bundle.getLocation()</code>). The purpose of binding a
+ * <code>Configuration</code> object to a location is to make it impossible
+ * for another bundle to forge a PID that would match this configuration. When a
+ * configuration is bound to a specific location, and a bundle with a different
+ * location registers a corresponding <code>ManagedService</code> object or
+ * <code>ManagedServiceFactory</code> object, then the configuration is not
+ * passed to the updated method of that object.
+ * 
+ * <p>
+ * If a configuration's location is <code>null</code>, it is not yet bound to
+ * a location. It will become bound to the location of the first bundle that
+ * registers a <code>ManagedService</code> or
+ * <code>ManagedServiceFactory</code> object with the corresponding PID.
+ * <p>
+ * The same <code>Configuration</code> object is used for configuring both a
+ * Managed Service Factory and a Managed Service. When it is important to
+ * differentiate between these two the term "factory configuration" is used.
+ * 
+ * @version $Revision$
+ */
+public interface Configuration {
+	/**
+	 * Get the PID for this <code>Configuration</code> object.
+	 * 
+	 * @return the PID for this <code>Configuration</code> object.
+	 * @throws IllegalStateException if this configuration has been deleted
+	 */
+	public String getPid();
+
+	/**
+	 * Return the properties of this <code>Configuration</code> object.
+	 * 
+	 * The <code>Dictionary</code> object returned is a private copy for the
+	 * caller and may be changed without influencing the stored configuration.
+	 * The keys in the returned dictionary are case insensitive and are always
+	 * of type <code>String</code>.
+	 * 
+	 * <p>
+	 * If called just after the configuration is created and before update has
+	 * been called, this method returns <code>null</code>.
+	 * 
+	 * @return A private copy of the properties for the caller or
+	 *         <code>null</code>. These properties must not contain the
+	 *         "service.bundleLocation" property. The value of this property may
+	 *         be obtained from the <code>getBundleLocation</code> method.
+	 * @throws IllegalStateException if this configuration has been deleted
+	 */
+	public Dictionary getProperties();
+
+	/**
+	 * Update the properties of this <code>Configuration</code> object.
+	 * 
+	 * Stores the properties in persistent storage after adding or overwriting
+	 * the following properties:
+	 * <ul>
+	 * <li>"service.pid" : is set to be the PID of this configuration.</li>
+	 * <li>"service.factoryPid" : if this is a factory configuration it is set
+	 * to the factory PID else it is not set.</li>
+	 * </ul>
+	 * These system properties are all of type <code>String</code>.
+	 * 
+	 * <p>
+	 * If the corresponding Managed Service/Managed Service Factory is
+	 * registered, its updated method must be called asynchronously. Else, this
+	 * callback is delayed until aforementioned registration occurs.
+	 * 
+	 * <p>
+	 * Also initiates an asynchronous call to all
+	 * <code>ConfigurationListener</code>s with a
+	 * <code>ConfigurationEvent.CM_UPDATED</code> event.
+	 * 
+	 * @param properties the new set of properties for this configuration
+	 * @throws IOException if update cannot be made persistent
+	 * @throws IllegalArgumentException if the <code>Dictionary</code> object
+	 *         contains invalid configuration types or contains case variants of
+	 *         the same key name.
+	 * @throws IllegalStateException if this configuration has been deleted
+	 */
+	public void update(Dictionary properties) throws IOException;
+
+	/**
+	 * Delete this <code>Configuration</code> object.
+	 * 
+	 * Removes this configuration object from the persistent store. Notify
+	 * asynchronously the corresponding Managed Service or Managed Service
+	 * Factory. A <code>ManagedService</code> object is notified by a call to
+	 * its <code>updated</code> method with a <code>null</code> properties
+	 * argument. A <code>ManagedServiceFactory</code> object is notified by a
+	 * call to its <code>deleted</code> method.
+	 * 
+	 * <p>
+	 * Also initiates an asynchronous call to all
+	 * <code>ConfigurationListener</code>s with a
+	 * <code>ConfigurationEvent.CM_DELETED</code> event.
+	 * 
+	 * @throws IOException If delete fails
+	 * @throws IllegalStateException if this configuration has been deleted
+	 */
+	public void delete() throws IOException;
+
+	/**
+	 * For a factory configuration return the PID of the corresponding Managed
+	 * Service Factory, else return <code>null</code>.
+	 * 
+	 * @return factory PID or <code>null</code>
+	 * @throws IllegalStateException if this configuration has been deleted
+	 */
+	public String getFactoryPid();
+
+	/**
+	 * Update the <code>Configuration</code> object with the current
+	 * properties.
+	 * 
+	 * Initiate the <code>updated</code> callback to the Managed Service or
+	 * Managed Service Factory with the current properties asynchronously.
+	 * 
+	 * <p>
+	 * This is the only way for a bundle that uses a Configuration Plugin
+	 * service to initiate a callback. For example, when that bundle detects a
+	 * change that requires an update of the Managed Service or Managed Service
+	 * Factory via its <code>ConfigurationPlugin</code> object.
+	 * 
+	 * @see ConfigurationPlugin
+	 * @throws IOException if update cannot access the properties in persistent
+	 *         storage
+	 * @throws IllegalStateException if this configuration has been deleted
+	 */
+	public void update() throws IOException;
+
+	/**
+	 * Bind this <code>Configuration</code> object to the specified bundle
+	 * location.
+	 * 
+	 * If the bundleLocation parameter is <code>null</code> then the
+	 * <code>Configuration</code> object will not be bound to a location. It
+	 * will be set to the bundle's location before the first time a Managed
+	 * Service/Managed Service Factory receives this <code>Configuration</code>
+	 * object via the updated method and before any plugins are called. The
+	 * bundle location will be set persistently.
+	 * 
+	 * @param bundleLocation a bundle location or <code>null</code>
+	 * @throws IllegalStateException If this configuration has been deleted.
+	 * @throws SecurityException If the caller does not have
+	 *         <code>ConfigurationPermission[*,CONFIGURE]</code>.
+	 */
+	public void setBundleLocation(String bundleLocation);
+
+	/**
+	 * Get the bundle location.
+	 * 
+	 * Returns the bundle location to which this configuration is bound, or
+	 * <code>null</code> if it is not yet bound to a bundle location.
+	 * 
+	 * @return location to which this configuration is bound, or
+	 *         <code>null</code>.
+	 * @throws IllegalStateException If this <code>Configuration</code> object
+	 *         has been deleted.
+	 * @throws SecurityException If the caller does not have
+	 *         <code>ConfigurationPermission[*,CONFIGURE]</code>.
+	 */
+	public String getBundleLocation();
+
+	/**
+	 * Equality is defined to have equal PIDs
+	 * 
+	 * Two Configuration objects are equal when their PIDs are equal.
+	 * 
+	 * @param other <code>Configuration</code> object to compare against
+	 * @return <code>true</code> if equal, <code>false</code> if not a
+	 *         <code>Configuration</code> object or one with a different PID.
+	 */
+	public boolean equals(Object other);
+
+	/**
+	 * Hash code is based on PID.
+	 * 
+	 * The hashcode for two Configuration objects must be the same when the
+	 * Configuration PID's are the same.
+	 * 
+	 * @return hash code for this Configuration object
+	 */
+	public int hashCode();
+}

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/Configuration.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/Configuration.java
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision Rev Url

Added: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java (added)
+++ felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java Sat Aug 29 18:53:17 2009
@@ -0,0 +1,255 @@
+/*
+ * 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.io.IOException;
+import java.util.Dictionary;
+
+import org.osgi.framework.InvalidSyntaxException;
+
+/**
+ * Service for administering configuration data.
+ * 
+ * <p>
+ * The main purpose of this interface is to store bundle configuration data
+ * persistently. This information is represented in <code>Configuration</code>
+ * objects. The actual configuration data is a <code>Dictionary</code> of
+ * properties inside a <code>Configuration</code> object.
+ * 
+ * <p>
+ * 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.
+ * 
+ * <p>
+ * Next, there is the concept of a factory where the Configuration Admin service
+ * will maintain 0 or more <code>Configuration</code> objects for a Managed
+ * Service Factory that is registered with the Framework.
+ * 
+ * <p>
+ * 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.
+ * 
+ * <p>
+ * 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</code> (persistent identifier or PID) must be used to
+ * identify this Managed Service or Managed Service Factory to the Configuration
+ * Admin service.
+ * 
+ * <p>
+ * When the ConfigurationAdmin detects the registration of a Managed Service, it
+ * checks its persistent storage for a configuration object whose
+ * <code>service.pid</code> property matches the PID service property (
+ * <code>service.pid</code>) of the Managed Service. If found, it calls
+ * {@link ManagedService#updated} method with the new properties. The
+ * implementation of a Configuration Admin service must run these call-backs
+ * asynchronously to allow proper synchronization.
+ * 
+ * <p>
+ * When the Configuration Admin service detects a Managed Service Factory
+ * registration, it checks its storage for configuration objects whose
+ * <code>service.factoryPid</code> property matches the PID service property of
+ * the Managed Service Factory. For each such <code>Configuration</code>
+ * objects, it calls the <code>ManagedServiceFactory.updated</code> method
+ * asynchronously with the new properties. The calls to the <code>updated</code>
+ * method of a <code>ManagedServiceFactory</code> must be executed sequentially
+ * and not overlap in time.
+ * 
+ * <p>
+ * 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 another bundle requires
+ * <code>ConfigurationPermission[*,CONFIGURE]</code>.
+ * 
+ * <p>
+ * <code>Configuration</code> objects can be <i>bound </i> to a specified bundle
+ * location. In this case, if a matching Managed Service or Managed Service
+ * Factory is registered by a bundle with a different location, then the
+ * Configuration Admin service must not do the normal callback, and it should
+ * log an error. In the case where a <code>Configuration</code> object is not
+ * bound, its location field is <code>null</code>, the Configuration Admin
+ * service will bind it to the location of the bundle that registers the first
+ * Managed Service or Managed Service Factory that has a corresponding PID
+ * property. When a <code>Configuration</code> object is bound to a bundle
+ * location in this manner, the Configuration Admin service must detect if the
+ * bundle corresponding to the location is uninstalled. If this occurs, the
+ * <code>Configuration</code> object is unbound, that is its location field is
+ * set back to <code>null</code>.
+ * 
+ * <p>
+ * 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</code> must use a
+ * {@link org.osgi.framework.ServiceFactory} to support this concept.
+ * 
+ * @version $Revision$
+ */
+public interface ConfigurationAdmin {
+	/**
+	 * Configuration property naming the Factory PID in the configuration
+	 * dictionary. The property's value is of type <code>String</code>.
+	 * 
+	 * @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</code> 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</code>.
+	 * 
+	 * @since 1.1
+	 */
+	public final static String	SERVICE_BUNDLELOCATION	= "service.bundleLocation";
+
+	/**
+	 * Create a new factory <code>Configuration</code> object with a new PID.
+	 * 
+	 * The properties of the new <code>Configuration</code> object are
+	 * <code>null</code> until the first time that its
+	 * {@link Configuration#update(Dictionary)} method is called.
+	 * 
+	 * <p>
+	 * It is not required that the <code>factoryPid</code> maps to a
+	 * registered Managed Service Factory.
+	 * <p>
+	 * The <code>Configuration</code> object is bound to the location of the
+	 * calling bundle.
+	 * 
+	 * @param factoryPid PID of factory (not <code>null</code>).
+	 * @return A new <code>Configuration</code> object.
+	 * @throws IOException if access to persistent storage fails.
+	 * @throws SecurityException if caller does not have <code>ConfigurationPermission[*,CONFIGURE]</code> and <code>factoryPid</code> is bound to another bundle.
+	 */
+	public Configuration createFactoryConfiguration(String factoryPid)
+			throws IOException;
+
+	/**
+	 * Create a new factory <code>Configuration</code> object with a new PID.
+	 * 
+	 * The properties of the new <code>Configuration</code> object are
+	 * <code>null</code> until the first time that its
+	 * {@link Configuration#update(Dictionary)} method is called.
+	 * 
+	 * <p>
+	 * It is not required that the <code>factoryPid</code> maps to a
+	 * registered Managed Service Factory.
+	 * 
+	 * <p>
+	 * The <code>Configuration</code> is bound to the location specified. If
+	 * this location is <code>null</code> it will be bound to the location of
+	 * the first bundle that registers a Managed Service Factory with a
+	 * corresponding PID.
+	 * 
+	 * @param factoryPid PID of factory (not <code>null</code>).
+	 * @param location A bundle location string, or <code>null</code>.
+	 * @return a new <code>Configuration</code> object.
+	 * @throws IOException if access to persistent storage fails.
+	 * @throws SecurityException if caller does not have <code>ConfigurationPermission[*,CONFIGURE]</code>.
+	 */
+	public Configuration createFactoryConfiguration(String factoryPid, String location)
+			throws IOException;
+
+	/**
+	 * Get an existing <code>Configuration</code> object from the persistent
+	 * store, or create a new <code>Configuration</code> object.
+	 * 
+	 * <p>
+	 * If a <code>Configuration</code> with this PID already exists in
+	 * Configuration Admin service return it. The location parameter is ignored
+	 * in this case.
+	 * 
+	 * <p>
+	 * Else, return a new <code>Configuration</code> object. This new object
+	 * is bound to the location and the properties are set to <code>null</code>.
+	 * If the location parameter is <code>null</code>, it will be set when a
+	 * Managed Service with the corresponding PID is registered for the first
+	 * time.
+	 * 
+	 * @param pid Persistent identifier.
+	 * @param location The bundle location string, or <code>null</code>.
+	 * @return An existing or new <code>Configuration</code> object.
+	 * @throws IOException if access to persistent storage fails.
+	 * @throws SecurityException if the caller does not have <code>ConfigurationPermission[*,CONFIGURE]</code>.
+	 */
+	public Configuration getConfiguration(String pid, String location)
+			throws IOException;
+
+	/**
+	 * Get an existing or new <code>Configuration</code> object from the
+	 * persistent store.
+	 * 
+	 * If the <code>Configuration</code> object for this PID does not exist,
+	 * create a new <code>Configuration</code> object for that PID, where
+	 * properties are <code>null</code>. Bind its location to the calling
+	 * bundle's location.
+	 * 
+	 * <p>
+	 * Otherwise, if the location of the existing <code>Configuration</code> object
+	 * is <code>null</code>, set it to the calling bundle's location.
+	 * 
+	 * @param pid persistent identifier.
+	 * @return an existing or new <code>Configuration</code> matching the PID.
+	 * @throws IOException if access to persistent storage fails.
+	 * @throws SecurityException if the <code>Configuration</code> object is bound to a location different from that of the calling bundle and it has no <code>ConfigurationPermission[*,CONFIGURE]</code>.
+	 */
+	public Configuration getConfiguration(String pid) throws IOException;
+
+	/**
+	 * List the current <code>Configuration</code> objects which match the
+	 * filter.
+	 * 
+	 * <p>
+	 * Only <code>Configuration</code> objects with non- <code>null</code>
+	 * properties are considered current. That is,
+	 * <code>Configuration.getProperties()</code> is guaranteed not to return
+	 * <code>null</code> for each of the returned <code>Configuration</code>
+	 * objects.
+	 * 
+	 * <p>
+	 * Normally only <code>Configuration</code> objects that are bound to the
+	 * location of the calling bundle are returned, or all if the caller has
+	 * <code>ConfigurationPermission[*,CONFIGURE]</code>.
+	 * 
+	 * <p>
+	 * The syntax of the filter string is as defined in the
+	 * {@link org.osgi.framework.Filter} class. The filter can test any
+	 * configuration properties including the following:
+	 * <ul>
+	 * <li><code>service.pid</code>-<code>String</code>- the PID under which
+	 * this is registered</li>
+	 * <li><code>service.factoryPid</code>-<code>String</code>- the factory if
+	 * applicable</li>
+	 * <li><code>service.bundleLocation</code>-<code>String</code>- the bundle
+	 * location</li>
+	 * </ul>
+	 * The filter can also be <code>null</code>, meaning that all
+	 * <code>Configuration</code> objects should be returned.
+	 * 
+	 * @param filter A filter string, or <code>null</code> to retrieve all
+	 *        <code>Configuration</code> objects.
+	 * @return All matching <code>Configuration</code> objects, or
+	 *         <code>null</code> if there aren't any.
+	 * @throws IOException if access to persistent storage fails
+	 * @throws InvalidSyntaxException if the filter string is invalid
+	 */
+	public Configuration[] listConfigurations(String filter) throws IOException,
+			InvalidSyntaxException;
+}

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision Rev Url

Added: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java (added)
+++ felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java Sat Aug 29 18:53:17 2009
@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) OSGi Alliance (2004, 2009). 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 Configuration Event.
+ * 
+ * <p>
+ * <code>ConfigurationEvent</code> objects are delivered to all registered
+ * <code>ConfigurationListener</code> service objects. ConfigurationEvents
+ * must be asynchronously delivered in chronological order with respect to each
+ * listener.
+ * 
+ * <p>
+ * A type code is used to identify the type of event. The following event types
+ * are defined:
+ * <ul>
+ * <li>{@link #CM_UPDATED}
+ * <li>{@link #CM_DELETED}
+ * </ul>
+ * Additional event types may be defined in the future.
+ * 
+ * <p>
+ * Security Considerations. <code>ConfigurationEvent</code> objects do not
+ * provide <code>Configuration</code> objects, so no sensitive configuration
+ * information is available from the event. If the listener wants to locate the
+ * <code>Configuration</code> object for the specified pid, it must use
+ * <code>ConfigurationAdmin</code>.
+ * 
+ * @see ConfigurationListener
+ * 
+ * @version $Revision$
+ * @since 1.2
+ */
+public class ConfigurationEvent {
+	/**
+	 * A <code>Configuration</code> has been updated.
+	 * 
+	 * <p>
+	 * This <code>ConfigurationEvent</code> type that indicates that a
+	 * <code>Configuration</code> object has been updated with new properties.
+	 * 
+	 * An event is fired when a call to {@link Configuration#update(Dictionary)}
+	 * successfully changes a configuration.
+	 * 
+	 * <p>
+	 * The value of <code>CM_UPDATED</code> is 1.
+	 */
+	public static final int			CM_UPDATED	= 1;
+	/**
+	 * A <code>Configuration</code> has been deleted.
+	 * 
+	 * <p>
+	 * This <code>ConfigurationEvent</code> type that indicates that a
+	 * <code>Configuration</code> object has been deleted.
+	 * 
+	 * An event is fired when a call to {@link Configuration#delete()}
+	 * successfully deletes a configuration.
+	 * 
+	 * <p>
+	 * The value of <code>CM_DELETED</code> is 2.
+	 */
+	public static final int			CM_DELETED	= 2;
+	/**
+	 * Type of this event.
+	 * 
+	 * @see #getType
+	 */
+	private final int				type;
+	/**
+	 * The factory pid associated with this event.
+	 */
+	private final String			factoryPid;
+	/**
+	 * The pid associated with this event.
+	 */
+	private final String			pid;
+	/**
+	 * The ConfigurationAdmin service which created this event.
+	 */
+	private final ServiceReference	reference;
+
+	/**
+	 * Constructs a <code>ConfigurationEvent</code> object from the given
+	 * <code>ServiceReference</code> object, event type, and pids.
+	 * 
+	 * @param reference The <code>ServiceReference</code> object of the
+	 *        Configuration Admin service that created this event.
+	 * @param type The event type. See {@link #getType}.
+	 * @param factoryPid The factory pid of the associated configuration if the
+	 *        target of the configuration is a ManagedServiceFactory. Otherwise
+	 *        <code>null</code> if the target of the configuration is a
+	 *        ManagedService.
+	 * @param pid The pid of the associated configuration.
+	 */
+	public ConfigurationEvent(ServiceReference reference, int type,
+			String factoryPid, String pid) {
+		this.reference = reference;
+		this.type = type;
+		this.factoryPid = factoryPid;
+		this.pid = pid;
+		if ((reference == null) || (pid == null)) {
+			throw new NullPointerException("reference and pid must not be null");
+		}
+	}
+
+	/**
+	 * Returns the factory pid of the associated configuration.
+	 * 
+	 * @return Returns the factory pid of the associated configuration if the
+	 *         target of the configuration is a ManagedServiceFactory. Otherwise
+	 *         <code>null</code> if the target of the configuration is a
+	 *         ManagedService.
+	 */
+	public String getFactoryPid() {
+		return factoryPid;
+	}
+
+	/**
+	 * Returns the pid of the associated configuration.
+	 * 
+	 * @return Returns the pid of the associated configuration.
+	 */
+	public String getPid() {
+		return pid;
+	}
+
+	/**
+	 * Return the type of this event.
+	 * <p>
+	 * The type values are:
+	 * <ul>
+	 * <li>{@link #CM_UPDATED}
+	 * <li>{@link #CM_DELETED}
+	 * </ul>
+	 * 
+	 * @return The type of this event.
+	 */
+	public int getType() {
+		return type;
+	}
+
+	/**
+	 * Return the <code>ServiceReference</code> object of the Configuration
+	 * Admin service that created this event.
+	 * 
+	 * @return The <code>ServiceReference</code> object for the Configuration
+	 *         Admin service that created this event.
+	 */
+	public ServiceReference getReference() {
+		return reference;
+	}
+}

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision Rev Url

Added: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java (added)
+++ felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java Sat Aug 29 18:53:17 2009
@@ -0,0 +1,104 @@
+/*
+ * 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;
+
+/**
+ * An <code>Exception</code> class to inform the Configuration Admin service
+ * of problems with configuration data.
+ * 
+ * @version $Revision$
+ */
+public class ConfigurationException extends Exception {
+	static final long	serialVersionUID	= -1690090413441769377L;
+
+	private final String		property;
+	private final String		reason;
+
+	/**
+	 * Create a <code>ConfigurationException</code> object.
+	 * 
+	 * @param property name of the property that caused the problem,
+	 *        <code>null</code> if no specific property was the cause
+	 * @param reason reason for failure
+	 */
+	public ConfigurationException(String property, String reason) {
+		super(property + " : " + reason);
+		this.property = property;
+		this.reason = reason;
+	}
+
+	/**
+	 * Create a <code>ConfigurationException</code> object.
+	 * 
+	 * @param property name of the property that caused the problem,
+	 *        <code>null</code> if no specific property was the cause
+	 * @param reason reason for failure
+	 * @param cause The cause of this exception.
+	 * @since 1.2
+	 */
+	public ConfigurationException(String property, String reason,
+			Throwable cause) {
+		super(property + " : " + reason, cause);
+		this.property = property;
+		this.reason = reason;
+	}
+
+	/**
+	 * Return the property name that caused the failure or null.
+	 * 
+	 * @return name of property or null if no specific property caused the
+	 *         problem
+	 */
+	public String getProperty() {
+		return property;
+	}
+
+	/**
+	 * Return the reason for this exception.
+	 * 
+	 * @return reason of the failure
+	 */
+	public String getReason() {
+		return reason;
+	}
+	
+	/**
+	 * Returns the cause of this exception or <code>null</code> if no cause was
+	 * set.
+	 * 
+	 * @return The cause of this exception or <code>null</code> if no cause was
+	 *         set.
+	 * @since 1.2
+	 */
+	public Throwable getCause() {
+		return super.getCause();
+	}
+
+	/**
+	 * Initializes the cause of this exception to the specified value.
+	 * 
+	 * @param cause The cause of this exception.
+	 * @return This exception.
+	 * @throws IllegalArgumentException If the specified cause is this
+	 *         exception.
+	 * @throws IllegalStateException If the cause of this exception has already
+	 *         been set.
+	 * @since 1.2
+	 */
+	public Throwable initCause(Throwable cause) {
+		return super.initCause(cause);
+	}
+}

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision Rev Url

Added: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java (added)
+++ felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java Sat Aug 29 18:53:17 2009
@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) OSGi Alliance (2004, 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;
+
+/**
+ * Listener for Configuration Events. When a <code>ConfigurationEvent</code>
+ * is fired, it is asynchronously delivered to a
+ * <code>ConfigurationListener</code>.
+ * 
+ * <p>
+ * <code>ConfigurationListener</code> objects are registered with the
+ * Framework service registry and are notified with a
+ * <code>ConfigurationEvent</code> object when an event is fired.
+ * <p>
+ * <code>ConfigurationListener</code> objects can inspect the received
+ * <code>ConfigurationEvent</code> object to determine its type, the pid of
+ * the <code>Configuration</code> object with which it is associated, and the
+ * Configuration Admin service that fired the event.
+ * 
+ * <p>
+ * Security Considerations. Bundles wishing to monitor configuration events will
+ * require <code>ServicePermission[ConfigurationListener,REGISTER]</code> to
+ * register a <code>ConfigurationListener</code> service.
+ * 
+ * @version $Revision$
+ * @since 1.2
+ */
+public interface ConfigurationListener {
+	/**
+	 * Receives notification of a Configuration that has changed.
+	 * 
+	 * @param event The <code>ConfigurationEvent</code>.
+	 */
+	public void configurationEvent(ConfigurationEvent event);
+}

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision Rev Url

Added: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java (added)
+++ felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java Sat Aug 29 18:53:17 2009
@@ -0,0 +1,220 @@
+/*
+ * Copyright (c) OSGi Alliance (2004, 2009). 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.security.BasicPermission;
+import java.security.Permission;
+import java.security.PermissionCollection;
+import java.util.Enumeration;
+import java.util.NoSuchElementException;
+
+/**
+ * Indicates a bundle's authority to configure bundles.
+ * 
+ * This permission has only a single action: CONFIGURE.
+ * 
+ * @ThreadSafe
+ * @version $Revision$
+ * @since 1.2
+ */
+
+public final class ConfigurationPermission extends BasicPermission {
+	static final long			serialVersionUID	= 5716868734811965383L;
+	/**
+	 * The action string <code>configure</code>.
+	 */
+	public final static String	CONFIGURE			= "configure";
+
+	/**
+	 * Create a new ConfigurationPermission.
+	 * 
+	 * @param name Name must be &quot;*&quot;.
+	 * @param actions <code>configure</code> (canonical order).
+	 */
+
+	public ConfigurationPermission(String name, String actions) {
+		super(name);
+		if (!name.equals("*")) {
+			throw new IllegalArgumentException("name must be *");
+		}
+		actions = actions.trim();
+		if (actions.equalsIgnoreCase(CONFIGURE)||actions.equals("*"))
+			return;
+		
+		throw new IllegalArgumentException("actions must be " + CONFIGURE);
+	}
+
+	/**
+	 * Determines if a <code>ConfigurationPermission</code> object "implies"
+	 * the specified permission.
+	 * 
+	 * @param p The target permission to check.
+	 * @return <code>true</code> if the specified permission is implied by
+	 *         this object; <code>false</code> otherwise.
+	 */
+
+	public boolean implies(Permission p) {
+		return p instanceof ConfigurationPermission;
+	}
+
+	/**
+	 * Determines the equality of two <code>ConfigurationPermission</code>
+	 * objects.
+	 * <p>
+	 * Two <code>ConfigurationPermission</code> objects are equal.
+	 * 
+	 * @param obj The object being compared for equality with this object.
+	 * @return <code>true</code> if <code>obj</code> is equivalent to this
+	 *         <code>ConfigurationPermission</code>; <code>false</code>
+	 *         otherwise.
+	 */
+	public boolean equals(Object obj) {
+		return obj instanceof ConfigurationPermission;
+	}
+
+	/**
+	 * Returns the hash code value for this object.
+	 * 
+	 * @return Hash code value for this object.
+	 */
+
+	public int hashCode() {
+		int h = 31 * 17 + getName().hashCode();
+		h = 31 * h + getActions().hashCode();
+		return h;
+	}
+
+	/**
+	 * Returns the canonical string representation of the
+	 * <code>ConfigurationPermission</code> actions.
+	 * 
+	 * <p>
+	 * Always returns present <code>ConfigurationPermission</code> actions in
+	 * the following order: <code>CONFIGURE</code>
+	 * 
+	 * @return Canonical string representation of the
+	 *         <code>ConfigurationPermission</code> actions.
+	 */
+	public String getActions() {
+		return CONFIGURE;
+	}
+
+	/**
+	 * Returns a new <code>PermissionCollection</code> object suitable for
+	 * storing <code>ConfigurationPermission</code>s.
+	 * 
+	 * @return A new <code>PermissionCollection</code> object.
+	 */
+	public PermissionCollection newPermissionCollection() {
+		return new ConfigurationPermissionCollection();
+	}
+}
+
+/**
+ * Stores a set of <code>ConfigurationPermission</code> permissions.
+ * 
+ * @see java.security.Permission
+ * @see java.security.Permissions
+ * @see java.security.PermissionCollection
+ */
+final class ConfigurationPermissionCollection extends PermissionCollection {
+	static final long	serialVersionUID	= -6917638867081695839L;
+	/**
+	 * True if collection is non-empty.
+	 * 
+	 * @serial
+	 */
+	private volatile boolean	hasElement;
+
+	/**
+	 * Creates an empty <tt>ConfigurationPermissionCollection</tt> object.
+	 * 
+	 */
+	public ConfigurationPermissionCollection() {
+		hasElement = false;
+	}
+
+	/**
+	 * Adds the specified permission to the
+	 * <tt>ConfigurationPermissionCollection</tt>. The key for the hash is
+	 * the interface name of the service.
+	 * 
+	 * @param permission The <tt>Permission</tt> object to add.
+	 * 
+	 * @exception IllegalArgumentException If the permission is not an
+	 *            <tt>ConfigurationPermission</tt>.
+	 * 
+	 * @exception SecurityException If this ConfigurationPermissionCollection
+	 *            object has been marked read-only.
+	 */
+
+	public void add(Permission permission) {
+		if (!(permission instanceof ConfigurationPermission)) {
+			throw new IllegalArgumentException("invalid permission: "
+					+ permission);
+		}
+
+		if (isReadOnly())
+			throw new SecurityException("attempt to add a Permission to a "
+					+ "readonly PermissionCollection");
+
+		hasElement = true;
+	}
+
+	/**
+	 * Determines if the specified set of permissions implies the permissions
+	 * expressed in the parameter <tt>permission</tt>.
+	 * 
+	 * @param p The Permission object to compare.
+	 * 
+	 * @return true if permission is a proper subset of a permission in the set;
+	 *         false otherwise.
+	 */
+
+	public boolean implies(Permission p) {
+		return hasElement && (p instanceof ConfigurationPermission);
+	}
+
+	/**
+	 * Returns an enumeration of an <tt>ConfigurationPermission</tt> object.
+	 * 
+	 * @return Enumeration of an <tt>ConfigurationPermission</tt> object.
+	 */
+
+	public Enumeration elements() {
+		final boolean nonEmpty = hasElement;
+		return new Enumeration() {
+			private boolean	more = nonEmpty;
+
+			public boolean hasMoreElements() {
+				return more;
+			}
+
+			public Object nextElement() {
+				if (more) {
+					more = false;
+
+					return new ConfigurationPermission("*",
+							ConfigurationPermission.CONFIGURE);
+				}
+				else {
+					throw new NoSuchElementException();
+				}
+			}
+		};
+	}
+}

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision Rev Url

Added: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java (added)
+++ felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java Sat Aug 29 18:53:17 2009
@@ -0,0 +1,129 @@
+/*
+ * 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.
+ * 
+ * <p>
+ * A bundle registers a <code>ConfigurationPlugin</code> 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 <code>ManagedService</code> or
+ * <code>ManagedServiceFactory</code>
+ * <code>updated</code> 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.
+ * 
+ * <p>
+ * 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
+ * <code>ServicePermission[ConfigurationPlugin,REGISTER]</code>.
+ * Implementations of a Configuration Plugin service should assure that they
+ * only act on appropriate configurations.
+ * 
+ * <p>
+ * The <code>Integer</code> <code>service.cmRanking</code> registration
+ * property may be specified. Not specifying this registration property, or
+ * setting it to something other than an <code>Integer</code>, is the same as
+ * setting it to the <code>Integer</code> zero. The
+ * <code>service.cmRanking</code> 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
+ * <code>service.cmRanking</code>, then the Configuration Admin service
+ * arbitrarily chooses the order in which they are called.
+ * 
+ * <p>
+ * By convention, plugins with <code>service.cmRanking&lt; 0</code> or
+ * <code>service.cmRanking &gt; 1000</code> should not make modifications to
+ * the properties.
+ * 
+ * <p>
+ * 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.
+ * 
+ * <p>
+ * A plugin may optionally specify a <code>cm.target</code> 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 <code>cm.target</code> registration property means that the
+ * plugin is called for all configuration updates.
+ * 
+ * @version $Revision$
+ */
+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 <code>String[]</code> 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 <code>Integer</code> ranking of the plugin.
+	 * Not specifying this registration property, or setting it to something
+	 * other than an <code>Integer</code>, is the same as setting it to the
+	 * <code>Integer</code> 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
+	 * <code>service.cmRanking</code> property. If this property is undefined
+	 * or is a non- <code>Integer</code> type, 0 is used.
+	 * 
+	 * <p>
+	 * This method should not modify the properties unless the
+	 * <code>service.cmRanking</code> of this plugin is in the range
+	 * <code>0 &lt;= service.cmRanking &lt;= 1000</code>.
+	 * <p>
+	 * If this method throws any <code>Exception</code>, 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
+	 *        <code>Configuration.getBundleLocation</code> method.
+	 */
+	public void modifyConfiguration(ServiceReference reference,
+			Dictionary properties);
+}

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision Rev Url

Added: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedService.java
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedService.java?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedService.java (added)
+++ felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedService.java Sat Aug 29 18:53:17 2009
@@ -0,0 +1,138 @@
+/*
+ * 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;
+
+/**
+ * A service that can receive configuration data from a Configuration Admin
+ * service.
+ * 
+ * <p>
+ * A Managed Service is a service that needs configuration data. Such an object
+ * should be registered with the Framework registry with the
+ * <code>service.pid</code> property set to some unique identifier called a
+ * PID.
+ * 
+ * <p>
+ * If the Configuration Admin service has a <code>Configuration</code> object
+ * corresponding to this PID, it will callback the <code>updated()</code>
+ * method of the <code>ManagedService</code> object, passing the properties of
+ * that <code>Configuration</code> object.
+ * 
+ * <p>
+ * If it has no such <code>Configuration</code> object, then it calls back
+ * with a <code>null</code> properties argument. Registering a Managed Service
+ * will always result in a callback to the <code>updated()</code> method
+ * provided the Configuration Admin service is, or becomes active. This callback
+ * must always be done asynchronously.
+ * 
+ * <p>
+ * Else, every time that either of the <code>updated()</code> methods is
+ * called on that <code>Configuration</code> object, the
+ * <code>ManagedService.updated()</code> method with the new properties is
+ * called. If the <code>delete()</code> method is called on that
+ * <code>Configuration</code> object, <code>ManagedService.updated()</code>
+ * is called with a <code>null</code> for the properties parameter. All these
+ * callbacks must be done asynchronously.
+ * 
+ * <p>
+ * The following example shows the code of a serial port that will create a port
+ * depending on configuration information.
+ * 
+ * <pre>
+ *  
+ *   class SerialPort implements ManagedService {
+ *  
+ *     ServiceRegistration registration;
+ *     Hashtable configuration;
+ *     CommPortIdentifier id;
+ *  
+ *     synchronized void open(CommPortIdentifier id,
+ *     BundleContext context) {
+ *       this.id = id;
+ *       registration = context.registerService(
+ *         ManagedService.class.getName(),
+ *         this,
+ *         getDefaults()
+ *       );
+ *     }
+ *  
+ *     Hashtable getDefaults() {
+ *       Hashtable defaults = new Hashtable();
+ *       defaults.put( &quot;port&quot;, id.getName() );
+ *       defaults.put( &quot;product&quot;, &quot;unknown&quot; );
+ *       defaults.put( &quot;baud&quot;, &quot;9600&quot; );
+ *       defaults.put( Constants.SERVICE_PID,
+ *         &quot;com.acme.serialport.&quot; + id.getName() );
+ *       return defaults;
+ *     }
+ *  
+ *     public synchronized void updated(
+ *       Dictionary configuration  ) {
+ *       if ( configuration == 
+ * <code>
+ * null
+ * </code>
+ *   )
+ *         registration.setProperties( getDefaults() );
+ *       else {
+ *         setSpeed( configuration.get(&quot;baud&quot;) );
+ *         registration.setProperties( configuration );
+ *       }
+ *     }
+ *     ...
+ *   }
+ *   
+ * </pre>
+ * 
+ * <p>
+ * As a convention, it is recommended that when a Managed Service is updated, it
+ * should copy all the properties it does not recognize into the service
+ * registration properties. This will allow the Configuration Admin service to
+ * set properties on services which can then be used by other applications.
+ * 
+ * @version $Revision$
+ */
+public interface ManagedService {
+	/**
+	 * Update the configuration for a Managed Service.
+	 * 
+	 * <p>
+	 * When the implementation of <code>updated(Dictionary)</code> detects any
+	 * kind of error in the configuration properties, it should create a new
+	 * <code>ConfigurationException</code> which describes the problem. This
+	 * can allow a management system to provide useful information to a human
+	 * administrator.
+	 * 
+	 * <p>
+	 * If this method throws any other <code>Exception</code>, the
+	 * Configuration Admin service must catch it and should log it.
+	 * <p>
+	 * The Configuration Admin service must call this method asynchronously
+	 * which initiated the callback. This implies that implementors of Managed
+	 * Service can be assured that the callback will not take place during
+	 * registration when they execute the registration in a synchronized method.
+	 * 
+	 * @param properties A copy of the Configuration properties, or
+	 *        <code>null</code>. This argument must not contain the
+	 *        "service.bundleLocation" property. The value of this property may
+	 *        be obtained from the <code>Configuration.getBundleLocation</code>
+	 *        method.
+	 * @throws ConfigurationException when the update fails
+	 */
+	public void updated(Dictionary properties) throws ConfigurationException;
+}

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedService.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedService.java
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision Rev Url

Added: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java (added)
+++ felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java Sat Aug 29 18:53:17 2009
@@ -0,0 +1,160 @@
+/*
+ * 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;
+
+/**
+ * Manage multiple service instances.
+ * 
+ * Bundles registering this interface are giving the Configuration Admin service
+ * the ability to create and configure a number of instances of a service that
+ * the implementing bundle can provide. For example, a bundle implementing a
+ * DHCP server could be instantiated multiple times for different interfaces
+ * using a factory.
+ * 
+ * <p>
+ * Each of these <i>service instances </i> is represented, in the persistent
+ * storage of the Configuration Admin service, by a factory
+ * <code>Configuration</code> object that has a PID. When such a
+ * <code>Configuration</code> is updated, the Configuration Admin service
+ * calls the <code>ManagedServiceFactory</code> updated method with the new
+ * properties. When <code>updated</code> is called with a new PID, the Managed
+ * Service Factory should create a new factory instance based on these
+ * configuration properties. When called with a PID that it has seen before, it
+ * should update that existing service instance with the new configuration
+ * information.
+ * 
+ * <p>
+ * In general it is expected that the implementation of this interface will
+ * maintain a data structure that maps PIDs to the factory instances that it has
+ * created. The semantics of a factory instance are defined by the Managed
+ * Service Factory. However, if the factory instance is registered as a service
+ * object with the service registry, its PID should match the PID of the
+ * corresponding <code>Configuration</code> object (but it should <b>not </b>
+ * be registered as a Managed Service!).
+ * 
+ * <p>
+ * An example that demonstrates the use of a factory. It will create serial
+ * ports under command of the Configuration Admin service.
+ * 
+ * <pre>
+ *  
+ *   class SerialPortFactory
+ *     implements ManagedServiceFactory {
+ *     ServiceRegistration registration;
+ *     Hashtable ports;
+ *     void start(BundleContext context) {
+ *       Hashtable properties = new Hashtable();
+ *       properties.put( Constants.SERVICE_PID,
+ *         &quot;com.acme.serialportfactory&quot; );
+ *       registration = context.registerService(
+ *         ManagedServiceFactory.class.getName(),
+ *         this,
+ *         properties
+ *       );
+ *     }
+ *     public void updated( String pid,
+ *       Dictionary properties  ) {
+ *       String portName = (String) properties.get(&quot;port&quot;);
+ *       SerialPortService port =
+ *         (SerialPort) ports.get( pid );
+ *       if ( port == null ) {
+ *         port = new SerialPortService();
+ *         ports.put( pid, port );
+ *         port.open();
+ *       }
+ *       if ( port.getPortName().equals(portName) )
+ *         return;
+ *       port.setPortName( portName );
+ *     }
+ *     public void deleted( String pid ) {
+ *       SerialPortService port =
+ *         (SerialPort) ports.get( pid );
+ *       port.close();
+ *       ports.remove( pid );
+ *     }
+ *     ...
+ *   }
+ *   
+ * </pre>
+ * 
+ * @version $Revision$
+ */
+public interface ManagedServiceFactory {
+	/**
+	 * Return a descriptive name of this factory.
+	 * 
+	 * @return the name for the factory, which might be localized
+	 */
+	public String getName();
+
+	/**
+	 * Create a new instance, or update the configuration of an existing
+	 * instance.
+	 * 
+	 * If the PID of the <code>Configuration</code> object is new for the
+	 * Managed Service Factory, then create a new factory instance, using the
+	 * configuration <code>properties</code> provided. Else, update the
+	 * service instance with the provided <code>properties</code>.
+	 * 
+	 * <p>
+	 * If the factory instance is registered with the Framework, then the
+	 * configuration <code>properties</code> should be copied to its registry
+	 * properties. This is not mandatory and security sensitive properties
+	 * should obviously not be copied.
+	 * 
+	 * <p>
+	 * If this method throws any <code>Exception</code>, the Configuration
+	 * Admin service must catch it and should log it.
+	 * 
+	 * <p>
+	 * When the implementation of updated detects any kind of error in the
+	 * configuration properties, it should create a new
+	 * {@link ConfigurationException} which describes the problem.
+	 * 
+	 * <p>
+	 * The Configuration Admin service must call this method asynchronously.
+	 * This implies that implementors of the <code>ManagedServiceFactory</code>
+	 * class can be assured that the callback will not take place during
+	 * registration when they execute the registration in a synchronized method.
+	 * 
+	 * @param pid The PID for this configuration.
+	 * @param properties A copy of the configuration properties. This argument
+	 *        must not contain the service.bundleLocation" property. The value
+	 *        of this property may be obtained from the
+	 *        <code>Configuration.getBundleLocation</code> method.
+	 * @throws ConfigurationException when the configuration properties are
+	 *         invalid.
+	 */
+	public void updated(String pid, Dictionary properties)
+			throws ConfigurationException;
+
+	/**
+	 * Remove a factory instance.
+	 * 
+	 * Remove the factory instance associated with the PID. If the instance was
+	 * registered with the service registry, it should be unregistered.
+	 * <p>
+	 * If this method throws any <code>Exception</code>, the Configuration
+	 * Admin service must catch it and should log it.
+	 * <p>
+	 * The Configuration Admin service must call this method asynchronously.
+	 * 
+	 * @param pid the PID of the service to be removed
+	 */
+	public void deleted(String pid);
+}

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: felix/trunk/configadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision Rev Url

Added: felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/package.html
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/package.html?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/package.html (added)
+++ felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/package.html Sat Aug 29 18:53:17 2009
@@ -0,0 +1,11 @@
+<!-- $Revision: 7356 $ -->
+<BODY>
+<p>Configuration Admin Package Version 1.3.
+<p>Bundles wishing to use this package must list the package
+in the Import-Package header of the bundle's manifest.
+For example:
+<pre>
+Import-Package: org.osgi.service.cm; version=&quot;[1.3,2.0)&quot;
+</pre>
+</BODY>
+

Propchange: felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/packageinfo
URL: http://svn.apache.org/viewvc/felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/packageinfo?rev=809193&view=auto
==============================================================================
--- felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/packageinfo (added)
+++ felix/trunk/configadmin/src/main/resources/org/osgi/service/cm/packageinfo Sat Aug 29 18:53:17 2009
@@ -0,0 +1 @@
+version 1.3



Mime
View raw message