felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
Subject svn commit: r616813 [4/9] - in /felix/trunk/deploymentadmin: ./ src/ src/main/ src/main/java/ src/main/java/org/ src/main/java/org/apache/ src/main/java/org/apache/felix/ src/main/java/org/apache/felix/deploymentadmin/ src/main/java/org/apache/felix/de...
Date Wed, 30 Jan 2008 16:46:39 GMT
Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/ApplicationHandle.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/ApplicationHandle.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/ApplicationHandle.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/ApplicationHandle.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,291 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.application/src/org/osgi/service/application/ApplicationHandle.java,v 1.41 2006/07/10 12:02:31 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2004, 2006). 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.application;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.security.*;
+
+import org.osgi.framework.Constants;
+
+/**
+ * ApplicationHandle is an OSGi service interface which represents an instance
+ * of an application. It provides the functionality to query and manipulate the
+ * lifecycle state of the represented application instance. It defines constants
+ * for the lifecycle states.
+ */
+public abstract class ApplicationHandle {
+	/*
+	 * NOTE: An implementor may also choose to replace this class in
+	 * their distribution with a class that directly interfaces with the
+	 * org.osgi.service.application implementation. This replacement class MUST NOT alter the
+	 * public/protected signature of this class.
+	 */
+
+	/**
+	 * The property key for the unique identifier (PID) of the application
+	 * instance.
+	 */
+	public static final String APPLICATION_PID = Constants.SERVICE_PID;
+	
+	/**
+	 * The property key for the pid of the corresponding application descriptor.
+	 */
+	public final static String APPLICATION_DESCRIPTOR	= "application.descriptor";
+	
+	/**
+	 * The property key for the state of this appliction instance.
+	 */
+	public final static String APPLICATION_STATE		= "application.state";
+
+	/**
+	 * The application instance is running. This is the initial state of a newly
+	 * created application instance.
+	 */
+	public final static String RUNNING = "RUNNING";
+	
+  /**
+   * The application instance is being stopped. This is the state of the
+   * application instance during the execution of the <code>destroy()</code>
+   * method.
+   */
+	public final static String STOPPING = "STOPPING";
+
+	private final String instanceId;
+	
+	private final ApplicationDescriptor	descriptor;
+
+	/**
+	 * Application instance identifier is specified by the container when the
+	 * instance is created. The instance identifier must remain static for the 
+	 * lifetime of the instance, it must remain the same even across framework
+	 * restarts for the same application instance. This value must be the same
+	 * as the <code>service.pid</code> service property of this application
+	 * handle.
+	 * <p>
+	 * The instance identifier should follow the following scheme: 
+	 * &lt;<i>application descriptor PID</i>&gt;.&lt;<i>index</i>&gt;
+	 * where &lt;<i>application descriptor PID</i>&gt; is the PID of the 
+	 * corresponding <code>ApplicationDescriptor</code> and &lt;<i>index</i>&gt;
+	 * is a unique integer index assigned by the application container. 
+	 * Even after destroying the application index the same index value should not
+	 * be reused in a reasonably long timeframe.
+	 * 
+	 * @param instanceId the instance identifier of the represented application
+	 * instance. It must not be null.
+	 * 
+	 * @param descriptor the <code>ApplicationDescriptor</code> of the represented
+	 * application instance. It must not be null.
+	 * 
+	 * @throws NullPointerException if any of the arguments is null.
+	 */
+	protected ApplicationHandle(String instanceId, ApplicationDescriptor descriptor ) {
+		if( (null == instanceId) || (null == descriptor) ) {
+			throw new NullPointerException("Parameters must not be null!");
+		}
+		
+		this.instanceId	= instanceId;
+		this.descriptor = descriptor;
+
+		try {
+			delegate = new Delegate();
+			delegate.setApplicationHandle( this, descriptor.delegate );
+		}
+		catch (Exception e) {
+			// Too bad ...
+			e.printStackTrace();
+			System.err
+					.println("No implementation available for ApplicationDescriptor, property is: "
+							+ Delegate.cName);
+		}
+	}
+
+	/**
+	 * Retrieves the <code>ApplicationDescriptor</code> to which this 
+	 * <code>ApplicationHandle</code> belongs. 
+	 * 
+	 * @return The corresponding <code>ApplicationDescriptor</code>
+	 */
+	public final ApplicationDescriptor getApplicationDescriptor() {
+		return descriptor;
+	}
+
+	/**
+	 * Get the state of the application instance.
+	 * 
+	 * @return the state of the application.
+	 * 
+	 * @throws IllegalStateException
+	 *             if the application handle is unregistered
+	 */
+	public abstract String getState();
+
+	/**
+	 * Returns the unique identifier of this instance. This value is also
+	 * available as a service property of this application handle's service.pid.
+	 * 
+	 * @return the unique identifier of the instance
+	 */
+	public final String getInstanceId() {
+		return instanceId;
+	}
+
+	/**
+	 * The application instance's lifecycle state can be influenced by this
+	 * method. It lets the application instance perform operations to stop
+	 * the application safely, e.g. saving its state to a permanent storage.
+	 * <p>
+	 * The method must check if the lifecycle transition is valid; a STOPPING
+	 * application cannot be stopped. If it is invalid then the method must
+	 * exit. Otherwise the lifecycle state of the application instance must be
+	 * set to STOPPING. Then the destroySpecific() method must be called to
+	 * perform any application model specific steps for safe stopping of the
+	 * represented application instance.
+	 * <p>
+	 * At the end the <code>ApplicationHandle</code> must be unregistered. 
+	 * This method should  free all the resources related to this 
+	 * <code>ApplicationHandle</code>.
+	 * <p>
+	 * When this method is completed the application instance has already made
+	 * its operations for safe stopping, the ApplicationHandle has been
+	 * unregistered and its related resources has been freed. Further calls on
+	 * this application should not be made because they may have unexpected
+	 * results.
+	 * 
+	 * @throws SecurityException
+	 *             if the caller doesn't have "lifecycle"
+	 *             <code>ApplicationAdminPermission</code> for the corresponding application.
+	 * 
+	 * @throws IllegalStateException
+	 *             if the application handle is unregistered
+	 */
+	public final void destroy() {
+		try {
+			delegate.destroy();
+		}catch( SecurityException se ) {
+			descriptor.isLaunchableSpecific(); /* check whether the bundle was uninstalled */
+			                                   /* if yes, throws IllegalStateException */
+			throw se;                          /* otherwise throw the catched SecurityException */
+		}
+		destroySpecific();
+	}
+
+	/**
+	 * Called by the destroy() method to perform application model specific
+	 * steps to stop and destroy an application instance safely.
+	 * 
+	 * @throws IllegalStateException
+	 *             if the application handle is unregistered
+	 */
+	protected abstract void destroySpecific();
+	
+	Delegate	delegate;
+	
+
+	/**
+	 * This class will load the class named
+	 * by the org.osgi.vendor.application.ApplicationHandle and delegate
+	 * method calls to an instance of the class.
+	 */
+	static class Delegate {
+		static String cName;
+		static Class implementation;
+		static Method setApplicationHandle;
+		static Method destroy;
+
+		static {
+			AccessController.doPrivileged(new PrivilegedAction() {
+				public Object run(){			
+					cName = System.getProperty("org.osgi.vendor.application.ApplicationHandle");
+					if (cName == null) {
+						throw new NoClassDefFoundError("org.osgi.vendor.application.ApplicationHandle property must be set"); 
+					}
+					
+					try {
+						implementation = Class.forName(cName);
+					}
+					catch (ClassNotFoundException e) {
+						throw new NoClassDefFoundError(e.toString());
+					}
+					
+					try {
+						setApplicationHandle = implementation.getMethod("setApplicationHandle",
+								new Class[] {ApplicationHandle.class, Object.class});
+						destroy = implementation.getMethod("destroy",
+								new Class[] {});
+					}
+					catch (NoSuchMethodException e) {
+						throw new NoSuchMethodError(e.toString());
+					}
+					
+					return null;
+				}
+			});
+		}
+		
+		Object target; 
+		
+		Delegate() throws Exception {
+			target = AccessController.doPrivileged(new PrivilegedExceptionAction() {
+				public Object run() throws Exception {			
+					return implementation.newInstance();
+				}
+			});
+		}
+
+		void setApplicationHandle(ApplicationHandle d, ApplicationDescriptor.Delegate descriptor ) {
+			try {
+				try {
+					setApplicationHandle.invoke(target, new Object[] {d, descriptor.target});
+				}
+				catch (InvocationTargetException e) {
+					throw e.getTargetException();
+				}
+			}
+			catch (Error e) {
+				throw e;
+			}
+			catch (RuntimeException e) {
+				throw e;
+			}
+			catch (Throwable e) {
+				throw new RuntimeException(e.toString());
+			}
+		}
+		void destroy() {
+			try {
+				try {
+					destroy.invoke(target, new Object[] {});
+				}
+				catch (InvocationTargetException e) {
+					throw e.getTargetException();
+				}
+			}
+			catch (Error e) {
+				throw e;
+			}
+			catch (RuntimeException e) {
+				throw e;
+			}
+			catch (Throwable e) {
+				throw new RuntimeException(e.toString());
+			}
+		}
+	}
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/ScheduledApplication.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/ScheduledApplication.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/ScheduledApplication.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/ScheduledApplication.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,176 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.application/src/org/osgi/service/application/ScheduledApplication.java,v 1.20 2006/07/06 14:59:29 sboshev Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2004, 2006). 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.application;
+
+import java.util.Map;
+
+/**
+ * It is allowed to schedule an application based on a specific event.
+ * ScheduledApplication service keeps the schedule information. When the
+ * specified event is fired a new instance must be launched. Note that launching
+ * operation may fail because e.g. the application is locked.
+ * <p>
+ * Each <code>ScheduledApplication</code> instance has an identifier which is
+ * unique within the scope of the application being scheduled.
+ * <p>
+ * <code>ScheduledApplication</code> instances are registered as services.
+ * The {@link #APPLICATION_PID} service property contains the PID of the
+ * application being scheduled, the {@link #SCHEDULE_ID} service property
+ * contains the schedule identifier.
+ */
+public interface ScheduledApplication {
+    
+    /**
+     * The property key for the identifier of the application being scheduled.
+     */
+    public static final String APPLICATION_PID = ApplicationDescriptor.APPLICATION_PID;
+    
+    /**
+     * The property key for the schedule identifier. The identifier is unique
+     * within the scope of the application being scheduled.
+     */
+    public static final String SCHEDULE_ID = "schedule.id";
+    
+    /**
+     * The key for the startup argument used to pass the event object that 
+     * triggered the schedule to launch the application instance.
+     * The event is passed in a {@link java.security.GuardedObject}
+     * protected by the corresponding 
+     * {@link org.osgi.service.event.TopicPermission}.
+     */
+    public static final String TRIGGERING_EVENT = "org.osgi.triggeringevent";
+    
+    /**
+     * The topic name for the virtual timer topic. Time based schedules
+     * should be created using this topic.
+     */
+    public static final String TIMER_TOPIC = "org/osgi/application/timer";
+    
+    /**
+     * The name of the <i>year</i> attribute of a virtual timer event. The value is
+     * defined by {@link java.util.Calendar#YEAR}.
+     */
+    public static final String YEAR = "year";
+    
+    /**
+     * The name of the <i>month</i> attribute of a virtual timer event. The value is
+     * defined by {@link java.util.Calendar#MONTH}.
+     */
+    public static final String MONTH = "month";
+    
+    /**
+     * The name of the <i>day of month</i> attribute of a virtual timer event. The value is
+     * defined by {@link java.util.Calendar#DAY_OF_MONTH}.
+     */
+    public static final String DAY_OF_MONTH = "day_of_month";
+    
+    /**
+     * The name of the <i>day of week</i> attribute of a virtual timer event. The value is
+     * defined by {@link java.util.Calendar#DAY_OF_WEEK}.
+     */
+    public static final String DAY_OF_WEEK = "day_of_week";
+    
+    /**
+     * The name of the <i>hour of day</i> attribute of a virtual timer event. The value is
+     * defined by {@link java.util.Calendar#HOUR_OF_DAY}.
+     */
+    public static final String HOUR_OF_DAY = "hour_of_day";
+    
+    /**
+     * The name of the <i>minute</i> attribute of a virtual timer event. The value is
+     * defined by {@link java.util.Calendar#MINUTE}.
+     */
+    public static final String MINUTE = "minute";
+    
+    
+    /**
+     * Returns the identifier of this schedule. The identifier is unique within
+     * the scope of the application that the schedule is related to. 
+     * @return the identifier of this schedule
+     * 
+     */
+    public String getScheduleId();
+
+	/**
+	 * Queries the topic of the triggering event. The topic may contain a
+	 * trailing asterisk as wildcard.
+	 * 
+	 * @return the topic of the triggering event
+	 * 
+	 * @throws IllegalStateException
+	 *             if the scheduled application service is unregistered
+	 */
+	public String getTopic();
+
+	/**
+	 * Queries the event filter for the triggering event.
+	 * 
+	 * @return the event filter for triggering event
+	 * 
+	 * @throws IllegalStateException
+	 *             if the scheduled application service is unregistered
+	 */
+	public String getEventFilter();
+
+	/**
+	 * Queries if the schedule is recurring.
+	 * 
+	 * @return true if the schedule is recurring, otherwise returns false
+	 * 
+	 * @throws IllegalStateException
+	 *             if the scheduled application service is unregistered
+	 */
+	public boolean isRecurring();
+
+	/**
+	 * Retrieves the ApplicationDescriptor which represents the application and
+	 * necessary for launching.
+	 * 
+	 * @return the application descriptor that
+	 *         represents the scheduled application
+	 * 
+	 * @throws IllegalStateException
+	 *             if the scheduled application service is unregistered
+	 */
+	public ApplicationDescriptor getApplicationDescriptor();
+
+	/**
+	 * Queries the startup arguments specified when the application was
+	 * scheduled. The method returns a copy of the arguments, it is not possible
+	 * to modify the arguments after scheduling.
+	 * 
+	 * @return the startup arguments of the scheduled application. It may be
+	 *         null if null argument was specified.
+	 * 
+	 * @throws IllegalStateException
+	 *             if the scheduled application service is unregistered
+	 */
+	public Map getArguments();
+
+	/**
+	 * Cancels this schedule of the application.
+	 * 
+	 * @throws SecurityException
+	 *             if the caller doesn't have "schedule"
+	 *             ApplicationAdminPermission for the scheduled application.
+	 * @throws IllegalStateException
+	 *             if the scheduled application service is unregistered
+	 */
+	public void remove();
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/package.html
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/package.html?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/package.html (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/package.html Wed Jan 30 08:46:24 2008
@@ -0,0 +1 @@
+<!-- $Header: /cvshome/build/org.osgi.service.application/src/org/osgi/service/application/package.html,v 1.5 2006/07/12 21:07:13 hargrave Exp $ -->
<BODY>
<p>Application Package Version 1.0.
<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.application; version=1.0
</pre>
</BODY>
\ No newline at end of file

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/packageinfo
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/packageinfo?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/packageinfo (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/application/packageinfo Wed Jan 30 08:46:24 2008
@@ -0,0 +1 @@
+version 1.0

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/Configuration.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/Configuration.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/Configuration.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/Configuration.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,227 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/Configuration.java,v 1.17 2006/06/16 16:31:28 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2001, 2006). 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: 1.17 $
+ */
+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 intiates 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 intiates 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 initate 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();
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,256 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationAdmin.java,v 1.16 2006/07/11 00:54:03 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2001, 2006). 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 PID matches
+ * the PID registration 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>factoryPid</code> matches the PID 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 Confguration 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: 1.16 $
+ */
+public interface ConfigurationAdmin {
+	/**
+	 * Service 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";
+	/**
+	 * Service 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 <code>Filter</code>
+	 * class. The filter can test any configuration parameters including the
+	 * following system properties:
+	 * <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 <code>Filter</code> object, 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;
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationEvent.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,167 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationEvent.java,v 1.9 2006/06/16 16:31:28 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2004, 2006). 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 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: 1.9 $
+ * @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 <code>Configuration.update</code>
+	 * 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 <code>Configuration.delete</code>
+	 * 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;
+	}
+
+	/**
+	 * 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;
+	}
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationException.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,112 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationException.java,v 1.13 2006/07/11 13:15:52 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2001, 2006). 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: 1.13 $
+ */
+public class ConfigurationException extends Exception {
+	static final long	serialVersionUID	= -1690090413441769377L;
+
+	private final String		property;
+	private final String		reason;
+
+	/**
+	 * Nested exception.
+	 */
+	private final Throwable	cause;
+
+	/**
+	 * 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;
+		this.cause = null;
+	}
+
+	/**
+	 * 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);
+		this.property = property;
+		this.reason = reason;
+		this.cause = cause;
+	}
+
+	/**
+	 * 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 specified when this exception was created.
+	 * 
+	 * @return The cause of this exception or <code>null</code> if no cause
+	 *         was specified.
+	 * @since 1.2
+	 */
+	public Throwable getCause() {
+		return cause;
+	}
+
+	/**
+	 * The cause of this exception can only be set when constructed.
+	 * 
+	 * @param cause Cause of the exception.
+	 * @return This object.
+	 * @throws java.lang.IllegalStateException This method will always throw an
+	 *         <code>IllegalStateException</code> since the cause of this
+	 *         exception can only be set when constructed.
+	 * @since 1.2
+	 */
+	public Throwable initCause(Throwable cause) {
+		throw new IllegalStateException();
+	}
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationListener.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,50 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationListener.java,v 1.10 2006/06/16 16:31:28 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2004, 2006). 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: 1.10 $
+ * @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);
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationPermission.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,218 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationPermission.java,v 1.22 2006/07/08 00:42:00 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2004, 2006). 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.*;
+import java.util.Enumeration;
+import java.util.NoSuchElementException;
+
+/**
+ * Indicates a bundle's authority to configure bundles.
+ * 
+ * This permission has only a single action: CONFIGURE.
+ * 
+ * @version $Revision: 1.22 $
+ * @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() {
+		return getName().hashCode() ^ getActions().hashCode();
+	}
+
+	/**
+	 * 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 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();
+				}
+			}
+		};
+	}
+
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ConfigurationPlugin.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,131 @@
+/*
+ * $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 $
+ *
+ * Copyright (c) OSGi Alliance (2001, 2006). 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 ManagedS ervice 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 targetted
+ * 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: 1.11 $
+ */
+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);
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ManagedService.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ManagedService.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ManagedService.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ManagedService.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,140 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ManagedService.java,v 1.12 2006/06/16 16:31:28 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2001, 2006). 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 identitifier 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: 1.12 $
+ */
+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;
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/ManagedServiceFactory.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,162 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ManagedServiceFactory.java,v 1.12 2006/07/11 00:54:03 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2001, 2006). 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: 1.12 $
+ */
+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);
+}

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/package.html
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/package.html?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/package.html (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/package.html Wed Jan 30 08:46:24 2008
@@ -0,0 +1 @@
+<!-- $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/package.html,v 1.3 2006/07/12 21:07:02 hargrave Exp $ -->
<BODY>
<p>Configuration Admin Package Version 1.2.
<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=1.2
</pre>
</BODY>
\ No newline at end of file

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/packageinfo
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/packageinfo?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/packageinfo (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/cm/packageinfo Wed Jan 30 08:46:24 2008
@@ -0,0 +1 @@
+version 1.2

Added: felix/trunk/deploymentadmin/src/main/java/org/osgi/service/component/ComponentConstants.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/src/main/java/org/osgi/service/component/ComponentConstants.java?rev=616813&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/src/main/java/org/osgi/service/component/ComponentConstants.java (added)
+++ felix/trunk/deploymentadmin/src/main/java/org/osgi/service/component/ComponentConstants.java Wed Jan 30 08:46:24 2008
@@ -0,0 +1,71 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.component/src/org/osgi/service/component/ComponentConstants.java,v 1.14 2006/06/16 16:31:26 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2004, 2006). 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.component;
+
+/**
+ * Defines standard names for Service Component constants.
+ * 
+ * @version $Revision: 1.14 $
+ */
+public interface ComponentConstants {
+	/**
+	 * Manifest header (named &quot;Service-Component&quot;) specifying the XML
+	 * documents within a bundle that contain the bundle's Service Component
+	 * descriptions.
+	 * <p>
+	 * The attribute value may be retrieved from the <code>Dictionary</code>
+	 * object returned by the <code>Bundle.getHeaders</code> method.
+	 */
+	public static final String	SERVICE_COMPONENT		= "Service-Component";
+
+	/**
+	 * A component property for a component configuration that contains the name
+	 * of the component as specified in the <code>name</code> attribute of the
+	 * <code>component</code> element. The type of this property must be
+	 * <code>String</code>.
+	 */
+	public final static String	COMPONENT_NAME			= "component.name";
+
+	/**
+	 * A component property that contains the generated id for a component
+	 * configuration. The type of this property must be <code>Long</code>.
+	 * 
+	 * <p>
+	 * The value of this property is assigned by the Service Component Runtime
+	 * when a component configuration is created. The Service Component Runtime
+	 * assigns a unique value that is larger than all previously assigned values
+	 * since the Service Component Runtime was started. These values are NOT
+	 * persistent across restarts of the Service Component Runtime.
+	 */
+	public final static String	COMPONENT_ID			= "component.id";
+
+	/**
+	 * A service registration property for a Component Factory that contains the
+	 * value of the <code>factory</code> attribute. The type of this property
+	 * must be <code>String</code>.
+	 */
+	public final static String	COMPONENT_FACTORY		= "component.factory";
+
+	/**
+	 * The suffix for reference target properties. These properties contain the
+	 * filter to select the target services for a reference. The type of this
+	 * property must be <code>String</code>.
+	 */
+	public final static String	REFERENCE_TARGET_SUFFIX	= ".target";
+}



Mime
View raw message