FELIX-514 Updated compendium bundle to R4.1 OSGi API
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@681945 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/org.osgi.compendium/src/main/java/org/osgi/application/ApplicationContext.java b/org.osgi.compendium/src/main/java/org/osgi/application/ApplicationContext.java
new file mode 100644
index 0000000..c04fcf8
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/application/ApplicationContext.java
@@ -0,0 +1,355 @@
+/*
+ * $Header: /cvshome/build/org.osgi.application/src/org/osgi/application/ApplicationContext.java,v 1.15 2006/07/11 13:19:02 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.application;
+
+import java.util.Dictionary;
+import java.util.Map;
+
+import org.osgi.framework.Constants;
+import org.osgi.framework.ServiceRegistration;
+
+
+/**
+ * <code>ApplicationContext</code> is the access point for an OSGi-aware
+ * application to the features of the OSGi Service Platform. Each application
+ * instance will have its own <code>ApplicationContext</code> instance, which
+ * will not be reused after destorying the corresponding application instace.
+ * <p>
+ * Application instances can obtain their <code>ApplicationContext</code>
+ * using the {@link Framework#getApplicationContext} method.
+ * <p>
+ * The lifecycle of an <code>ApplicationContext</code> instance is bound to
+ * the lifecycle of the corresponding application instance. The
+ * <code>ApplicationContext</code> becomes available when the application is
+ * started and it is invalidated when the application instance is stopped (i.e.
+ * the "stop" method of the application activator object returned).
+ * All method calls (except {@link #getApplicationId()} and
+ * {@link #getInstanceId()}) to an invalidated context object result an
+ * <code>IllegalStateException</code>.
+ *
+ * @see org.osgi.application.Framework
+ */
+public interface ApplicationContext {
+
+ /**
+ * Adds the specified {@link ApplicationServiceListener} object to this context
+ * application instance's list of listeners. The specified <code>referenceName</code> is a
+ * reference name specified in the descriptor of the corresponding application. The registered
+ * <code>listener> will only receive the {@link ApplicationServiceEvent}s realted to the referred service.
+ * <p>
+ * If the <code>listener</code> was already added, calling this method will overwrite the previous
+ * registration.
+ * <p>
+ *
+ * @param listener
+ * The {@link org.osgi.application.ApplicationServiceListener} to be added. It must
+ * not be <code>null</code>
+ * @param referenceName the reference name of a service from the descriptor of the corresponding
+ * application. It must not be <code>null</code>.
+ * @throws java.lang.IllegalStateException
+ * If this context application instance has stopped.
+ * @throws java.lang.NullPointerException If <code>listener</code> or <code>referenceName</code>
+ * is <code>null</code>
+ * @throws java.lang.IllegalArgumentException If there is no service in the
+ * application descriptor with the specified <code>referenceName</code>.
+ */
+ public void addServiceListener(ApplicationServiceListener listener, String referenceName) throws java.lang.IllegalArgumentException;
+
+ /**
+ * Adds the specified {@link ApplicationServiceListener} object to this context
+ * application instance's list of listeners. The <code>referenceNames</code> parameter is an
+ * array of reference name specified in the descriptor of the corresponding application. The registered
+ * <code>listener> will only receive the {@link ApplicationServiceEvent}s realted to the referred
+ * services.
+ * <p>
+ * If the <code>listener</code> was already added, calling this method will overwrite the previous
+ * registration.
+ * <p>
+ *
+ * @param listener
+ * The {@link org.osgi.application.ApplicationServiceListener} to be added. It must not
+ * be <code>null</code>
+ * @param referenceNames and array of service reference names from the descriptor of the corresponding
+ * application. It must not be <code>null</code> and it must not be empty.
+ * @throws java.lang.IllegalStateException
+ * If this context application instance has stopped.
+ * @throws java.lang.NullPointerException If <code>listener</code> or <code>referenceNames</code>
+ * is <code>null</code>
+ * @throws java.lang.IllegalArgumentException If <code>referenceNames</code> array is empty or it
+ * contains unknown references
+ */
+ public void addServiceListener(ApplicationServiceListener listener, String[] referenceNames) throws java.lang.IllegalArgumentException;
+
+ /**
+ * Removes the specified {@link org.osgi.application.ApplicationServiceListener} object from this
+ * context application instances's list of listeners.
+ * <p>
+ * If <code>listener</code> is not contained in this context application
+ * instance's list of listeners, this method does nothing.
+ *
+ * @param listener
+ * The {@link org.osgi.application.ApplicationServiceListener} object to be removed.
+ * @throws java.lang.IllegalStateException
+ * If this context application instance has stopped.
+ */
+ public void removeServiceListener(ApplicationServiceListener listener);
+
+ /**
+ * This method returns the identifier of the corresponding application instace.
+ * This identifier is guarateed to be unique within the scope of the device.
+ *
+ * Note: this method can safely be called on an invalid
+ * <code>ApplicationContext</code> as well.
+ *
+ * @see org.osgi.service.application.ApplicationHandle#getInstanceId()
+ *
+ * @return the unique identifier of the corresponding application instance
+ */
+ public String getInstanceId();
+
+ /**
+ * This method return the identifier of the correspondig application type. This identifier
+ * is the same for the different instances of the same application but it is different for
+ * different application type.
+ * <p>
+ * Note: this method can safely be called on an invalid
+ * <code>ApplicationContext</code> as well.
+ *
+ * @see org.osgi.service.application.ApplicationDescriptor#getApplicationId()
+ *
+ * @return the identifier of the application type.
+ */
+ public String getApplicationId();
+
+ /**
+ * This method returns the service object for the specified
+ * <code>referenceName</code>. If the cardinality of the reference is
+ * 0..n or 1..n and multiple services are bound to the reference, the
+ * service with the highest ranking (as specified in its
+ * {@link org.osgi.framework.Constants#SERVICE_RANKING} property) is returned. If there
+ * is a tie in ranking, the service with the lowest service ID (as specified
+ * in its {@link org.osgi.framework.Constants#SERVICE_ID} property); that is, the
+ * service that was registered first is returned.
+ *
+ * @param referenceName
+ * The name of a reference as specified in a reference element in
+ * this context applications's description. It must not be <code>null</code>
+ * @return A service object for the referenced service or <code>null</code>
+ * if the reference cardinality is 0..1 or 0..n and no bound service
+ * is available.
+ * @throws java.lang.NullPointerException If <code>referenceName</code> is <code>null</code>.
+ * @throws java.lang.IllegalArgumentException If there is no service in the
+ * application descriptor with the specified <code>referenceName</code>.
+ * @throws java.lang.IllegalStateException
+ * If this context application instance has stopped.
+ */
+ public Object locateService(String referenceName);
+
+ /**
+ * This method returns the service objects for the specified
+ * <code>referenceName</code>.
+ *
+ * @param referenceName
+ * The name of a reference as specified in a reference element in
+ * this context applications's description. It must not be
+ * <code>null</code>.
+ * @return An array of service object for the referenced service or
+ * <code>null</code> if the reference cardinality is 0..1 or 0..n
+ * and no bound service is available.
+ * @throws java.lang.NullPointerException If <code>referenceName</code> is <code>null</code>.
+ * @throws java.lang.IllegalArgumentException If there is no service in the
+ * application descriptor with the specified <code>referenceName</code>.
+ * @throws java.lang.IllegalStateException
+ * If this context application instance has stopped.
+ */
+ public Object[] locateServices(String referenceName);
+
+ /**
+ * Returns the startup parameters specified when calling the
+ * {@link org.osgi.service.application.ApplicationDescriptor#launch}
+ * method.
+ * <p>
+ * Startup arguments can be specified as name, value pairs. The name
+ * must be of type {@link java.lang.String}, which must not be
+ * <code>null</code> or empty {@link java.lang.String} (<code>""</code>),
+ * the value can be any object including <code>null</code>.
+ *
+ * @return a {@link java.util.Map} containing the startup arguments.
+ * It can be <code>null</code>.
+ * @throws java.lang.IllegalStateException
+ * If this context application instance has stopped.
+ */
+ public Map getStartupParameters();
+
+ /**
+ * Application can query the service properties of a service object
+ * it is bound to. Application gets bound to a service object when
+ * it fisrt obtains a reference to the service by calling
+ * <code>locateService</code> or <code>locateServices</code> methods.
+ *
+ * @param serviceObject A service object the application is bound to.
+ * It must not be null.
+ * @return The service properties associated with the specified service
+ * object.
+ * @throws NullPointerException if the specified <code>serviceObject</code>
+ * is <code>null</code>
+ * @throws IllegalArgumentException if the application is not
+ * bound to the specified service object or it is not a service
+ * object at all.
+ * @throws java.lang.IllegalStateException
+ * If this context application instance has stopped.
+ */
+ public Map getServiceProperties(Object serviceObject);
+
+
+ /**
+ * Registers the specified service object with the specified properties
+ * under the specified class names into the Framework. A
+ * {@link org.osgi.framework.ServiceRegistration} object is returned. The
+ * {@link org.osgi.framework.ServiceRegistration} object is for the private use of the
+ * application registering the service and should not be shared with other
+ * applications. The registering application is defined to be the context application.
+ * Bundles can locate the service by using either the
+ * {@link org.osgi.framework.BundleContext#getServiceReferences} or
+ * {@link org.osgi.framework.BundleContext#getServiceReference} method. Other applications
+ * can locate this service by using {@link #locateService(String)} or {@link #locateServices(String)}
+ * method, if they declared their dependece on the registered service.
+ *
+ * <p>
+ * An application can register a service object that implements the
+ * {@link org.osgi.framework.ServiceFactory} interface to have more flexibility in providing
+ * service objects to other applications or bundles.
+ *
+ * <p>
+ * The following steps are required to register a service:
+ * <ol>
+ * <li>If <code>service</code> is not a <code>ServiceFactory</code>,
+ * an <code>IllegalArgumentException</code> is thrown if
+ * <code>service</code> is not an <code>instanceof</code> all the
+ * classes named.
+ * <li>The Framework adds these service properties to the specified
+ * <code>Dictionary</code> (which may be <code>null</code>): a property
+ * named {@link org.osgi.framework.Constants#SERVICE_ID} identifying the registration number of
+ * the service and a property named {@link org.osgi.framework.Constants#OBJECTCLASS} containing
+ * all the specified classes. If any of these properties have already been
+ * specified by the registering bundle, their values will be overwritten by
+ * the Framework.
+ * <li>The service is added to the Framework service registry and may now
+ * be used by others.
+ * <li>A service event of type {@link org.osgi.framework.ServiceEvent#REGISTERED} is
+ * fired. This event triggers the corresponding {@link ApplicationServiceEvent} to be
+ * delivered to the applications that registered the appropriate listener.
+ * <li>A <code>ServiceRegistration</code> object for this registration is
+ * returned.
+ * </ol>
+ *
+ * @param clazzes The class names under which the service can be located.
+ * The class names in this array will be stored in the service's
+ * properties under the key {@link org.osgi.framework.Constants#OBJECTCLASS}.
+ * This parameter must not be <code>null</code>.
+ * @param service The service object or a <code>ServiceFactory</code>
+ * object.
+ * @param properties The properties for this service. The keys in the
+ * properties object must all be <code>String</code> objects. See
+ * {@link org.osgi.framework.Constants} for a list of standard service property keys.
+ * Changes should not be made to this object after calling this
+ * method. To update the service's properties the
+ * {@link org.osgi.framework.ServiceRegistration#setProperties} method must be called.
+ * The set of properties may be <code>null</code> if the service
+ * has no properties.
+ *
+ * @return A {@link org.osgi.framework.ServiceRegistration} object for use by the application
+ * registering the service to update the service's properties or to
+ * unregister the service.
+ *
+ * @throws java.lang.IllegalArgumentException If one of the following is
+ * true:
+ * <ul>
+ * <li><code>service</code> is <code>null</code>.
+ * <li><code>service</code> is not a <code>ServiceFactory</code>
+ * object and is not an instance of all the named classes in
+ * <code>clazzes</code>.
+ * <li><code>properties</code> contains case variants of the same
+ * key name.
+ * </ul>
+ * @throws NullPointerException if <code>clazzes</code> is <code>null</code>
+ *
+ * @throws java.lang.SecurityException If the caller does not have the
+ * <code>ServicePermission</code> to register the service for all
+ * the named classes and the Java Runtime Environment supports
+ * permissions.
+ *
+ * @throws java.lang.IllegalStateException If this ApplicationContext is no
+ * longer valid.
+ *
+ * @see org.osgi.framework.BundleContext#registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)
+ * @see org.osgi.framework.ServiceRegistration
+ * @see org.osgi.framework.ServiceFactory
+ */
+ public ServiceRegistration registerService(String[] clazzes,
+ Object service, Dictionary properties);
+
+ /**
+ * Registers the specified service object with the specified properties
+ * under the specified class name with the Framework.
+ *
+ * <p>
+ * This method is otherwise identical to
+ * {@link #registerService(java.lang.String[], java.lang.Object,
+ * java.util.Dictionary)} and is provided as a convenience when
+ * <code>service</code> will only be registered under a single class name.
+ * Note that even in this case the value of the service's
+ * {@link Constants#OBJECTCLASS} property will be an array of strings,
+ * rather than just a single string.
+ *
+ * @param clazz The class name under which the service can be located. It
+ * must not be <code>null</code>
+ * @param service The service object or a <code>ServiceFactory</code>
+ * object.
+ * @param properties The properties for this service.
+ *
+ * @return A <code>ServiceRegistration</code> object for use by the application
+ * registering the service to update the service's properties or to
+ * unregister the service.
+ *
+ * @throws java.lang.IllegalArgumentException If one of the following is
+ * true:
+ * <ul>
+ * <li><code>service</code> is <code>null</code>.
+ * <li><code>service</code> is not a <code>ServiceFactory</code>
+ * object and is not an instance of the named class in
+ * <code>clazz</code>.
+ * <li><code>properties</code> contains case variants of the same
+ * key name.
+ * </ul>
+ * @throws NullPointerException if <code>clazz</code> is <code>null</code>
+ *
+ * @throws java.lang.SecurityException If the caller does not have the
+ * <code>ServicePermission</code> to register the service
+ * the named class and the Java Runtime Environment supports
+ * permissions.
+ *
+ * @throws java.lang.IllegalStateException If this ApplicationContext is no
+ * longer valid.
+ * @see #registerService(java.lang.String[], java.lang.Object,
+ * java.util.Dictionary)
+ */
+ public ServiceRegistration registerService(String clazz, Object service,
+ Dictionary properties);
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/application/ApplicationServiceEvent.java b/org.osgi.compendium/src/main/java/org/osgi/application/ApplicationServiceEvent.java
new file mode 100644
index 0000000..cfb4cec
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/application/ApplicationServiceEvent.java
@@ -0,0 +1,83 @@
+/*
+ * $Header: /cvshome/build/org.osgi.application/src/org/osgi/application/ApplicationServiceEvent.java,v 1.6 2006/07/11 13:19:02 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.application;
+
+import org.osgi.framework.ServiceEvent;
+import org.osgi.framework.ServiceReference;
+
+/**
+ * An event from the Framework describing a service lifecycle change.
+ * <p>
+ * <code>ApplicationServiceEvent</code> objects are delivered to a
+ * <code>ApplicationServiceListener</code> objects when a change occurs in this service's
+ * lifecycle. The delivery of an <code>ApplicationServiceEvent</code> is
+ * always triggered by a {@link org.osgi.framework.ServiceEvent}.
+ * <code>ApplicationServiceEvent</code> extends the content of <code>ServiceEvent</code>
+ * with the service object the event is referring to as applications has no means to
+ * find the corresponding service object for a {@link org.osgi.framework.ServiceReference}.
+ * A type code is used to identify the event type for future
+ * extendability. The available type codes are defined in {@link org.osgi.framework.ServiceEvent}.
+ *
+ * <p>
+ * OSGi Alliance reserves the right to extend the set of types.
+ *
+ * @see org.osgi.framework.ServiceEvent
+ * @see ApplicationServiceListener
+ *
+ * @version $Revision: 1.6 $
+ */
+public class ApplicationServiceEvent extends ServiceEvent {
+
+ private static final long serialVersionUID = -4762149286971897323L;
+ final Object serviceObject;
+
+ /**
+ * Creates a new application service event object.
+ *
+ * @param type The event type. Available type codes are defines in
+ * {@link org.osgi.framework.ServiceEvent}
+ * @param reference A <code>ServiceReference</code> object to the service
+ * that had a lifecycle change. This reference will be used as the <code>source</code>
+ * in the {@link java.util.EventObject} baseclass, therefore, it must not be
+ * null.
+ * @param serviceObject The service object bound to this application instance. It can
+ * be <code>null</code> if this application is not bound to this service yet.
+ * @throws IllegalArgumentException if the specified <code>reference</code> is null.
+ */
+ public ApplicationServiceEvent(int type, ServiceReference reference, Object serviceObject) {
+ super(type, reference);
+ this.serviceObject = serviceObject;
+ }
+
+ /**
+ * This method returns the service object of this service bound to the listener
+ * application instace. A service object becomes bound to the application when it
+ * first obtains a service object reference to that service by calling the
+ * <code>ApplicationContext.locateService</code> or <code>locateServices</code>
+ * methods. If the application is not bound to the service yet, this method returns
+ * <code>null</code>.
+ *
+ * @return the service object bound to the listener application or <code>null</code>
+ * if it isn't bound to this service yet.
+ */
+ public Object getServiceObject() {
+ return this.serviceObject;
+ }
+
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/application/ApplicationServiceListener.java b/org.osgi.compendium/src/main/java/org/osgi/application/ApplicationServiceListener.java
new file mode 100644
index 0000000..1a7d36f
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/application/ApplicationServiceListener.java
@@ -0,0 +1,68 @@
+/*
+ * $Header: /cvshome/build/org.osgi.application/src/org/osgi/application/ApplicationServiceListener.java,v 1.6 2006/07/12 21:21:34 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.application;
+
+import java.util.EventListener;
+
+import org.osgi.framework.*;
+
+/**
+ * An <code>ApplicationServiceEvent</code> listener. When a
+ * <code>ServiceEvent</code> is
+ * fired, it is converted to an <code>ApplictionServiceEvent</code>
+ * and it is synchronously delivered to an <code>ApplicationServiceListener</code>.
+ *
+ * <p>
+ * <code>ApplicationServiceListener</code> is a listener interface that may be
+ * implemented by an application developer.
+ * <p>
+ * An <code>ApplicationServiceListener</code> object is registered with the Framework
+ * using the <code>ApplicationContext.addServiceListener</code> method.
+ * <code>ApplicationServiceListener</code> objects are called with an
+ * <code>ApplicationServiceEvent</code> object when a service is registered, modified, or
+ * is in the process of unregistering.
+ *
+ * <p>
+ * <code>ApplicationServiceEvent</code> object delivery to
+ * <code>ApplicationServiceListener</code>
+ * objects is filtered by the filter specified when the listener was registered.
+ * If the Java Runtime Environment supports permissions, then additional
+ * filtering is done. <code>ApplicationServiceEvent</code> objects are only delivered to
+ * the listener if the application which defines the listener object's class has the
+ * appropriate <code>ServicePermission</code> to get the service using at
+ * least one of the named classes the service was registered under, and the application
+ * specified its dependece on the corresponding service in the application metadata.
+ *
+ * <p>
+ * <code>ApplicationServiceEvent</code> object delivery to <code>ApplicationServiceListener</code>
+ * objects is further filtered according to package sources as defined in
+ * {@link ServiceReference#isAssignableTo(Bundle, String)}.
+ *
+ * @version $Revision: 1.6 $
+ * @see ApplicationServiceEvent
+ * @see ServicePermission
+ */
+public interface ApplicationServiceListener extends EventListener {
+ /**
+ * Receives notification that a service has had a lifecycle change.
+ *
+ * @param event The <code>ApplicationServiceEvent</code> object.
+ */
+ public void serviceChanged(ApplicationServiceEvent event);
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/application/Framework.java b/org.osgi.compendium/src/main/java/org/osgi/application/Framework.java
new file mode 100644
index 0000000..4696115
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/application/Framework.java
@@ -0,0 +1,59 @@
+/*
+ * $Header: /cvshome/build/org.osgi.application/src/org/osgi/application/Framework.java,v 1.9 2006/07/11 13:19:02 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.application;
+
+import java.util.Hashtable;
+
+/**
+ * Using this class, OSGi-aware applications can obtain their {@link ApplicationContext}.
+ *
+ */
+public final class Framework {
+
+ private Framework() { }
+
+ private static Hashtable appContextHash;
+
+ /**
+ * This method needs an argument, an object that represents the application instance.
+ * An application consists of a set of object, however there is a single object, which
+ * is used by the corresponding application container to manage the lifecycle on the
+ * application instance. The lifetime of this object equals the lifetime of
+ * the application instance; therefore, it is suitable to represent the instance.
+ * <P>
+ * The returned {@link ApplicationContext} object is singleton for the
+ * specified application instance. Subsequent calls to this method with the same
+ * application instance must return the same context object
+ *
+ * @param applicationInstance is the activator object of an application instance
+ * @throws java.lang.NullPointerException If <code>applicationInstance</code>
+ * is <code>null</code>
+ * @throws java.lang.IllegalArgumentException if called with an object that is not
+ * the activator object of an application.
+ * @return the {@link ApplicationContext} of the specified application instance.
+ */
+ public static ApplicationContext getApplicationContext(Object applicationInstance) {
+ if( applicationInstance == null )
+ throw new NullPointerException( "Instance cannot be null!" );
+ ApplicationContext appContext = (ApplicationContext)appContextHash.get( applicationInstance );
+ if( appContext == null )
+ throw new IllegalArgumentException( "ApplicationContext not found!" );
+ return appContext;
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationAdminPermission.java b/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationAdminPermission.java
new file mode 100644
index 0000000..5615148
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationAdminPermission.java
@@ -0,0 +1,407 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.application/src/org/osgi/service/application/ApplicationAdminPermission.java,v 1.34 2006/07/12 21:22:11 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.security.Permission;
+import java.util.*;
+
+import org.osgi.framework.*;
+
+/**
+ * This class implements permissions for manipulating applications and
+ * their instances.
+ * <P>
+ * ApplicationAdminPermission can be targeted to applications that matches the
+ * specified filter.
+ * <P>
+ * ApplicationAdminPermission may be granted for different actions:
+ * <code>lifecycle</code>, <code>schedule</code> and <code>lock</code>.
+ * The permission <code>schedule</code> implies the permission
+ * <code>lifecycle</code>.
+ */
+public class ApplicationAdminPermission extends Permission {
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Allows the lifecycle management of the target applications.
+ */
+ public static final String LIFECYCLE_ACTION = "lifecycle";
+
+ /**
+ * Allows scheduling of the target applications. The permission to
+ * schedule an application implies that the scheduler can also
+ * manage the lifecycle of that application i.e. <code>schedule</code>
+ * implies <code>lifecycle</code>
+ */
+ public static final String SCHEDULE_ACTION = "schedule";
+
+ /**
+ * Allows setting/unsetting the locking state of the target applications.
+ */
+ public static final String LOCK_ACTION = "lock";
+
+ private ApplicationDescriptor applicationDescriptor;
+
+ /**
+ * Constructs an ApplicationAdminPermission. The <code>filter</code>
+ * specifies the target application. The <code>filter</code> is an
+ * LDAP-style filter, the recognized properties are <code>signer</code>
+ * and <code>pid</code>. The pattern specified in the <code>signer</code>
+ * is matched with the Distinguished Name chain used to sign the application.
+ * Wildcards in a DN are not matched according to the filter string rules,
+ * but according to the rules defined for a DN chain. The attribute
+ * <code>pid</code> is matched with the PID of the application according to
+ * the filter string rules.
+ * <p>
+ * If the <code>filter</code> is <code>null</code> then it matches
+ * <code>"*"</code>. If
+ * <code>actions</code> is <code>"*"</code> then it identifies all the
+ * possible actions.
+ *
+ * @param filter
+ * filter to identify application. The value <code>null</code>
+ * is equivalent to <code>"*"</code> and it indicates "all application".
+ * @param actions
+ * comma-separated list of the desired actions granted on the
+ * applications or "*" means all the actions. It must not be
+ * <code>null</code>. The order of the actions in the list is
+ * not significant.
+ * @throws InvalidSyntaxException
+ * is thrown if the specified <code>filter</code> is not syntactically
+ * correct.
+ *
+ * @exception NullPointerException
+ * is thrown if the actions parameter is <code>null</code>
+ *
+ * @see ApplicationDescriptor
+ * @see org.osgi.framework.AdminPermission
+ */
+ public ApplicationAdminPermission(String filter, String actions) throws InvalidSyntaxException {
+ super(filter == null ? "*" : filter);
+
+ if( filter == null )
+ filter = "*";
+
+ if( actions == null )
+ throw new NullPointerException( "Action string cannot be null!" );
+
+ this.applicationDescriptor = null;
+ this.filter = (filter == null ? "*" : filter);
+ this.actions = actions;
+
+ if( !filter.equals( "*" ) && !filter.equals( "<<SELF>>" ) )
+ FrameworkUtil.createFilter( this.filter ); // check if the filter is valid
+ init();
+ }
+
+ /**
+ * This contructor should be used when creating <code>ApplicationAdminPermission</code>
+ * instance for <code>checkPermission</code> call.
+ * @param application the tareget of the operation, it must not be <code>null</code>
+ * @param actions the required operation. it must not be <code>null</code>
+ * @throws NullPointerException if any of the arguments is null.
+ */
+ public ApplicationAdminPermission(ApplicationDescriptor application, String actions) {
+ super(application.getApplicationId());
+
+ if( application == null || actions == null )
+ throw new NullPointerException( "ApplicationDescriptor and action string cannot be null!" );
+
+ this.filter = application.getApplicationId();
+ this.applicationDescriptor = application;
+ this.actions = actions;
+
+ init();
+ }
+
+ /**
+ * This method can be used in the {@link java.security.ProtectionDomain}
+ * implementation in the <code>implies</code> method to insert the
+ * application ID of the current application into the permission being
+ * checked. This enables the evaluation of the
+ * <code><<SELF>></code> pseudo targets.
+ * @param applicationId the ID of the current application.
+ * @return the permission updated with the ID of the current application
+ */
+ public ApplicationAdminPermission setCurrentApplicationId(String applicationId) {
+ ApplicationAdminPermission newPerm = null;
+
+ if( this.applicationDescriptor == null ) {
+ try {
+ newPerm = new ApplicationAdminPermission( this.filter, this.actions );
+ }catch( InvalidSyntaxException e ) {
+ throw new RuntimeException( "Internal error" ); /* this can never happen */
+ }
+ }
+ else
+ newPerm = new ApplicationAdminPermission( this.applicationDescriptor, this.actions );
+
+ newPerm.applicationID = applicationId;
+
+ return newPerm;
+ }
+
+ /**
+ * Checks if the specified <code>permission</code> is implied by this permission.
+ * The method returns true under the following conditions:
+ * <UL>
+ * <LI> This permission was created by specifying a filter (see {@link #ApplicationAdminPermission(String, String)})
+ * <LI> The implied <code>otherPermission</code> was created for a particular {@link ApplicationDescriptor}
+ * (see {@link #ApplicationAdminPermission(ApplicationDescriptor, String)})
+ * <LI> The <code>filter</code> of this permission mathes the <code>ApplicationDescriptor</code> specified
+ * in the <code>otherPermission</code>. If the filter in this permission is the
+ * <code><<SELF>></code> pseudo target, then the currentApplicationId set in the
+ * <code>otherPermission</code> is compared to the application Id of the target
+ * <code>ApplicationDescriptor</code>.
+ * <LI> The list of permitted actions in this permission contains all actions required in the
+ * <code>otherPermission</code>
+ * </UL>
+ * Otherwise the method returns false.
+ * @param otherPermission the implied permission
+ * @return true if this permission implies the <code>otherPermission</code>, false otherwise.
+ */
+ public boolean implies(Permission otherPermission) {
+ if( otherPermission == null )
+ return false;
+
+ if(!(otherPermission instanceof ApplicationAdminPermission))
+ return false;
+
+ ApplicationAdminPermission other = (ApplicationAdminPermission) otherPermission;
+
+ if( !filter.equals("*") ) {
+ if( other.applicationDescriptor == null )
+ return false;
+
+ if( filter.equals( "<<SELF>>") ) {
+ if( other.applicationID == null )
+ return false; /* it cannot be, this might be a bug */
+
+ if( !other.applicationID.equals( other.applicationDescriptor.getApplicationId() ) )
+ return false;
+ }
+ else {
+ Hashtable props = new Hashtable();
+ props.put( "pid", other.applicationDescriptor.getApplicationId() );
+ props.put( "signer", new SignerWrapper( other.applicationDescriptor ) );
+
+ Filter flt = getFilter();
+ if( flt == null )
+ return false;
+
+ if( !flt.match( props ) )
+ return false;
+ }
+ }
+
+ if( !actionsVector.containsAll( other.actionsVector ) )
+ return false;
+
+ return true;
+ }
+
+ public boolean equals(Object with) {
+ if( with == null || !(with instanceof ApplicationAdminPermission) )
+ return false;
+
+ ApplicationAdminPermission other = (ApplicationAdminPermission)with;
+
+ // Compare actions:
+ if( other.actionsVector.size() != actionsVector.size() )
+ return false;
+
+ for( int i=0; i != actionsVector.size(); i++ )
+ if( !other.actionsVector.contains( actionsVector.get( i ) ) )
+ return false;
+
+
+ return equal(this.filter, other.filter ) && equal(this.applicationDescriptor, other.applicationDescriptor)
+ && equal(this.applicationID, other.applicationID);
+ }
+
+ /**
+ * Compares parameters for equality. If both object are null, they are considered
+ * equal.
+ * @param a object to compare
+ * @param b other object to compare
+ * @return true if both objects are equal or both are null
+ */
+ private static boolean equal(Object a, Object b) {
+ // This equation is true if both references are null or both point
+ // to the same object. In both cases they are considered as equal.
+ if( a == b ) {
+ return true;
+ }
+
+ return a.equals(b);
+ }
+
+ public int hashCode() {
+ int hc = 0;
+ for( int i=0; i != actionsVector.size(); i++ )
+ hc ^= ((String)actionsVector.get( i )).hashCode();
+ hc ^= (null == this.filter )? 0 : this.filter.hashCode();
+ hc ^= (null == this.applicationDescriptor) ? 0 : this.applicationDescriptor.hashCode();
+ hc ^= (null == this.applicationID) ? 0 : this.applicationID.hashCode();
+ return hc;
+ }
+
+ /**
+ * Returns the actions of this permission.
+ * @return the actions specified when this permission was created
+ */
+ public String getActions() {
+ return actions;
+ }
+
+ private String applicationID;
+
+ private static final Vector ACTIONS = new Vector();
+ private Vector actionsVector;
+ private final String filter;
+ private final String actions;
+ private Filter appliedFilter = null;
+
+ static {
+ ACTIONS.add(LIFECYCLE_ACTION);
+ ACTIONS.add(SCHEDULE_ACTION);
+ ACTIONS.add(LOCK_ACTION);
+ }
+
+ private static Vector actionsVector(String actions) {
+ Vector v = new Vector();
+ StringTokenizer t = new StringTokenizer(actions.toUpperCase(), ",");
+ while (t.hasMoreTokens()) {
+ String action = t.nextToken().trim();
+ v.add(action.toLowerCase());
+ }
+
+ if( v.contains( SCHEDULE_ACTION ) && !v.contains( LIFECYCLE_ACTION ) )
+ v.add( LIFECYCLE_ACTION );
+
+ return v;
+ }
+
+
+ private static class SignerWrapper extends Object {
+ private String pattern;
+ private ApplicationDescriptor appDesc;
+
+ public SignerWrapper(String pattern) {
+ this.pattern = pattern;
+ }
+
+ SignerWrapper(ApplicationDescriptor appDesc) {
+ this.appDesc = appDesc;
+ }
+
+ public boolean equals(Object o) {
+ if (!(o instanceof SignerWrapper))
+ return false;
+ SignerWrapper other = (SignerWrapper) o;
+ ApplicationDescriptor matchAppDesc = (ApplicationDescriptor) (appDesc != null ? appDesc : other.appDesc);
+ String matchPattern = appDesc != null ? other.pattern : pattern;
+ return matchAppDesc.matchDNChain(matchPattern);
+ }
+ }
+
+ private void init() {
+ actionsVector = actionsVector( actions );
+
+ if ( actions.equals("*") )
+ actionsVector = actionsVector( LIFECYCLE_ACTION + "," + SCHEDULE_ACTION + "," + LOCK_ACTION );
+ else if (!ACTIONS.containsAll(actionsVector))
+ throw new IllegalArgumentException("Illegal action!");
+
+ applicationID = null;
+ }
+
+ private Filter getFilter() {
+ String transformedFilter = filter;
+
+ if (appliedFilter == null) {
+ try {
+ int pos = filter.indexOf("signer"); //$NON-NLS-1$
+ if (pos != -1){
+
+ //there may be a signer attribute
+ StringBuffer filterBuf = new StringBuffer(filter);
+ int numAsteriskFound = 0; //use as offset to replace in buffer
+
+ int walkbackPos; //temp pos
+
+ //find occurences of (signer= and escape out *'s
+ while (pos != -1) {
+
+ //walk back and look for '(' to see if this is an attr
+ walkbackPos = pos-1;
+
+ //consume whitespace
+ while(walkbackPos >= 0 && Character.isWhitespace(filter.charAt(walkbackPos))) {
+ walkbackPos--;
+ }
+ if (walkbackPos <0) {
+ //filter is invalid - FilterImpl will throw error
+ break;
+ }
+
+ //check to see if we have unescaped '('
+ if (filter.charAt(walkbackPos) != '(' || (walkbackPos > 0 && filter.charAt(walkbackPos-1) == '\\')) {
+ //'(' was escaped or not there
+ pos = filter.indexOf("signer",pos+6); //$NON-NLS-1$
+ continue;
+ }
+ pos+=6; //skip over 'signer'
+
+ //found signer - consume whitespace before '='
+ while (Character.isWhitespace(filter.charAt(pos))) {
+ pos++;
+ }
+
+ //look for '='
+ if (filter.charAt(pos) != '=') {
+ //attr was signerx - keep looking
+ pos = filter.indexOf("signer",pos); //$NON-NLS-1$
+ continue;
+ }
+ pos++; //skip over '='
+
+ //found signer value - escape '*'s
+ while (!(filter.charAt(pos) == ')' && filter.charAt(pos-1) != '\\')) {
+ if (filter.charAt(pos) == '*') {
+ filterBuf.insert(pos+numAsteriskFound,'\\');
+ numAsteriskFound++;
+ }
+ pos++;
+ }
+
+ //end of signer value - look for more?
+ pos = filter.indexOf("signer",pos); //$NON-NLS-1$
+ } //end while (pos != -1)
+ transformedFilter = filterBuf.toString();
+ } //end if (pos != -1)
+
+ appliedFilter = FrameworkUtil.createFilter( transformedFilter );
+ } catch (InvalidSyntaxException e) {
+ //we will return null
+ }
+ }
+ return appliedFilter;
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationDescriptor.java b/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationDescriptor.java
new file mode 100644
index 0000000..4764bd7
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationDescriptor.java
@@ -0,0 +1,714 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.application/src/org/osgi/service/application/ApplicationDescriptor.java,v 1.61 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 java.util.Map;
+
+import org.osgi.framework.Constants;
+import org.osgi.framework.InvalidSyntaxException;
+
+/**
+ * An OSGi service that represents an installed application and stores
+ * information about it. The application descriptor can be used for instance
+ * creation.
+ */
+
+public abstract class ApplicationDescriptor {
+ /*
+ * 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 localized name of the application.
+ */
+ public static final String APPLICATION_NAME = "application.name";
+
+ /**
+ * The property key for the localized icon of the application.
+ */
+ public static final String APPLICATION_ICON = "application.icon";
+
+ /**
+ * The property key for the unique identifier (PID) of the application.
+ */
+ public static final String APPLICATION_PID = Constants.SERVICE_PID;
+
+ /**
+ * The property key for the version of the application.
+ */
+ public static final String APPLICATION_VERSION = "application.version";
+
+ /**
+ * The property key for the name of the application vendor.
+ */
+ public static final String APPLICATION_VENDOR = Constants.SERVICE_VENDOR;
+
+
+ /**
+ * The property key for the visibility property of the application.
+ */
+ public static final String APPLICATION_VISIBLE = "application.visible";
+
+ /**
+ * The property key for the launchable property of the application.
+ */
+ public static final String APPLICATION_LAUNCHABLE = "application.launchable";
+
+ /**
+ * The property key for the locked property of the application.
+ */
+ public static final String APPLICATION_LOCKED = "application.locked";
+
+ /**
+ * The property key for the localized description of the application.
+ */
+ public static final String APPLICATION_DESCRIPTION = "application.description";
+
+ /**
+ * The property key for the localized documentation of the application.
+ */
+ public static final String APPLICATION_DOCUMENTATION = "application.documentation";
+
+ /**
+ * The property key for the localized copyright notice of the application.
+ */
+ public static final String APPLICATION_COPYRIGHT = "application.copyright";
+
+ /**
+ * The property key for the localized license of the application.
+ */
+ public static final String APPLICATION_LICENSE = "application.license";
+
+ /**
+ * The property key for the application container of the application.
+ */
+ public static final String APPLICATION_CONTAINER = "application.container";
+
+ /**
+ * The property key for the location of the application.
+ */
+ public static final String APPLICATION_LOCATION = "application.location";
+
+
+ private final String pid;
+
+
+ /**
+ * Constructs the <code>ApplicationDescriptor</code>.
+ *
+ * @param applicationId
+ * The identifier of the application. Its value is also available
+ * as the <code>service.pid</code> service property of this
+ * <code>ApplicationDescriptor</code> service. This parameter must not
+ * be <code>null</code>.
+ * @throws NullPointerException if the specified <code>applicationId</code> is null.
+ */
+ protected ApplicationDescriptor(String applicationId) {
+ if(null == applicationId ) {
+ throw new NullPointerException("Application ID must not be null!");
+ }
+
+ this.pid = applicationId;
+ try {
+ delegate = new Delegate();
+ delegate.setApplicationDescriptor( this, applicationId );
+ }
+ catch (Exception e) {
+ // Too bad ...
+ e.printStackTrace();
+ System.err
+ .println("No implementation available for ApplicationDescriptor, property is: "
+ + Delegate.cName);
+ }
+ }
+
+ /**
+ * Returns the identifier of the represented application.
+ *
+ * @return the identifier of the represented application
+ */
+ public final String getApplicationId() {
+ return pid;
+ }
+
+ /**
+ * This method verifies whether the specified <code>pattern</code>
+ * matches the Distinguished Names of any of the certificate chains
+ * used to authenticate this application.
+ * <P>
+ * The <code>pattern</code> must adhere to the
+ * syntax defined in {@link org.osgi.service.application.ApplicationAdminPermission}
+ * for signer attributes.
+ * <p>
+ * This method is used by {@link ApplicationAdminPermission#implies(java.security.Permission)} method
+ * to match target <code>ApplicationDescriptor</code> and filter.
+ *
+ * @param pattern a pattern for a chain of Distinguished Names. It must not be null.
+ * @return <code>true</code> if the specified pattern matches at least
+ * one of the certificate chains used to authenticate this application
+ * @throws NullPointerException if the specified <code>pattern</code> is null.
+ * @throws IllegalStateException if the application descriptor was
+ * unregistered
+ */
+ public abstract boolean matchDNChain( String pattern );
+
+ /**
+ * Returns the properties of the application descriptor as key-value pairs.
+ * The return value contains the locale aware and unaware properties as
+ * well. The returned <code>Map</code> will include the service
+ * properties of this <code>ApplicationDescriptor</code> as well.
+ * <p>
+ * This method will call the <code>getPropertiesSpecific</code> method
+ * to enable the container implementation to insert application model and/or
+ * container implementation specific properties.
+ * <P>
+ * The returned {@link java.util.Map} will contain the standard OSGi service
+ * properties as well
+ * (e.g. service.id, service.vendor etc.) and specialized application
+ * descriptors may offer further service properties. The returned Map contains
+ * a snapshot of the properties. It will not reflect further changes in the
+ * property values nor will the update of the Map change the corresponding
+ * service property.
+ *
+ * @param locale
+ * the locale string, it may be null, the value null means the
+ * default locale. If the provided locale is the empty String
+ * (<code>""</code>)then raw (non-localized) values are returned.
+ *
+ * @return copy of the service properties of this application descriptor service,
+ * according to the specified locale. If locale is null then the
+ * default locale's properties will be returned. (Since service
+ * properties are always exist it cannot return null.)
+ *
+ * @throws IllegalStateException
+ * if the application descriptor is unregistered
+ */
+ public final Map getProperties(String locale) {
+ Map props = getPropertiesSpecific( locale );
+
+ /* currently the ApplicationDescriptor manages the load/save of locking */
+ boolean isLocked = delegate.isLocked(); // the real locking state
+ Boolean containerLocked = (Boolean)props.remove( APPLICATION_LOCKED );
+ if( containerLocked != null && containerLocked.booleanValue() != isLocked ) {
+ try {
+ if( isLocked ) /* if the container's information is not correct */
+ lockSpecific(); /* about the locking state (after loading the lock states) */
+ else
+ unlockSpecific();
+ }catch( Exception e ) {}
+ }
+ /* replace the container's lock with the application model's lock, that's the correct */
+ props.put( APPLICATION_LOCKED, new Boolean( isLocked ) );
+ return props;
+ }
+
+ /**
+ * Container implementations can provide application model specific
+ * and/or container implementation specific properties via this
+ * method.
+ *
+ * Localizable properties must be returned localized if the provided
+ * <code>locale</code> argument is not the empty String. The value
+ * <code>null</code> indicates to use the default locale, for other
+ * values the specified locale should be used.
+ *
+ * The returned {@link java.util.Map} must contain the standard OSGi service
+ * properties as well
+ * (e.g. service.id, service.vendor etc.) and specialized application
+ * descriptors may offer further service properties.
+ * The returned <code>Map</code>
+ * contains a snapshot of the properties. It will not reflect further changes in the
+ * property values nor will the update of the Map change the corresponding
+ * service property.
+
+ * @param locale the locale to be used for localizing the properties.
+ * If <code>null</code> the default locale should be used. If it is
+ * the empty String (<code>""</code>) then raw (non-localized) values
+ * should be returned.
+ *
+ * @return the application model specific and/or container implementation
+ * specific properties of this application descriptor.
+ *
+ * @throws IllegalStateException
+ * if the application descriptor is unregistered
+ */
+ protected abstract Map getPropertiesSpecific(String locale);
+
+ /**
+ * Launches a new instance of an application. The <code>args</code> parameter specifies
+ * the startup parameters for the instance to be launched, it may be null.
+ * <p>
+ * The following steps are made:
+ * <UL>
+ * <LI>Check for the appropriate permission.
+ * <LI>Check the locking state of the application. If locked then return
+ * null otherwise continue.
+ * <LI>Calls the <code>launchSpecific()</code> method to create and start an application
+ * instance.
+ * <LI>Returns the <code>ApplicationHandle</code> returned by the
+ * launchSpecific()
+ * </UL>
+ * The caller has to have ApplicationAdminPermission(applicationPID,
+ * "launch") in order to be able to perform this operation.
+ * <P>
+ * The <code>Map</code> argument of the launch method contains startup
+ * arguments for the
+ * application. The keys used in the Map must be non-null, non-empty <code>String<code>
+ * objects. They can be standard or application
+ * specific. OSGi defines the <code>org.osgi.triggeringevent</code>
+ * key to be used to
+ * pass the triggering event to a scheduled application, however
+ * in the future it is possible that other well-known keys will be defined.
+ * To avoid unwanted clashes of keys, the following rules should be applied:
+ * <ul>
+ * <li>The keys starting with the dash (-) character are application
+ * specific, no well-known meaning should be associated with them.</li>
+ * <li>Well-known keys should follow the reverse domain name based naming.
+ * In particular, the keys standardized in OSGi should start with
+ * <code>org.osgi.</code>.</li>
+ * </ul>
+ * <P>
+ * The method is synchonous, it return only when the application instance was
+ * successfully started or the attempt to start it failed.
+ * <P>
+ * This method never returns <code>null</code>. If launching an application fails,
+ * the appropriate exception is thrown.
+ *
+ * @param arguments
+ * Arguments for the newly launched application, may be null
+ *
+ * @return the registered ApplicationHandle, which represents the newly
+ * launched application instance. Never returns <code>null</code>.
+ *
+ * @throws SecurityException
+ * if the caller doesn't have "lifecycle"
+ * ApplicationAdminPermission for the application.
+ * @throws ApplicationException
+ * if starting the application failed
+ * @throws IllegalStateException
+ * if the application descriptor is unregistered
+ * @throws IllegalArgumentException
+ * if the specified <code>Map</code> contains invalid keys
+ * (null objects, empty <code>String</code> or a key that is not
+ * <code>String</code>)
+ */
+ public final ApplicationHandle launch(Map arguments)
+ throws ApplicationException {
+ try {
+ delegate.launch(arguments);
+ }catch( SecurityException se ) {
+ isLaunchableSpecific(); /* check whether the bundle was uninstalled */
+ /* if yes, throws IllegalStateException */
+ throw se; /* otherwise throw the catched SecurityException */
+ }
+ if( !isLaunchableSpecific() )
+ throw new ApplicationException(ApplicationException.APPLICATION_NOT_LAUNCHABLE,
+ "Cannot launch the application!");
+ try {
+ return launchSpecific(arguments);
+ } catch(IllegalStateException ise) {
+ throw ise;
+ } catch(SecurityException se) {
+ throw se;
+ } catch( ApplicationException ae) {
+ throw ae;
+ } catch(Exception t) {
+ throw new ApplicationException(ApplicationException.APPLICATION_INTERNAL_ERROR, t);
+ }
+ }
+
+ /**
+ * Called by launch() to create and start a new instance in an application
+ * model specific way. It also creates and registeres the application handle
+ * to represent the newly created and started instance and registeres it.
+ * The method is synchonous, it return only when the application instance was
+ * successfully started or the attempt to start it failed.
+ * <P>
+ * This method must not return <code>null</code>. If launching the application
+ * failed, and exception must be thrown.
+ *
+ * @param arguments
+ * the startup parameters of the new application instance, may be
+ * null
+ *
+ * @return the registered application model
+ * specific application handle for the newly created and started
+ * instance.
+ *
+ * @throws IllegalStateException
+ * if the application descriptor is unregistered
+ * @throws Exception
+ * if any problem occures.
+ */
+ protected abstract ApplicationHandle launchSpecific(Map arguments)
+ throws Exception;
+
+ /**
+ * This method is called by launch() to verify that according to the
+ * container, the application is launchable.
+ *
+ * @return true, if the application is launchable according to the
+ * container, false otherwise.
+ *
+ * @throws IllegalStateException
+ * if the application descriptor is unregistered
+ */
+ protected abstract boolean isLaunchableSpecific();
+
+ /**
+ * Schedules the application at a specified event. Schedule information
+ * should not get lost even if the framework or the device restarts so it
+ * should be stored in a persistent storage. The method registers a
+ * {@link ScheduledApplication} service in Service Registry, representing
+ * the created schedule.
+ * <p>
+ * The <code>Map</code> argument of the method contains startup
+ * arguments for the application. The keys used in the Map must be non-null,
+ * non-empty <code>String<code> objects.
+ * <p>
+ * The created schedules have a unique identifier within the scope of this
+ * <code>ApplicationDescriptor</code>. This identifier can be specified
+ * in the <code>scheduleId</code> argument. If this argument is <code>null</code>,
+ * the identifier is automatically generated.
+ *
+ * @param scheduleId
+ * the identifier of the created schedule. It can be <code>null</code>,
+ * in this case the identifier is automatically generated.
+ * @param arguments
+ * the startup arguments for the scheduled application, may be
+ * null
+ * @param topic
+ * specifies the topic of the triggering event, it may contain a
+ * trailing asterisk as wildcard, the empty string is treated as
+ * "*", must not be null
+ * @param eventFilter
+ * specifies and LDAP filter to filter on the properties of the
+ * triggering event, may be null
+ * @param recurring
+ * if the recurring parameter is false then the application will
+ * be launched only once, when the event firstly occurs. If the
+ * parameter is true then scheduling will take place for every
+ * event occurrence; i.e. it is a recurring schedule
+ *
+ * @return the registered scheduled application service
+ *
+ * @throws NullPointerException
+ * if the topic is <code>null</code>
+ * @throws InvalidSyntaxException
+ * if the specified <code>eventFilter</code> is not syntactically correct
+ * @throws ApplicationException
+ * if the schedule couldn't be created. The possible error
+ * codes are
+ * <ul>
+ * <li> {@link ApplicationException#APPLICATION_DUPLICATE_SCHEDULE_ID}
+ * if the specified <code>scheduleId</code> is already used
+ * for this <code>ApplicationDescriptor</code>
+ * <li> {@link ApplicationException#APPLICATION_SCHEDULING_FAILED}
+ * if the scheduling failed due to some internal reason
+ * (e.g. persistent storage error).
+ * </ul>
+ * @throws SecurityException
+ * if the caller doesn't have "schedule"
+ * ApplicationAdminPermission for the application.
+ * @throws IllegalStateException
+ * if the application descriptor is unregistered
+ * @throws IllegalArgumentException
+ * if the specified <code>Map</code> contains invalid keys
+ * (null objects, empty <code>String</code> or a key that is not
+ * <code>String</code>)
+ */
+ public final ScheduledApplication schedule(String scheduleId, Map arguments, String topic,
+ String eventFilter, boolean recurring) throws InvalidSyntaxException,
+ ApplicationException {
+ isLaunchableSpecific(); // checks if the ApplicationDescriptor was already unregistered
+ try {
+ return delegate.schedule(scheduleId, arguments, topic, eventFilter, recurring);
+ }catch( SecurityException se ) {
+ isLaunchableSpecific(); /* check whether the bundle was uninstalled */
+ /* if yes, throws IllegalStateException */
+ throw se; /* otherwise throw the catched SecurityException */
+ }
+ }
+
+ /**
+ * Sets the lock state of the application. If an application is locked then
+ * launching a new instance is not possible. It does not affect the already
+ * launched instances.
+ *
+ * @throws SecurityException
+ * if the caller doesn't have "lock" ApplicationAdminPermission
+ * for the application.
+ * @throws IllegalStateException
+ * if the application descriptor is unregistered
+ */
+ public final void lock() {
+ try {
+ delegate.lock();
+ }catch( SecurityException se ) {
+ isLaunchableSpecific(); /* check whether the bundle was uninstalled */
+ /* if yes, throws IllegalStateException */
+ throw se; /* otherwise throw the catched SecurityException */
+ }
+ lockSpecific();
+ }
+
+ /**
+ * This method is used to notify the container implementation that the
+ * corresponding application has been locked and it should update the
+ * <code>application.locked</code> service property accordingly.
+ * @throws IllegalStateException
+ * if the application descriptor is unregistered
+ */
+ protected abstract void lockSpecific();
+
+ /**
+ * Unsets the lock state of the application.
+ *
+ * @throws SecurityException
+ * if the caller doesn't have "lock" ApplicationAdminPermission
+ * for the application.
+ * @throws IllegalStateException
+ * if the application descriptor is unregistered
+ */
+ public final void unlock() {
+ try {
+ delegate.unlock();
+ }catch( SecurityException se ) {
+ isLaunchableSpecific(); /* check whether the bundle was uninstalled */
+ /* if yes, throws IllegalStateException */
+ throw se; /* otherwise throw the catched SecurityException */
+ }
+ unlockSpecific();
+ }
+
+ /**
+ * This method is used to notify the container implementation that the
+ * corresponding application has been unlocked and it should update the
+ * <code>application.locked</code> service property accordingly.
+
+ * @throws IllegalStateException
+ * if the application descriptor is unregistered
+ */
+ protected abstract void unlockSpecific();
+
+ Delegate delegate;
+ /**
+ * This class will load the class named
+ * by the org.osgi.vendor.application.ApplicationDescriptor and delegate
+ * method calls to an instance of the class.
+ */
+ static class Delegate {
+ static String cName;
+ static Class implementation;
+ static Method setApplicationDescriptor;
+ static Method isLocked;
+ static Method lock;
+ static Method unlock;
+ static Method schedule;
+ static Method launch;
+
+ static {
+ AccessController.doPrivileged(new PrivilegedAction() {
+ public Object run() {
+ cName = System.getProperty("org.osgi.vendor.application.ApplicationDescriptor");
+ if (cName == null) {
+ throw new NoClassDefFoundError("org.osgi.vendor.application.ApplicationDescriptor property must be set");
+ }
+
+ try {
+ implementation = Class.forName(cName);
+ }
+ catch (ClassNotFoundException e) {
+ throw new NoClassDefFoundError(e.toString());
+ }
+
+ try {
+ setApplicationDescriptor = implementation.getMethod("setApplicationDescriptor",
+ new Class[] {ApplicationDescriptor.class, String.class});
+ isLocked = implementation.getMethod("isLocked",
+ new Class[] {});
+ lock = implementation.getMethod("lock",
+ new Class[] {});
+ unlock = implementation.getMethod("unlock",
+ new Class[] {});
+ schedule = implementation.getMethod("schedule",
+ new Class[] {String.class, Map.class, String.class, String.class,
+ boolean.class});
+ launch = implementation.getMethod("launch",
+ new Class[] {Map.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 setApplicationDescriptor(ApplicationDescriptor d, String pid ) {
+ try {
+ try {
+ setApplicationDescriptor.invoke(target, new Object[] {d, pid});
+ }
+ catch (InvocationTargetException e) {
+ throw e.getTargetException();
+ }
+ }
+ catch (Error e) {
+ throw e;
+ }
+ catch (RuntimeException e) {
+ throw e;
+ }
+ catch (Throwable e) {
+ throw new RuntimeException(e.toString());
+ }
+ }
+
+ boolean isLocked() {
+ try {
+ try {
+ return ((Boolean)isLocked.invoke(target, new Object[] {})).booleanValue();
+ }
+ 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 lock() {
+ try {
+ try {
+ lock.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());
+ }
+ }
+
+ void unlock() {
+ try {
+ try {
+ unlock.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());
+ }
+ }
+
+ ScheduledApplication schedule(String scheduleId, Map args, String topic, String filter,
+ boolean recurs) throws InvalidSyntaxException, ApplicationException {
+ try {
+ try {
+ return (ScheduledApplication)schedule.invoke(target, new Object[] {scheduleId, args, topic, filter,
+ new Boolean(recurs)});
+ }
+ catch (InvocationTargetException e) {
+ throw e.getTargetException();
+ }
+ }
+ catch (InvalidSyntaxException e) {
+ throw e;
+ }
+ catch (ApplicationException e) {
+ throw e;
+ }
+ catch (Error e) {
+ throw e;
+ }
+ catch (RuntimeException e) {
+ throw e;
+ }
+ catch (Throwable e) {
+ throw new RuntimeException(e.toString());
+ }
+ }
+
+ void launch(Map arguments) throws ApplicationException {
+ try {
+ try {
+ launch.invoke(target, new Object[] {arguments});
+ }
+ catch (InvocationTargetException e) {
+ throw e.getTargetException();
+ }
+ }
+ catch (ApplicationException e) {
+ throw e;
+ }
+ catch (Error e) {
+ throw e;
+ }
+ catch (RuntimeException e) {
+ throw e;
+ }
+ catch (Throwable e) {
+ throw new RuntimeException(e.toString());
+ }
+ }
+ }
+
+
+}
\ No newline at end of file
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationException.java b/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationException.java
new file mode 100644
index 0000000..c30e112
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationException.java
@@ -0,0 +1,136 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.application/src/org/osgi/service/application/ApplicationException.java,v 1.10 2006/07/10 11:49:12 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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;
+
+/**
+ * This exception is used to indicate problems related to application
+ * lifecycle management.
+ *
+ * <code>ApplicationException</code> object is created by the Application Admin to denote
+ * an exception condition in the lifecycle of an application.
+ * <code>ApplicationException</code>s should not be created by developers.
+ * <br/>
+ * <code>ApplicationException</code>s are associated with an error code. This code
+ * describes the type of problem reported in this exception. The possible codes are:
+ * <ul>
+ * <li> {@link #APPLICATION_LOCKED} - The application couldn't be launched because it is locked.</li>
+ * <li> {@link #APPLICATION_NOT_LAUNCHABLE} - The application is not in launchable state.</li>
+ * <li> {@link #APPLICATION_INTERNAL_ERROR} - An exception was thrown by the application or its
+ * container during launch.</li>
+ * <li> {@link #APPLICATION_SCHEDULING_FAILED} - The scheduling of an application
+ * failed.
+ * </ul>
+ *
+ */
+public class ApplicationException extends Exception {
+ private static final long serialVersionUID = -7173190453622508207L;
+ private final Throwable cause;
+ private final int errorCode;
+
+ /**
+ * The application couldn't be launched because it is locked.
+ */
+ public static final int APPLICATION_LOCKED = 0x01;
+
+ /**
+ * The application is not in launchable state, it's
+ * {@link ApplicationDescriptor#APPLICATION_LAUNCHABLE}
+ * attribute is false.
+ */
+ public static final int APPLICATION_NOT_LAUNCHABLE = 0x02;
+
+ /**
+ * An exception was thrown by the application or the corresponding
+ * container during launch. The exception is available in {@link #getCause()}.
+ */
+ public static final int APPLICATION_INTERNAL_ERROR = 0x03;
+
+ /**
+ * The application schedule could not be created due to some internal error
+ * (for example, the schedule information couldn't be saved).
+ */
+ public static final int APPLICATION_SCHEDULING_FAILED = 0x04;
+
+ /**
+ * The application scheduling failed because the specified identifier
+ * is already in use.
+ */
+ public static final int APPLICATION_DUPLICATE_SCHEDULE_ID = 0x05;
+
+ /**
+ * Creates an <code>ApplicationException</code> with the specified error code.
+ * @param errorCode The code of the error
+ */
+ public ApplicationException(int errorCode) {
+ this(errorCode,(Throwable) null);
+ }
+
+ /**
+ * Creates a <code>ApplicationException</code> that wraps another exception.
+ *
+ * @param errorCode The code of the error
+ * @param cause The cause of this exception.
+ */
+ public ApplicationException(int errorCode, Throwable cause) {
+ super();
+ this.cause = cause;
+ this.errorCode = errorCode;
+ }
+
+ /**
+ * Creates an <code>ApplicationException</code> with the specified error code.
+ * @param errorCode The code of the error
+ * @param message The associated message
+ */
+ public ApplicationException(int errorCode, String message) {
+ this(errorCode, message,null);
+ }
+
+ /**
+ * Creates a <code>ApplicationException</code> that wraps another exception.
+ *
+ * @param errorCode The code of the error
+ * @param message The associated message.
+ * @param cause The cause of this exception.
+ */
+ public ApplicationException(int errorCode, String message, Throwable cause) {
+ super(message);
+ this.cause = cause;
+ this.errorCode = errorCode;
+ }
+
+ /**
+ * 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.
+ */
+ public Throwable getCause() {
+ return cause;
+ }
+
+ /**
+ * Returns the error code associcated with this exception.
+ * @return The error code of this exception.
+ */
+ public int getErrorCode() {
+ return errorCode;
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationHandle.java b/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationHandle.java
new file mode 100644
index 0000000..a0bdc89
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/application/ApplicationHandle.java
@@ -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:
+ * <<i>application descriptor PID</i>>.<<i>index</i>>
+ * where <<i>application descriptor PID</i>> is the PID of the
+ * corresponding <code>ApplicationDescriptor</code> and <<i>index</i>>
+ * 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());
+ }
+ }
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/application/ScheduledApplication.java b/org.osgi.compendium/src/main/java/org/osgi/service/application/ScheduledApplication.java
new file mode 100644
index 0000000..46cfe5e
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/application/ScheduledApplication.java
@@ -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();
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java b/org.osgi.compendium/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java
index 0d8c6a8..131f863 100644
--- a/org.osgi.compendium/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java
@@ -1,5 +1,5 @@
/*
- * $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 $
+ * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationAdmin.java,v 1.17 2006/09/26 13:33:09 hargrave Exp $
*
* Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
*
@@ -100,7 +100,7 @@
* <code>ConfigurationAdmin</code> must use a
* {@link org.osgi.framework.ServiceFactory} to support this concept.
*
- * @version $Revision: 1.16 $
+ * @version $Revision: 1.17 $
*/
public interface ConfigurationAdmin {
/**
@@ -230,7 +230,7 @@
* <code>ConfigurationPermission[*,CONFIGURE]</code>.
*
* <p>
- * The syntax of the filter string is as defined in the <code>Filter</code>
+ * The syntax of the filter string is as defined in the {@link org.osgi.framework.Filter}
* class. The filter can test any configuration parameters including the
* following system properties:
* <ul>
@@ -244,10 +244,10 @@
* 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
+ * @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
+ * @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
*/
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/BundleInfo.java b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/BundleInfo.java
new file mode 100644
index 0000000..9bd31fb
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/BundleInfo.java
@@ -0,0 +1,43 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/BundleInfo.java,v 1.3 2006/06/16 16:31:39 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.deploymentadmin;
+
+import org.osgi.framework.Version;
+
+/**
+ * Represents a bundle in the array given back by the {@link DeploymentPackage#getBundleInfos()}
+ * method.
+ */
+public interface BundleInfo {
+
+ /**
+ * Returns the Bundle Symbolic Name of the represented bundle.
+ *
+ * @return the Bundle Symbolic Name
+ */
+ String getSymbolicName();
+
+ /**
+ * Returns the version of the represented bundle.
+ *
+ * @return the version of the represented bundle
+ */
+ Version getVersion();
+
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdmin.java b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdmin.java
new file mode 100644
index 0000000..9376d14
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdmin.java
@@ -0,0 +1,139 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/DeploymentAdmin.java,v 1.28 2007/02/07 18:53:07 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 2007). 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.deploymentadmin;
+
+import java.io.InputStream;
+
+import org.osgi.framework.Bundle;
+
+/**
+ * This is the interface of the Deployment Admin service.<p>
+ *
+ * The OSGi Service Platform provides mechanisms to manage the life cycle of
+ * bundles, configuration objects, permission objects, etc. but the overall consistency
+ * of the runtime configuration is the responsibility of the management
+ * agent. In other words, the management agent decides to install, update,
+ * or uninstall bundles, create or delete configuration or permission objects, as
+ * well as manage other resource types, etc.<p>
+ *
+ * The Deployment Admin service standardizes the access to some of the responsibilities
+ * of the management agent. The service provides functionality to manage Deployment Packages
+ * (see {@link DeploymentPackage}). A Deployment Package groups resources as a unit
+ * of management. A Deployment Package is something that can be installed, updated,
+ * and uninstalled as a unit.<p>
+ *
+ * The Deployment Admin functionality is exposed as a standard OSGi service with no
+ * mandatory service parameters.
+ */
+public interface DeploymentAdmin {
+
+ /**
+ * Installs a Deployment Package from an input stream. If a version of that Deployment Package
+ * is already installed and the versions are different, the installed version is updated
+ * with this new version even if it is older (downgrade). If the two versions are the same, then this
+ * method simply returns with the old (target) Deployment Package without any action.
+ *
+ * @param in the input stream the Deployment Package can be read from. It mustn't be <code>null</code>.
+ * @return A DeploymentPackage object representing the newly installed/updated Deployment Package.
+ * It is never <code>null</code>.
+ * @throws IllegalArgumentException if the got InputStream parameter is <code>null</code>
+ * @throws DeploymentException if the installation was not successful. For detailed error code description
+ * see {@link DeploymentException}.
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentAdminPermission}("<filter>", "install") permission.
+ * @see DeploymentAdminPermission
+ * @see DeploymentPackage
+ * @see DeploymentPackage
+ */
+ DeploymentPackage installDeploymentPackage(InputStream in) throws DeploymentException;
+
+ /**
+ * Lists the Deployment Packages currently installed on the platform.<p>
+ *
+ * {@link DeploymentAdminPermission}("<filter>", "list") is
+ * needed for this operation to the effect that only those packages are listed in
+ * the array to which the caller has appropriate DeploymentAdminPermission. It has
+ * the consequence that the method never throws SecurityException only doesn't
+ * put certain Deployment Packages into the array.<p>
+ *
+ * During an installation of an existing package (update) or during an uninstallation,
+ * the target must remain in this list until the installation (uninstallation) process
+ * is completed, after which the source (or <code>null</code> in case of uninstall)
+ * replaces the target.
+ *
+ * @return the array of <code>DeploymentPackage</code> objects representing all the
+ * installed Deployment Packages. The return value cannot be <code>null</code>.
+ * In case of missing permissions it may give back an empty array.
+ * @see DeploymentPackage
+ * @see DeploymentAdminPermission
+ */
+ DeploymentPackage[] listDeploymentPackages();
+
+ /**
+ * Gets the currenlty installed {@link DeploymentPackage} instance which has the given
+ * symbolic name.<p>
+ *
+ * During an installation of an existing package (update) or during an uninstallation,
+ * the target Deployment Package must remain the return value until the installation
+ * (uninstallation) process is completed, after which the source (or <code>null</code>
+ * in case of uninstall) is the return value.
+ *
+ * @param symbName the symbolic name of the Deployment Package to be retrieved. It mustn't be
+ * <code>null</code>.
+ * @return The <code>DeploymentPackage</code> for the given symbolic name.
+ * If there is no Deployment Package with that symbolic name currently installed,
+ * <code>null</code> is returned.
+ * @throws IllegalArgumentException if the given <code>symbName</code> is <code>null</code>
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentAdminPermission}("<filter>", "list") permission.
+ * @see DeploymentPackage
+ * @see DeploymentAdminPermission
+ */
+ DeploymentPackage getDeploymentPackage(String symbName);
+
+ /**
+ * Gives back the installed {@link DeploymentPackage} that owns the bundle. Deployment Packages own their
+ * bundles by their Bundle Symbolic Name. It means that if a bundle belongs to an installed
+ * Deployment Packages (and at most to one) the Deployment Admin assigns the bundle to its owner
+ * Deployment Package by the Symbolic Name of the bundle.<p>
+ *
+ * @param bundle the bundle whose owner is queried
+ * @return the Deployment Package Object that owns the bundle or <code>null</code> if the bundle doesn't
+ * belong to any Deployment Packages (standalone bundles)
+ * @throws IllegalArgumentException if the given <code>bundle</code> is <code>null</code>
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentAdminPermission}("<filter>", "list") permission.
+ * @see DeploymentPackage
+ * @see DeploymentAdminPermission
+ */
+ DeploymentPackage getDeploymentPackage(Bundle bundle);
+
+ /**
+ * This method cancels the currently active deployment session. This method addresses the need
+ * to cancel the processing of excessively long running, or resource consuming install, update
+ * or uninstall operations.<p>
+ *
+ * @return true if there was an active session and it was successfully cancelled.
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentAdminPermission}("<filter>", "cancel") permission.
+ * @see DeploymentAdminPermission
+ */
+ boolean cancel();
+
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java
new file mode 100644
index 0000000..34509cf
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java
@@ -0,0 +1,331 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java,v 1.40 2006/07/12 21:22:10 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.deploymentadmin;
+
+import java.io.InputStream;
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationTargetException;
+import java.security.*;
+
+import org.osgi.framework.Bundle;
+
+/**
+ * DeploymentAdminPermission controls access to the Deployment Admin service.<p>
+ *
+ * The permission uses a filter string formatted similarly to the {@link org.osgi.framework.Filter}.
+ * The filter determines the target of the permission. The <code>DeploymentAdminPermission</code> uses the
+ * <code>name</code> and the <code>signer</code> filter attributes only. The value of the <code>signer</code>
+ * attribute is matched against the signer chain (represented with its semicolon separated Distinguished Name chain)
+ * of the Deployment Package, and the value of the <code>name</code> attribute is matched against the value of the
+ * "DeploymentPackage-Name" manifest header of the Deployment Package. Example:
+ *
+ * <ul>
+ * <li>(signer=cn = Bugs Bunny, o = ACME, c = US)</li>
+ * <li>(name=org.osgi.ExampleApp)</li>
+ * </ul>
+ *
+ * Wildcards also can be used:<p>
+ *
+ * <pre>
+ * (signer=cn=*,o=ACME,c=*)
+ * </pre>
+ * "cn" and "c" may have an arbitrary value
+ *
+ * <pre>
+ * (signer=*, o=ACME, c=US)
+ * </pre>
+ * Only the value of "o" and "c" are significant
+ *
+ * <pre>
+ * (signer=* ; ou=S & V, o=Tweety Inc., c=US)
+ * </pre>
+ * The first element of the certificate chain is
+ * not important, only the second (the
+ * Distingushed Name of the root certificate)
+ *
+ * <pre>
+ * (signer=- ; *, o=Tweety Inc., c=US)
+ * </pre>
+ * The same as the previous but '-' represents
+ * zero or more certificates, whereas the asterisk
+ * only represents a single certificate
+ *
+ * <pre>
+ * (name=*)
+ * </pre>
+ * The name of the Deployment Package doesn't matter
+ *
+ * <pre>
+ * (name=org.osgi.*)
+ * </pre>
+ * The name has to begin with "org.osgi."
+ *
+ * <p>The following actions are allowed:<p>
+ *
+ * <b>list</b>
+ * <p>
+ * A holder of this permission can access the inventory information of the deployment
+ * packages selected by the <filter> string. The filter selects the deployment packages
+ * on which the holder of the permission can acquire detailed inventory information.
+ * See {@link DeploymentAdmin#getDeploymentPackage(Bundle)},
+ * {@link DeploymentAdmin#getDeploymentPackage(String)} and
+ * {@link DeploymentAdmin#listDeploymentPackages}.<p>
+ *
+ * <b>install</b><p>
+ *
+ * A holder of this permission can install/update deployment packages if the deployment
+ * package satisfies the <filter> string. See {@link DeploymentAdmin#installDeploymentPackage}.<p>
+ *
+ * <b>uninstall</b><p>
+ *
+ * A holder of this permission can uninstall deployment packages if the deployment
+ * package satisfies the <filter> string. See {@link DeploymentPackage#uninstall}.<p>
+ *
+ * <b>uninstall_forced</b><p>
+ *
+ * A holder of this permission can forcefully uninstall deployment packages if the deployment
+ * package satisfies the <filter> string. See {@link DeploymentPackage#uninstallForced}.<p>
+ *
+ * <b>cancel</b><p>
+ *
+ * A holder of this permission can cancel an active deployment action. This action being
+ * cancelled could correspond to the install, update or uninstall of a deployment package
+ * that satisfies the <filter> string. See {@link DeploymentAdmin#cancel}<p>
+ *
+ * <b>metadata</b><p>
+ *
+ * A holder of this permission is able to retrieve metadata information about a Deployment
+ * Package (e.g. is able to ask its manifest hedares).
+ * See {@link org.osgi.service.deploymentadmin.DeploymentPackage#getBundle(String)},
+ * {@link org.osgi.service.deploymentadmin.DeploymentPackage#getBundleInfos()},
+ * {@link org.osgi.service.deploymentadmin.DeploymentPackage#getHeader(String)},
+ * {@link org.osgi.service.deploymentadmin.DeploymentPackage#getResourceHeader(String, String)},
+ * {@link org.osgi.service.deploymentadmin.DeploymentPackage#getResourceProcessor(String)},
+ * {@link org.osgi.service.deploymentadmin.DeploymentPackage#getResources()}<p>
+ *
+ * The actions string is converted to lowercase before processing.
+ */
+public final class DeploymentAdminPermission extends Permission {
+
+ /**
+ *
+ */
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Constant String to the "install" action.<p>
+ *
+ * @see DeploymentAdmin#installDeploymentPackage(InputStream)
+ */
+ public static final String INSTALL = "install";
+
+ /**
+ * Constant String to the "list" action.<p>
+ *
+ * @see DeploymentAdmin#listDeploymentPackages()
+ * @see DeploymentAdmin#getDeploymentPackage(String)
+ * @see DeploymentAdmin#getDeploymentPackage(Bundle)
+ */
+ public static final String LIST = "list";
+
+ /**
+ * Constant String to the "uninstall" action.<p>
+ *
+ * @see DeploymentPackage#uninstall()
+ */
+ public static final String UNINSTALL = "uninstall";
+
+ /**
+ * Constant String to the "uninstall_forced" action.<p>
+ *
+ * @see DeploymentPackage#uninstallForced()
+ */
+ public static final String UNINSTALL_FORCED = "uninstall_forced";
+
+ /**
+ * Constant String to the "cancel" action.<p>
+ *
+ * @see DeploymentAdmin#cancel
+ */
+ public static final String CANCEL = "cancel";
+
+ /**
+ * Constant String to the "metadata" action.<p>
+ *
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getBundle(String)
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getBundleInfos()
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getHeader(String)
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getResourceHeader(String, String)
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getResourceProcessor(String)
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getResources()
+ */
+ public static final String METADATA = "metadata";
+
+ private static final String delegateProperty = "org.osgi.vendor.deploymentadmin";
+ private static final Constructor constructor;
+ private final Permission delegate;
+ static {
+ constructor = (Constructor) AccessController.doPrivileged(new PrivilegedAction() {
+ public Object run() {
+ String pckg = System.getProperty(delegateProperty);
+ if (null == pckg)
+ throw new RuntimeException("Property '" + delegateProperty + "' is not set");
+ try {
+ Class c = Class.forName(pckg + ".DeploymentAdminPermission");
+ return c.getConstructor(new Class[] {String.class, String.class});
+ }
+ catch (Exception e) {
+ throw new RuntimeException(e.getMessage());
+ }
+ }});
+ }
+
+ /**
+ * Creates a new <code>DeploymentAdminPermission</code> object for the given <code>name</code> and
+ * <code>action</code>.<p>
+ * The <code>name</code> parameter identifies the target depolyment package the permission
+ * relates to. The <code>actions</code> parameter contains the comma separated list of allowed actions.
+ *
+ * @param name filter string, must not be null.
+ * @param actions action string, must not be null. "*" means all the possible actions.
+ * @throws IllegalArgumentException if the filter is invalid, the list of actions
+ * contains unknown operations or one of the parameters is null
+ */
+ public DeploymentAdminPermission(String name, String actions) {
+ super(name);
+ try {
+ try {
+ delegate = (Permission) constructor.newInstance(new Object[] {name, actions});
+ }
+ catch (InvocationTargetException e) {
+ throw e.getTargetException();
+ }
+ }
+ catch (Error e) {
+ throw e;
+ }
+ catch (RuntimeException e) {
+ throw e;
+ }
+ catch (Throwable e) {
+ throw new RuntimeException(e.toString());
+ }
+ }
+
+ /**
+ * Checks two DeploymentAdminPermission objects for equality.
+ * Two permission objects are equal if: <p>
+ *
+ * <ul>
+ * <li>their target filters are semantically equal and</li>
+ * <li>their actions are the same</li>
+ * </ul>
+ *
+ * @param obj The reference object with which to compare.
+ * @return true if the two objects are equal.
+ * @see java.lang.Object#equals(java.lang.Object)
+ */
+ public boolean equals(Object obj) {
+ if (obj == this)
+ return true;
+ if (!(obj instanceof DeploymentAdminPermission))
+ return false;
+ DeploymentAdminPermission dap = (DeploymentAdminPermission) obj;
+ return delegate.equals(dap.delegate);
+ }
+
+ /**
+ * Returns hash code for this permission object.
+ *
+ * @return Hash code for this permission object.
+ * @see java.lang.Object#hashCode()
+ */
+ public int hashCode() {
+ return delegate.hashCode();
+ }
+
+ /**
+ * Returns the String representation of the action list.<p>
+ * The method always gives back the actions in the following (alphabetical) order:
+ * <code>cancel, install, list, metadata, uninstall, uninstall_forced</code>
+ *
+ * @return Action list of this permission instance. This is a comma-separated
+ * list that reflects the action parameter of the constructor.
+ * @see java.security.Permission#getActions()
+ */
+ public String getActions() {
+ return delegate.getActions();
+ }
+
+ /**
+ * Checks if this DeploymentAdminPermission would imply the parameter permission.<p>
+ * Precondition of the implication is that the action set of this permission is the superset
+ * of the action set of the other permission. Further rules of implication are determined
+ * by the {@link org.osgi.framework.Filter} rules and the "OSGi Service Platform, Core
+ * Specification Release 4, Chapter Certificate Matching".<p>
+ *
+ * The allowed attributes are: <code>name</code> (the symbolic name of the deployment
+ * package) and <code>signer</code> (the signer of the deployment package). In both cases
+ * wildcards can be used.<p>
+ *
+ * Examples:
+ *
+ * <pre>
+ * 1. DeploymentAdminPermission("(name=org.osgi.ExampleApp)", "list")
+ * 2. DeploymentAdminPermission("(name=org.osgi.ExampleApp)", "list, install")
+ * 3. DeploymentAdminPermission("(name=org.osgi.*)", "list")
+ * 4. DeploymentAdminPermission("(signer=*, o=ACME, c=US)", "list")
+ * 5. DeploymentAdminPermission("(signer=cn = Bugs Bunny, o = ACME, c = US)", "list")
+ * </pre><p>
+ *
+ * <pre>
+ * 1. implies 1.
+ * 2. implies 1.
+ * 1. doesn't implies 2.
+ * 3. implies 1.
+ * 4. implies 5.
+ * </pre>
+ *
+ * @param permission Permission to check.
+ * @return true if this DeploymentAdminPermission object implies the
+ * specified permission.
+ * @see java.security.Permission#implies(java.security.Permission)
+ * @see org.osgi.framework.Filter
+ */
+ public boolean implies(Permission permission) {
+ if (!(permission instanceof DeploymentAdminPermission))
+ return false;
+
+ DeploymentAdminPermission dap = (DeploymentAdminPermission) permission;
+
+ return delegate.implies(dap.delegate);
+ }
+
+ /**
+ * Returns a new PermissionCollection object for storing DeploymentAdminPermission
+ * objects.
+ *
+ * @return The new PermissionCollection.
+ * @see java.security.Permission#newPermissionCollection()
+ */
+ public PermissionCollection newPermissionCollection() {
+ return delegate.newPermissionCollection();
+ }
+
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentException.java b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentException.java
new file mode 100644
index 0000000..bf5c6e6
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentException.java
@@ -0,0 +1,266 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/DeploymentException.java,v 1.20 2006/07/12 21:22:10 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.deploymentadmin;
+
+import java.io.InputStream;
+
+/**
+ * Checked exception received when something fails during any deployment
+ * processes. A <code>DeploymentException</code> always contains an error code
+ * (one of the constants specified in this class), and may optionally contain
+ * the textual description of the error condition and a nested cause exception.
+ */
+public class DeploymentException extends Exception {
+
+ /**
+ *
+ */
+ private static final long serialVersionUID = 916011169146851101L;
+
+ /**
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)},
+ * {@link DeploymentPackage#uninstall()} and {@link DeploymentPackage#uninstallForced()}
+ * methods can throw {@link DeploymentException} with this error code if the
+ * {@link DeploymentAdmin#cancel()} method is called from another thread.
+ */
+ public static final int CODE_CANCELLED = 401;
+
+ /**
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * methods can throw {@link DeploymentException} with this error code if
+ * the got InputStream is not a jar.
+ */
+ public static final int CODE_NOT_A_JAR = 404;
+
+ /**
+ * Order of files in the deployment package is bad. The right order is the
+ * following:<p>
+ *
+ * <ol>
+ * <li>META-INF/MANIFEST.MF</li>
+ * <li>META-INF/*.SF, META-INF/*.DSA, META-INF/*.RS</li>
+ * <li>Localization files</li>
+ * <li>Bundles</li>
+ * <li>Resources</li>
+ * </ol>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_ORDER_ERROR = 450;
+
+ /**
+ * Missing mandatory manifest header.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)} can throw
+ * exception with this error code.
+ */
+ public static final int CODE_MISSING_HEADER = 451;
+
+ /**
+ * Syntax error in any manifest header.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_BAD_HEADER = 452;
+
+ /**
+ * Fix pack version range doesn't fit to the version of the target
+ * deployment package or the target deployment package of the fix pack
+ * doesn't exist.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_MISSING_FIXPACK_TARGET = 453;
+
+ /**
+ * A bundle in the deployment package is marked as DeploymentPackage-Missing
+ * but there is no such bundle in the target deployment package.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_MISSING_BUNDLE = 454;
+
+ /**
+ * A resource in the source deployment package is marked as
+ * DeploymentPackage-Missing but there is no such resource in the target
+ * deployment package.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_MISSING_RESOURCE = 455;
+
+ /**
+ * Bad deployment package signing.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_SIGNING_ERROR = 456;
+
+ /**
+ * Bundle symbolic name is not the same as defined by the deployment package
+ * manifest.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_BUNDLE_NAME_ERROR = 457;
+
+ /**
+ * Matched resource processor service is a customizer from another
+ * deployment package.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_FOREIGN_CUSTOMIZER = 458;
+
+ /**
+ * Bundle with the same symbolic name alerady exists.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_BUNDLE_SHARING_VIOLATION = 460;
+
+ /**
+ * An artifact of any resource already exists.<p>
+ *
+ * This exception is thrown when the called resource processor throws a
+ * <code>ResourceProcessorException</code> with the
+ * {@link org.osgi.service.deploymentadmin.spi.ResourceProcessorException#CODE_RESOURCE_SHARING_VIOLATION}
+ * error code.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_RESOURCE_SHARING_VIOLATION = 461;
+
+ /**
+ * Exception with this error code is thrown when one of the Resource Processors
+ * involved in the deployment session threw a <code>ResourceProcessorException</code> with the
+ * {@link org.osgi.service.deploymentadmin.spi.ResourceProcessorException#CODE_PREPARE} error
+ * code.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)} and
+ * {@link DeploymentPackage#uninstall()} methods throw exception with this error code.
+ */
+ public static final int CODE_COMMIT_ERROR = 462;
+
+ /**
+ * Other error condition.<p>
+ *
+ * All Deployment Admin methods which throw <code>DeploymentException</code>
+ * can throw an exception with this error code if the error condition cannot be
+ * categorized.
+ */
+ public static final int CODE_OTHER_ERROR = 463;
+
+ /**
+ * The Resource Processor service with the given PID (see
+ * <code>Resource-Processor</code> manifest header) is not found.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)},
+ * {@link DeploymentPackage#uninstall()} and
+ * {@link DeploymentPackage#uninstallForced()}
+ * throws exception with this error code.
+ */
+ public static final int CODE_PROCESSOR_NOT_FOUND = 464;
+
+ /**
+ * When a client requests a new session with an install or uninstall
+ * operation, it must block that call until the earlier session is
+ * completed. The Deployment Admin service must throw a Deployment Exception
+ * with this error code when the session can not be created after an appropriate
+ * time out period.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)},
+ * {@link DeploymentPackage#uninstall()} and
+ * {@link DeploymentPackage#uninstallForced()}
+ * throws exception with this error code.
+ */
+ public static final int CODE_TIMEOUT = 465;
+
+ private final int code;
+ private final String message;
+ private final Throwable cause;
+
+ /**
+ * Create an instance of the exception.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ * @param message Message associated with the exception
+ * @param cause the originating exception
+ */
+ public DeploymentException(int code, String message, Throwable cause) {
+ this.code = code;
+ this.message = message;
+ this.cause = cause;
+ }
+
+ /**
+ * Create an instance of the exception. Cause exception is implicitly set to
+ * null.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ * @param message Message associated with the exception
+ */
+ public DeploymentException(int code, String message) {
+ this(code, message, null);
+ }
+
+ /**
+ * Create an instance of the exception. Cause exception and message are
+ * implicitly set to null.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ */
+ public DeploymentException(int code) {
+ this(code, null, null);
+ }
+
+ /**
+ * @return Returns the cause.
+ */
+ public Throwable getCause() {
+ return cause;
+ }
+
+ /**
+ * @return Returns the code.
+ */
+ public int getCode() {
+ return code;
+ }
+
+ /**
+ * @return Returns the message.
+ */
+ public String getMessage() {
+ return message;
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentPackage.java b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentPackage.java
new file mode 100644
index 0000000..0155771
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentPackage.java
@@ -0,0 +1,240 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/DeploymentPackage.java,v 1.26 2006/07/12 21:22:10 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.deploymentadmin;
+
+import org.osgi.framework.*;
+
+/**
+ * The <code>DeploymentPackage</code> object represents a deployment package (already installed
+ * or being currently processed). A Deployment Package groups resources as a unit
+ * of management. A deployment package is something that can be installed, updated,
+ * and uninstalled as a unit. A deployment package is a reified concept, like a bundle,
+ * in an OSGi Service Platform. It is not known by the OSGi Framework, but it is managed
+ * by the Deployment Admin service. A deployment package is a stream of resources
+ * (including bundles) which, once processed, will result in new artifacts (effects on
+ * the system) being added to the OSGi platform. These new artifacts can include
+ * installed Bundles, new configuration objects added to the Configuration Admin service,
+ * new Wire objects added to the Wire Admin service, or changed system properties, etc. All
+ * the changes caused by the processing of a deployment package are persistently
+ * associated with the deployment package, so that they can be appropriately cleaned
+ * up when the deployment package is uninstalled. There is a strict no overlap rule
+ * imposed on deployment packages. Two deployment packages are not allowed to create or
+ * manipulate the same artifact. Obviously, this means that a bundle cannot be in two
+ * different deployment packagess. Any violation of this no overlap rule is considered
+ * an error and the install or update of the offending deployment package must be aborted.<p>
+ *
+ * The Deployment Admin service should do as much as possible to ensure transactionality.
+ * It means that if a deployment package installation, update or removal (uninstall) fails
+ * all the side effects caused by the process should be disappeared and the system
+ * should be in the state in which it was before the process.<p>
+ *
+ * If a deployment package is being updated the old version is visible through the
+ * <code>DeploymentPackage</code> interface until the update process ends. After the
+ * package is updated the updated version is visible and the old one is not accessible
+ * any more.
+ */
+public interface DeploymentPackage {
+
+ /**
+ * Gives back the state of the deployment package whether it is stale or not).
+ * After uninstall of a deployment package it becomes stale. Any active method calls to a
+ * stale deployment package raise {@link IllegalStateException}.
+ * Active methods are the following:<p>
+ *
+ * <ul>
+ * <li>{@link #getBundle(String)}</li>
+ * <li>{@link #getResourceProcessor(String)}</li>
+ * <li>{@link #uninstall()}</li>
+ * <li>{@link #uninstallForced()}</li>
+ * </ul>
+ *
+ * @return <code>true</code> if the deployment package is stale. <code>false</code>
+ * otherwise
+ * @see #uninstall
+ * @see #uninstallForced
+ */
+ boolean isStale();
+
+ /**
+ * Returns the Deployment Pacakage Symbolic Name of the package.
+ *
+ * @return The name of the deployment package. It cannot be null.
+ */
+ String getName();
+
+ /**
+ * Returns the version of the deployment package.
+ * @return version of the deployment package. It cannot be null.
+ */
+ Version getVersion();
+
+ /**
+ * Returns an array of {@link BundleInfo} objects representing the bundles specified in the manifest
+ * of this deployment package. Its size is equal to the number of the bundles in the deployment package.
+ *
+ * @return array of <code>BundleInfo</code> objects
+ * @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
+ * with "metadata" action
+ */
+ BundleInfo[] getBundleInfos();
+
+ /**
+ * Returns the bundle instance, which is part of this deployment package, that corresponds
+ * to the bundle's symbolic name passed in the <code>symbolicName</code> parameter.
+ * This method will return null for request for bundles that are not part
+ * of this deployment package.<p>
+ *
+ * As this instance is transient (i.e. a bundle can be removed at any time because of the
+ * dynamic nature of the OSGi platform), this method may also return null if the bundle
+ * is part of this deployment package, but is not currently defined to the framework.
+ *
+ * @param symbolicName the symbolic name of the requested bundle
+ * @return The <code>Bundle</code> instance for a given bundle symbolic name.
+ * @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
+ * with "metadata" action
+ * @throws IllegalStateException if the package is stale
+ */
+ Bundle getBundle(String symbolicName);
+
+ /**
+ * Returns an array of strings representing the resources (including bundles) that
+ * are specified in the manifest of this deployment package. A string element of the
+ * array is the same as the value of the "Name" attribute in the manifest. The array
+ * contains the bundles as well.<p>
+ *
+ * E.g. if the "Name" section of the resource (or individual-section as the
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/guide/jar/jar.html#Manifest%20Specification">Manifest Specification</a>
+ * calls it) in the manifest is the following
+
+ * <pre>
+ * Name: foo/readme.txt
+ * Resource-Processor: foo.rp
+ * </pre>
+ *
+ * then the corresponding array element is the "foo/readme.txt" string.<p>
+ *
+ * @return The string array corresponding to resources. It cannot be null but its
+ * length can be zero.
+ * @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
+ * with "metadata" action
+ */
+ String[] getResources();
+
+ /**
+ * At the time of deployment, resource processor service instances are located to
+ * resources contained in a deployment package.<p>
+ *
+ * This call returns a service reference to the corresponding service instance.
+ * If the resource is not part of the deployment package or this call is made during
+ * deployment, prior to the locating of the service to process a given resource, null will
+ * be returned. Services can be updated after a deployment package has been deployed.
+ * In this event, this call will return a reference to the updated service, not to the
+ * instance that was used at deployment time.
+ *
+ * @param resource the name of the resource (it is the same as the value of the "Name"
+ * attribute in the deployment package's manifest)
+ * @return resource processor for the resource or <code>null</cpde>.
+ * @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
+ * with "metadata" action
+ * @throws IllegalStateException if the package is stale
+ */
+ ServiceReference getResourceProcessor(String resource);
+
+ /**
+ * Returns the requested deployment package manifest header from the main section.
+ * Header names are case insensitive. If the header doesn't exist it returns null.<p>
+ *
+ * If the header is localized then the localized value is returned (see OSGi Service Platform,
+ * Mobile Specification Release 4 - Localization related chapters).
+ *
+ * @param header the requested header
+ * @return the value of the header or <code>null</code> if the header does not exist
+ * @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
+ * with "metadata" action
+ */
+ String getHeader(String header);
+
+ /**
+ * Returns the requested deployment package manifest header from the name
+ * section determined by the resource parameter. Header names are case insensitive.
+ * If the resource or the header doesn't exist it returns null.<p>
+ *
+ * If the header is localized then the localized value is returned (see OSGi Service Platform,
+ * Mobile Specification Release 4 - Localization related chapters).
+
+ * @param resource the name of the resource (it is the same as the value of the "Name"
+ * attribute in the deployment package's manifest)
+ * @param header the requested header
+ * @return the value of the header or <code>null</code> if the resource or the header doesn't exist
+ * @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
+ * with "metadata" action
+ */
+ String getResourceHeader(String resource, String header);
+
+ /**
+ * Uninstalls the deployment package. After uninstallation, the deployment package
+ * object becomes stale. This can be checked by using {@link #isStale()},
+ * which will return <code>true</code> when stale.<p>
+ *
+ * @throws DeploymentException if the deployment package could not be successfully uninstalled.
+ * For detailed error code description see {@link DeploymentException}.
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentAdminPermission}("<filter>", "uninstall") permission.
+ * @throws IllegalStateException if the package is stale
+ */
+ void uninstall() throws DeploymentException;
+
+ /**
+ * This method is called to completely uninstall a deployment package, which couldn't be uninstalled
+ * using traditional means ({@link #uninstall()}) due to exceptions. After uninstallation, the deployment
+ * package object becomes stale. This can be checked by using {@link #isStale()},
+ * which will return <code>true</code> when stale.<p>
+ *
+ * The method forces removal of the Deployment Package from the repository maintained by the
+ * Deployment Admin service. This method follows the same steps as {@link #uninstall}. However,
+ * any errors or the absence of Resource Processor services are ignored, they must not cause a roll back.
+ * These errors should be logged.
+ *
+ * @return true if the operation was successful
+ * @throws DeploymentException only {@link DeploymentException#CODE_TIMEOUT} and
+ * {@link DeploymentException#CODE_CANCELLED} can be thrown. For detailed error code description
+ * see {@link DeploymentException}.
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentAdminPermission}("<filter>", "uninstall_forced") permission.
+ * @throws IllegalStateException if the package is stale
+ */
+ boolean uninstallForced() throws DeploymentException;
+
+ /**
+ * Returns a hash code value for the object.
+ *
+ * @return a hash code value for this object
+ */
+ int hashCode();
+
+ /**
+ * Indicates whether some other object is "equal to" this one. Two deployment packages
+ * are equal if they have the same deployment package symbolicname and version.
+ *
+ * @param other the reference object with which to compare.
+ * @return true if this object is the same as the obj argument; false otherwise.
+ */
+ boolean equals(Object other);
+
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java
new file mode 100644
index 0000000..681329e
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java
@@ -0,0 +1,200 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java,v 1.6 2006/06/21 15:16:13 hargrave Exp $
+ *
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.deploymentadmin.spi;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationTargetException;
+import java.security.*;
+
+import org.osgi.service.deploymentadmin.DeploymentAdminPermission;
+
+/**
+ * The <code>DeploymentCustomizerPermission</code> permission gives the right to
+ * Resource Processors to access a bundle's (residing in a Deployment Package) private area.
+ * The bundle and the Resource Processor (customizer) have to be in the same Deployment Package.<p>
+ *
+ * The Resource Processor that has this permission is allowed to access the bundle's
+ * private area by calling the {@link DeploymentSession#getDataFile} method during the session
+ * (see {@link DeploymentSession}). After the session ends the FilePermissions are withdrawn.
+ * The Resource Processor will have <code>FilePermission</code> with "read", "write" and "delete"
+ * actions for the returned {@link java.io.File} that represents the the base directory of the
+ * persistent storage area and for its subdirectories.<p>
+ *
+ * The actions string is converted to lowercase before processing.
+ */
+public class DeploymentCustomizerPermission extends Permission {
+
+ /**
+ *
+ */
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Constant String to the "privatearea" action.
+ */
+ public static final String PRIVATEAREA = "privatearea";
+
+ private static final String delegateProperty = "org.osgi.vendor.deploymentadmin";
+ private static final Constructor constructor;
+ private final Permission delegate;
+ static {
+ constructor = (Constructor) AccessController.doPrivileged(new PrivilegedAction() {
+ public Object run() {
+ String pckg = System.getProperty(delegateProperty);
+ if (null == pckg)
+ throw new RuntimeException("Property '" + delegateProperty + "' is not set");
+ try {
+ Class c = Class.forName(pckg + ".DeploymentCustomizerPermission");
+ return c.getConstructor(new Class[] {String.class, String.class});
+ }
+ catch (Exception e) {
+ throw new RuntimeException(e.getMessage());
+ }
+ }});
+ }
+
+ /**
+ * Creates a new <code>DeploymentCustomizerPermission</code> object for the given
+ * <code>name</code> and <code>action</code>.<p>
+ *
+ * The name parameter is a filter string. This filter has the same syntax as an OSGi filter
+ * but only the "name" attribute is allowed. The value of the attribute
+ * is a Bundle Symbolic Name that represents a bundle. The only allowed action is the
+ * "privatearea" action. E.g.
+ *
+ * <pre>
+ * Permission perm = new DeploymentCustomizerPermission("(name=com.acme.bundle)", "privatearea");
+ * </pre>
+ *
+ * The Resource Processor that has this permission is allowed to access the bundle's
+ * private area by calling the {@link DeploymentSession#getDataFile} method. The
+ * Resource Processor will have <code>FilePermission</code> with "read", "write" and "delete"
+ * actions for the returned {@link java.io.File} and its subdirectories during the deployment
+ * session.
+ *
+ * @param name Bundle Symbolic Name of the target bundle, must not be <code>null</code>.
+ * @param actions action string (only the "privatearea" or "*" action is valid; "*" means all
+ * the possible actions), must not be <code>null</code>.
+ * @throws IllegalArgumentException if the filter is invalid, the list of actions
+ * contains unknown operations or one of the parameters is <code>null</code>
+ */
+ public DeploymentCustomizerPermission(String name, String actions) {
+ super(name);
+ try {
+ try {
+ delegate = (Permission) constructor.newInstance(new Object[] {name, actions});
+ }
+ catch (InvocationTargetException e) {
+ throw e.getTargetException();
+ }
+ }
+ catch (Error e) {
+ throw e;
+ }
+ catch (RuntimeException e) {
+ throw e;
+ }
+ catch (Throwable e) {
+ throw new RuntimeException(e.toString());
+ }
+ }
+
+ /**
+ * Checks two DeploymentCustomizerPermission objects for equality.
+ * Two permission objects are equal if: <p>
+ *
+ * <ul>
+ * <li>their target filters are equal (semantically and not character by
+ * character) and</li>
+ * <li>their actions are the same</li>
+ * </ul>
+ *
+ * @param obj the reference object with which to compare.
+ * @return true if the two objects are equal.
+ * @see java.lang.Object#equals(java.lang.Object)
+ */
+ public boolean equals(Object obj) {
+ if (obj == this)
+ return true;
+ if (!(obj instanceof DeploymentCustomizerPermission))
+ return false;
+ DeploymentCustomizerPermission dcp = (DeploymentCustomizerPermission) obj;
+ return delegate.equals(dcp.delegate);
+ }
+
+ /**
+ * Returns hash code for this permission object.
+ *
+ * @return Hash code for this permission object.
+ * @see java.lang.Object#hashCode()
+ */
+ public int hashCode() {
+ return delegate.hashCode();
+ }
+
+ /**
+ * Returns the String representation of the action list.
+ *
+ * @return Action list of this permission instance. It is always "privatearea".
+ * @see java.security.Permission#getActions()
+ */
+ public String getActions() {
+ return delegate.getActions();
+ }
+
+ /**
+ * Checks if this DeploymentCustomizerPermission would imply the parameter permission.
+ * This permission implies another DeploymentCustomizerPermission permission if:
+ *
+ * <ul>
+ * <li>both of them has the "privatearea" action (other actions are not allowed) and</li>
+ * <li>their filters (only name attribute is allowed in the filters) match similarly to
+ * {@link DeploymentAdminPermission}.</li>
+ * </ul>
+ *
+ * The value of the name attribute means Bundle Symbolic Name and not Deployment Package
+ * Symbolic Name here!<p>
+ *
+ * @param permission Permission to check.
+ * @return true if this DeploymentCustomizerPermission object implies the
+ * specified permission.
+ * @see java.security.Permission#implies(java.security.Permission)
+ */
+ public boolean implies(Permission permission) {
+ if (!(permission instanceof DeploymentCustomizerPermission))
+ return false;
+
+ DeploymentCustomizerPermission dcp = (DeploymentCustomizerPermission) permission;
+
+ return delegate.implies(dcp.delegate);
+ }
+
+ /**
+ * Returns a new PermissionCollection object for storing DeploymentCustomizerPermission
+ * objects.
+ *
+ * @return The new PermissionCollection.
+ * @see java.security.Permission#newPermissionCollection()
+ */
+ public PermissionCollection newPermissionCollection() {
+ return delegate.newPermissionCollection();
+ }
+
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentSession.java b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentSession.java
new file mode 100644
index 0000000..87a5b1f
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentSession.java
@@ -0,0 +1,96 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/spi/DeploymentSession.java,v 1.6 2006/06/16 16:31:39 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.deploymentadmin.spi;
+
+import org.osgi.service.deploymentadmin.DeploymentPackage;
+
+/**
+ * The session interface represents a currently running deployment session
+ * (install/update/uninstall).<p>
+ *
+ * When a deployment package is installed the target package, when uninstalled the
+ * source package is an empty deployment package. The empty deployment package is a virtual
+ * entity it doesn't appear for the outside world. It is only visible on the
+ * DeploymentSession interface used by Resource Processors. Although the empty package
+ * is only visible for Resource Processors it has the following characteristics:<p>
+ *
+ * <ul>
+ * <li>has version 0.0.0</li>
+ * <li>its name is an empty string</li>
+ * <li>it is stale</li>
+ * <li>it has no bundles
+ * (see {@link DeploymentPackage#getBundle(String)})</li>
+ * <li>it has no resources
+ * (see {@link DeploymentPackage#getResources()})</li>
+ * <li>it has no headers except <br/>
+ * <code>DeploymentPackage-SymbolicName</code> and <br/>
+ * <code>DeploymentPackage-Version</code> <br/>
+ * (see {@link DeploymentPackage#getHeader(String)})</li>
+ * <li>it has no resource headers (see
+ * {@link DeploymentPackage#getResourceHeader(String, String)})</li>
+ * <li>{@link DeploymentPackage#uninstall()} throws
+ * {@link java.lang.IllegalStateException}</li>
+ * <li>{@link DeploymentPackage#uninstallForced()} throws
+ * {@link java.lang.IllegalStateException}</li>
+ * </ul>
+ *
+ */
+public interface DeploymentSession {
+
+ /**
+ * If the deployment action is an update or an uninstall, this call returns
+ * the <code>DeploymentPackage</code> instance for the installed deployment package. If the
+ * deployment action is an install, this call returns the empty deploymet package (see
+ * {@link DeploymentPackage}).
+ *
+ * @return the target deployment package
+ * @see DeploymentPackage
+ */
+ DeploymentPackage getTargetDeploymentPackage();
+
+ /**
+ * If the deployment action is an install or an update, this call returns
+ * the <code>DeploymentPackage</code> instance that corresponds to the deployment package
+ * being streamed in for this session. If the deployment action is an uninstall, this call
+ * returns the empty deploymet package (see {@link DeploymentPackage}).
+ *
+ * @return the source deployment package
+ * @see DeploymentPackage
+ */
+ DeploymentPackage getSourceDeploymentPackage();
+
+ /**
+ * Returns the private data area of the specified bundle. The bundle must be part of
+ * either the source or the target deployment packages. The permission set the caller
+ * resource processor needs to manipulate the private area of the bundle is set by the
+ * Deployment Admin on the fly when this method is called. The permissions remain available
+ * during the deployment action only.<p>
+ *
+ * The bundle and the caller Resource Processor have to be in the same Deployment Package.
+ *
+ * @param bundle the bundle the private area belongs to
+ * @return file representing the private area of the bundle. It cannot be null.
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentCustomizerPermission}("<filter>", "privatearea") permission.
+ * @see DeploymentPackage
+ * @see DeploymentCustomizerPermission
+ */
+ java.io.File getDataFile(org.osgi.framework.Bundle bundle);
+
+}
+
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java
new file mode 100644
index 0000000..ec5a5fd
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java
@@ -0,0 +1,139 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java,v 1.6 2006/07/11 13:19:02 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.deploymentadmin.spi;
+
+import java.io.InputStream;
+
+/**
+ * ResourceProcessor interface is implemented by processors handling resource files
+ * in deployment packages. Resource Processors expose their services as standard OSGi services.
+ * Bundles exporting the service may arrive in the deployment package (customizers) or may be
+ * preregistered (they are installed prevoiusly). Resource processors has to define the
+ * <code>service.pid</code> standard OSGi service property which should be a unique string.<p>
+ *
+ * The order of the method calls on a particular Resource Processor in case of install/update
+ * session is the following:<p>
+ *
+ * <ol>
+ * <li>{@link #begin(DeploymentSession)}</li>
+ * <li>{@link #process(String, InputStream)} calls till there are resources to process
+ * or {@link #rollback()} and the further steps are ignored</li>
+ * <li>{@link #dropped(String)} calls till there are resources to drop
+ * <li>{@link #prepare()}</li>
+ * <li>{@link #commit()} or {@link #rollback()}</li>
+ * </ol>
+ *
+ * The order of the method calls on a particular Resource Processor in case of uninstall
+ * session is the following:<p>
+ *
+ * <ol>
+ * <li>{@link #begin(DeploymentSession)}</li>
+ * <li>{@link #dropAllResources()} or {@link #rollback()} and the further steps are ignored</li>
+ * <li>{@link #prepare()}</li>
+ * <li>{@link #commit()} or {@link #rollback()}</li>
+ * </ol>
+ */
+public interface ResourceProcessor {
+
+ /**
+ * Called when the Deployment Admin starts a new operation on the given deployment package,
+ * and the resource processor is associated a resource within the package. Only one
+ * deployment package can be processed at a time.
+ *
+ * @param session object that represents the current session to the resource processor
+ * @see DeploymentSession
+ */
+ void begin(DeploymentSession session);
+
+ /**
+ * Called when a resource is encountered in the deployment package for which this resource
+ * processor has been selected to handle the processing of that resource.
+ *
+ * @param name The name of the resource relative to the deployment package root directory.
+ * @param stream The stream for the resource.
+ * @throws ResourceProcessorException if the resource cannot be processed. Only
+ * {@link ResourceProcessorException#CODE_RESOURCE_SHARING_VIOLATION} and
+ * {@link ResourceProcessorException#CODE_OTHER_ERROR} error codes are allowed.
+ */
+ void process(String name, InputStream stream) throws ResourceProcessorException;
+
+ /**
+ * Called when a resource, associated with a particular resource processor, had belonged to
+ * an earlier version of a deployment package but is not present in the current version of
+ * the deployment package. This provides an opportunity for the processor to cleanup any
+ * memory and persistent data being maintained for the particular resource.
+ * This method will only be called during "update" deployment sessions.
+ *
+ * @param resource the name of the resource to drop (it is the same as the value of the
+ * "Name" attribute in the deployment package's manifest)
+ * @throws ResourceProcessorException if the resource is not allowed to be dropped. Only the
+ * {@link ResourceProcessorException#CODE_OTHER_ERROR} error code is allowed
+ */
+ void dropped(String resource) throws ResourceProcessorException;
+
+ /**
+ * This method is called during an "uninstall" deployment session.
+ * This method will be called on all resource processors that are associated with resources
+ * in the deployment package being uninstalled. This provides an opportunity for the processor
+ * to cleanup any memory and persistent data being maintained for the deployment package.
+ *
+ * @throws ResourceProcessorException if all resources could not be dropped. Only the
+ * {@link ResourceProcessorException#CODE_OTHER_ERROR} is allowed.
+ */
+ void dropAllResources() throws ResourceProcessorException;
+
+ /**
+ * This method is called on the Resource Processor immediately before calling the
+ * <code>commit</code> method. The Resource Processor has to check whether it is able
+ * to commit the operations since the last <code>begin</code> method call. If it determines
+ * that it is not able to commit the changes, it has to raise a
+ * <code>ResourceProcessorException</code> with the {@link ResourceProcessorException#CODE_PREPARE}
+ * error code.
+ *
+ * @throws ResourceProcessorException if the resource processor is able to determine it is
+ * not able to commit. Only the {@link ResourceProcessorException#CODE_PREPARE} error
+ * code is allowed.
+ */
+ void prepare() throws ResourceProcessorException;
+
+ /**
+ * Called when the processing of the current deployment package is finished.
+ * This method is called if the processing of the current deployment package was successful,
+ * and the changes must be made permanent.
+ */
+ void commit();
+
+
+ /**
+ * Called when the processing of the current deployment package is finished.
+ * This method is called if the processing of the current deployment package was unsuccessful,
+ * and the changes made during the processing of the deployment package should be removed.
+ */
+ void rollback();
+
+ /**
+ * Processing of a resource passed to the resource processor may take long.
+ * The <code>cancel()</code> method notifies the resource processor that it should
+ * interrupt the processing of the current resource. This method is called by the
+ * <code>DeploymentAdmin</code> implementation after the
+ * <code>DeploymentAdmin.cancel()</code> method is called.
+ */
+ void cancel();
+
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java
new file mode 100644
index 0000000..eb9c3dc
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java
@@ -0,0 +1,123 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java,v 1.7 2006/07/12 21:22:10 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.deploymentadmin.spi;
+
+import java.io.InputStream;
+
+/**
+ * Checked exception received when something fails during a call to a Resource
+ * Processor. A <code>ResourceProcessorException</code> always contains an error
+ * code (one of the constants specified in this class), and may optionally contain
+ * the textual description of the error condition and a nested cause exception.
+ */
+public class ResourceProcessorException extends Exception {
+
+ /**
+ *
+ */
+ private static final long serialVersionUID = 9135007015668223386L;
+
+ /**
+ * Resource Processors are allowed to raise an exception with this error code
+ * to indicate that the processor is not able to commit the operations it made
+ * since the last call of {@link ResourceProcessor#begin(DeploymentSession)} method.<p>
+ *
+ * Only the {@link ResourceProcessor#prepare()} method is allowed to throw exception
+ * with this error code.
+ */
+ public static final int CODE_PREPARE = 1;
+
+ /**
+ * An artifact of any resource already exists.<p>
+ *
+ * Only the {@link ResourceProcessor#process(String, InputStream)} method
+ * is allowed to throw exception with this error code.
+ */
+ public static final int CODE_RESOURCE_SHARING_VIOLATION = 461;
+
+ /**
+ * Other error condition.<p>
+ *
+ * All Resource Processor methods which throw <code>ResourceProcessorException</code>
+ * is allowed throw an exception with this erro code if the error condition cannot be
+ * categorized.
+ */
+ public static final int CODE_OTHER_ERROR = 463;
+
+ private final int code;
+ private final String message;
+ private final Throwable cause;
+
+ /**
+ * Create an instance of the exception.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ * @param message Message associated with the exception
+ * @param cause the originating exception
+ */
+ public ResourceProcessorException(int code, String message, Throwable cause) {
+ this.code = code;
+ this.message = message;
+ this.cause = cause;
+ }
+
+ /**
+ * Create an instance of the exception. Cause exception is implicitly set to
+ * null.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ * @param message Message associated with the exception
+ */
+ public ResourceProcessorException(int code, String message) {
+ this(code, message, null);
+ }
+
+ /**
+ * Create an instance of the exception. Cause exception and message are
+ * implicitly set to null.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ */
+ public ResourceProcessorException(int code) {
+ this(code, null, null);
+ }
+
+ /**
+ * @return Returns the cause.
+ */
+ public Throwable getCause() {
+ return cause;
+ }
+
+ /**
+ * @return Returns the code.
+ */
+ public int getCode() {
+ return code;
+ }
+
+ /**
+ * @return Returns the message.
+ */
+ public String getMessage() {
+ return message;
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitorAdmin.java b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitorAdmin.java
new file mode 100644
index 0000000..c9377c8
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitorAdmin.java
@@ -0,0 +1,359 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/MonitorAdmin.java,v 1.25 2006/06/16 16:31:25 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.monitor;
+
+/**
+ * The <code>MonitorAdmin</code> service is a singleton service that handles
+ * <code>StatusVariable</code> query requests and measurement job control
+ * requests.
+ * <p>
+ * Note that an alternative but not recommended way of obtaining
+ * <code>StatusVariable</code>s is that applications having the required
+ * <code>ServicePermissions</code> can query the list of
+ * <code>Monitorable</code> services from the service registry and then query
+ * the list of <code>StatusVariable</code> names from the
+ * <code>Monitorable</code> services. This way all services which publish
+ * <code>StatusVariable</code>s will be returned regardless of whether they
+ * do or do not hold the necessary <code>MonitorPermission</code> for
+ * publishing <code>StatusVariable</code>s. By using the
+ * <code>MonitorAdmin</code> to obtain the <code>StatusVariable</code>s it
+ * is guaranteed that only those <code>Monitorable</code> services will be
+ * accessed who are authorized to publish <code>StatusVariable</code>s. It is
+ * the responsibility of the <code>MonitorAdmin</code> implementation to check
+ * the required permissions and show only those variables which pass this check.
+ * <p>
+ * The events posted by <code>MonitorAdmin</code> contain the following
+ * properties:
+ * <ul>
+ * <li><code>mon.monitorable.pid</code>: The identifier of the
+ * <code>Monitorable</code>
+ * <li><code>mon.statusvariable.name</code>: The identifier of the
+ * <code>StatusVariable</code> within the given <code>Monitorable</code>
+ * <li><code>mon.statusvariable.value</code>: The value of the
+ * <code>StatusVariable</code>, represented as a <code>String</code>
+ * <li><code>mon.listener.id</code>: The identifier of the initiator of the
+ * monitoring job (only present if the event was generated due to a monitoring
+ * job)
+ * </ul>
+ * <p>
+ * Most of the methods require either a Monitorable ID or a Status Variable path
+ * parameter, the latter in [Monitorable_ID]/[StatusVariable_ID] format. These
+ * parameters must not be <code>null</code>, and the IDs they contain must
+ * conform to their respective definitions in {@link Monitorable} and
+ * {@link StatusVariable}. If any of the restrictions are violated, the method
+ * must throw an <code>IllegalArgumentException</code>.
+ */
+public interface MonitorAdmin {
+
+ /**
+ * Returns a <code>StatusVariable</code> addressed by its full path.
+ * The entity which queries a <code>StatusVariable</code> needs to hold
+ * <code>MonitorPermission</code> for the given target with the
+ * <code>read</code> action present.
+ *
+ * @param path the full path of the <code>StatusVariable</code> in
+ * [Monitorable_ID]/[StatusVariable_ID] format
+ * @return the <code>StatusVariable</code> object
+ * @throws java.lang.IllegalArgumentException if <code>path</code> is
+ * <code>null</code> or otherwise invalid, or points to a
+ * non-existing <code>StatusVariable</code>
+ * @throws java.lang.SecurityException if the caller does not hold a
+ * <code>MonitorPermission</code> for the
+ * <code>StatusVariable</code> specified by <code>path</code>
+ * with the <code>read</code> action present
+ */
+ public StatusVariable getStatusVariable(String path)
+ throws IllegalArgumentException, SecurityException;
+
+ /**
+ * Returns the names of the <code>Monitorable</code> services that are
+ * currently registered. The <code>Monitorable</code> instances are not
+ * accessible through the <code>MonitorAdmin</code>, so that requests to
+ * individual status variables can be filtered with respect to the
+ * publishing rights of the <code>Monitorable</code> and the reading
+ * rights of the caller.
+ * <p>
+ * The returned array contains the names in alphabetical order. It cannot be
+ * <code>null</code>, an empty array is returned if no
+ * <code>Monitorable</code> services are registered.
+ *
+ * @return the array of <code>Monitorable</code> names
+ */
+ public String[] getMonitorableNames();
+
+ /**
+ * Returns the <code>StatusVariable</code> objects published by a
+ * <code>Monitorable</code> instance. The <code>StatusVariables</code>
+ * will hold the values taken at the time of this method call. Only those
+ * status variables are returned where the following two conditions are met:
+ * <ul>
+ * <li>the specified <code>Monitorable</code> holds a
+ * <code>MonitorPermission</code> for the status variable with the
+ * <code>publish</code> action present
+ * <li>the caller holds a <code>MonitorPermission</code> for the status
+ * variable with the <code>read</code> action present
+ * </ul>
+ * All other status variables are silently ignored, they are omitted from
+ * the result.
+ * <p>
+ * The elements in the returned array are in no particular order. The return
+ * value cannot be <code>null</code>, an empty array is returned if no
+ * (authorized and readable) Status Variables are provided by the given
+ * <code>Monitorable</code>.
+ *
+ * @param monitorableId the identifier of a <code>Monitorable</code>
+ * instance
+ * @return a list of <code>StatusVariable</code> objects published
+ * by the specified <code>Monitorable</code>
+ * @throws java.lang.IllegalArgumentException if <code>monitorableId</code>
+ * is <code>null</code> or otherwise invalid, or points to a
+ * non-existing <code>Monitorable</code>
+ */
+ public StatusVariable[] getStatusVariables(String monitorableId)
+ throws IllegalArgumentException;
+
+ /**
+ * Returns the list of <code>StatusVariable</code> names published by a
+ * <code>Monitorable</code> instance. Only those status variables are
+ * listed where the following two conditions are met:
+ * <ul>
+ * <li>the specified <code>Monitorable</code> holds a
+ * <code>MonitorPermission</code> for the status variable with the
+ * <code>publish</code> action present
+ * <li>the caller holds a <code>MonitorPermission</code> for
+ * the status variable with the <code>read</code> action present
+ * </ul>
+ * All other status variables are silently ignored, their names are omitted
+ * from the list.
+ * <p>
+ * The returned array does not contain duplicates, and the elements are in
+ * alphabetical order. It cannot be <code>null</code>, an empty array is
+ * returned if no (authorized and readable) Status Variables are provided
+ * by the given <code>Monitorable</code>.
+ *
+ * @param monitorableId the identifier of a <code>Monitorable</code>
+ * instance
+ * @return a list of <code>StatusVariable</code> objects names
+ * published by the specified <code>Monitorable</code>
+ * @throws java.lang.IllegalArgumentException if <code>monitorableId</code>
+ * is <code>null</code> or otherwise invalid, or points to a
+ * non-existing <code>Monitorable</code>
+ */
+ public String[] getStatusVariableNames(String monitorableId)
+ throws IllegalArgumentException;
+
+ /**
+ * Switches event sending on or off for the specified
+ * <code>StatusVariable</code>s. When the <code>MonitorAdmin</code> is
+ * notified about a <code>StatusVariable</code> being updated it sends an
+ * event unless this feature is switched off. Note that events within a
+ * monitoring job can not be switched off. The event sending state of the
+ * <code>StatusVariables</code> must not be persistently stored. When a
+ * <code>StatusVariable</code> is registered for the first time in a
+ * framework session, its event sending state is set to ON by default.
+ * <p>
+ * Usage of the "*" wildcard is allowed in the path argument of this method
+ * as a convenience feature. The wildcard can be used in either or both path
+ * fragments, but only at the end of the fragments. The semantics of the
+ * wildcard is that it stands for any matching <code>StatusVariable</code>
+ * at the time of the method call, it does not affect the event sending
+ * status of <code>StatusVariable</code>s which are not yet registered. As
+ * an example, when the <code>switchEvents("MyMonitorable/*", false)</code>
+ * method is executed, event sending from all <code>StatusVariables</code>
+ * of the MyMonitorable service are switched off. However, if the
+ * MyMonitorable service starts to publish a new <code>StatusVariable</code>
+ * later, it's event sending status is on by default.
+ *
+ * @param path the identifier of the <code>StatusVariable</code>(s) in
+ * [Monitorable_id]/[StatusVariable_id] format, possibly with the
+ * "*" wildcard at the end of either path fragment
+ * @param on <code>false</code> if event sending should be switched off,
+ * <code>true</code> if it should be switched on for the given path
+ * @throws java.lang.SecurityException if the caller does not hold
+ * <code>MonitorPermission</code> with the
+ * <code>switchevents</code> action or if there is any
+ * <code>StatusVariable</code> in the <code>path</code> field for
+ * which it is not allowed to switch event sending on or off as per
+ * the target field of the permission
+ * @throws java.lang.IllegalArgumentException if <code>path</code> is
+ * <code>null</code> or otherwise invalid, or points to a
+ * non-existing <code>StatusVariable</code>
+ */
+ public void switchEvents(String path, boolean on)
+ throws IllegalArgumentException, SecurityException;
+
+ /**
+ * Issues a request to reset a given <code>StatusVariable</code>.
+ * Depending on the semantics of the <code>StatusVariable</code> this call
+ * may or may not succeed: it makes sense to reset a counter to its starting
+ * value, but e.g. a <code>StatusVariable</code> of type String might not
+ * have a meaningful default value. Note that for numeric
+ * <code>StatusVariable</code>s the starting value may not necessarily be
+ * 0. Resetting a <code>StatusVariable</code> triggers a monitor event if
+ * the <code>StatusVariable</code> supports update notifications.
+ * <p>
+ * The entity that wants to reset the <code>StatusVariable</code> needs to
+ * hold <code>MonitorPermission</code> with the <code>reset</code>
+ * action present. The target field of the permission must match the
+ * <code>StatusVariable</code> name to be reset.
+ *
+ * @param path the identifier of the <code>StatusVariable</code> in
+ * [Monitorable_id]/[StatusVariable_id] format
+ * @return <code>true</code> if the <code>Monitorable</code> could
+ * successfully reset the given <code>StatusVariable</code>,
+ * <code>false</code> otherwise
+ * @throws java.lang.IllegalArgumentException if <code>path</code> is
+ * <code>null</code> or otherwise invalid, or points to a
+ * non-existing <code>StatusVariable</code>
+ * @throws java.lang.SecurityException if the caller does not hold
+ * <code>MonitorPermission</code> with the <code>reset</code>
+ * action or if the specified <code>StatusVariable</code> is not
+ * allowed to be reset as per the target field of the permission
+ */
+ public boolean resetStatusVariable(String path)
+ throws IllegalArgumentException, SecurityException;
+
+ /**
+ * Returns a human readable description of the given
+ * <code>StatusVariable</code>. The <code>null</code> value may be returned
+ * if there is no description for the given <code>StatusVariable</code>.
+ * <p>
+ * The entity that queries a <code>StatusVariable</code> needs to hold
+ * <code>MonitorPermission</code> for the given target with the
+ * <code>read</code> action present.
+ *
+ * @param path the full path of the <code>StatusVariable</code> in
+ * [Monitorable_ID]/[StatusVariable_ID] format
+ * @return the human readable description of this
+ * <code>StatusVariable</code> or <code>null</code> if it is not
+ * set
+ * @throws java.lang.IllegalArgumentException if <code>path</code> is
+ * <code>null</code> or otherwise invalid, or points to a
+ * non-existing <code>StatusVariable</code>
+ * @throws java.lang.SecurityException if the caller does not hold a
+ * <code>MonitorPermission</code> for the
+ * <code>StatusVariable</code> specified by <code>path</code>
+ * with the <code>read</code> action present
+ */
+ public String getDescription(String path)
+ throws IllegalArgumentException, SecurityException;
+
+ /**
+ * Starts a time based <code>MonitoringJob</code> with the parameters
+ * provided. Monitoring events will be sent according to the specified
+ * schedule. All specified <code>StatusVariable</code>s must exist when the
+ * job is started. The initiator string is used in the
+ * <code>mon.listener.id</code> field of all events triggered by the job,
+ * to allow filtering the events based on the initiator.
+ * <p>
+ * The <code>schedule</code> parameter specifies the time in seconds
+ * between two measurements, it must be greater than 0. The first
+ * measurement will be taken when the timer expires for the first time, not
+ * when this method is called.
+ * <p>
+ * The <code>count</code> parameter defines the number of measurements to be
+ * taken, and must either be a positive integer, or 0 if the measurement is
+ * to run until explicitely stopped.
+ * <p>
+ * The entity which initiates a <code>MonitoringJob</code> needs to hold
+ * <code>MonitorPermission</code> for all the specified target
+ * <code>StatusVariable</code>s with the <code>startjob</code> action
+ * present. If the permission's action string specifies a minimal sampling
+ * interval then the <code>schedule</code> parameter should be at least as
+ * great as the value in the action string.
+ *
+ * @param initiator the identifier of the entity that initiated the job
+ * @param statusVariables the list of <code>StatusVariable</code>s to be
+ * monitored, with each <code>StatusVariable</code> name given in
+ * [Monitorable_PID]/[StatusVariable_ID] format
+ * @param schedule the time in seconds between two measurements
+ * @param count the number of measurements to be taken, or 0 for the
+ * measurement to run until explicitely stopped
+ * @return the successfully started job object, cannot be <code>null</code>
+ * @throws java.lang.IllegalArgumentException if the list of
+ * <code>StatusVariable</code> names contains an invalid or
+ * non-existing <code>StatusVariable</code>; if
+ * <code>initiator</code> is <code>null</code> or empty; or if the
+ * <code>schedule</code> or <code>count</code> parameters are
+ * invalid
+ * @throws java.lang.SecurityException if the caller does not hold
+ * <code>MonitorPermission</code> for all the specified
+ * <code>StatusVariable</code>s, with the <code>startjob</code>
+ * action present, or if the permission does not allow starting the
+ * job with the given frequency
+ */
+ public MonitoringJob startScheduledJob(String initiator,
+ String[] statusVariables, int schedule, int count)
+ throws IllegalArgumentException, SecurityException;
+
+ /**
+ * Starts a change based <code>MonitoringJob</code> with the parameters
+ * provided. Monitoring events will be sent when the
+ * <code>StatusVariable</code>s of this job are updated. All specified
+ * <code>StatusVariable</code>s must exist when the job is started, and
+ * all must support update notifications. The initiator string is used in
+ * the <code>mon.listener.id</code> field of all events triggered by the
+ * job, to allow filtering the events based on the initiator.
+ * <p>
+ * The <code>count</code> parameter specifies the number of changes that
+ * must happen to a <code>StatusVariable</code> before a new notification is
+ * sent, this must be a positive integer.
+ * <p>
+ * The entity which initiates a <code>MonitoringJob</code> needs to hold
+ * <code>MonitorPermission</code> for all the specified target
+ * <code>StatusVariable</code>s with the <code>startjob</code> action
+ * present.
+ *
+ * @param initiator the identifier of the entity that initiated the job
+ * @param statusVariables the list of <code>StatusVariable</code>s to be
+ * monitored, with each <code>StatusVariable</code> name given in
+ * [Monitorable_PID]/[StatusVariable_ID] format
+ * @param count the number of changes that must happen to a
+ * <code>StatusVariable</code> before a new notification is sent
+ * @return the successfully started job object, cannot be <code>null</code>
+ * @throws java.lang.IllegalArgumentException if the list of
+ * <code>StatusVariable</code> names contains an invalid or
+ * non-existing <code>StatusVariable</code>, or one that does not
+ * support notifications; if the <code>initiator</code> is
+ * <code>null</code> or empty; or if <code>count</code> is invalid
+ * @throws java.lang.SecurityException if the caller does not hold
+ * <code>MonitorPermission</code> for all the specified
+ * <code>StatusVariable</code>s, with the <code>startjob</code>
+ * action present
+ */
+ public MonitoringJob startJob(String initiator, String[] statusVariables,
+ int count) throws IllegalArgumentException, SecurityException;
+
+ /**
+ * Returns the list of currently running <code>MonitoringJob</code>s.
+ * Jobs are only visible to callers that have the necessary permissions: to
+ * receive a Monitoring Job in the returned list, the caller must hold all
+ * permissions required for starting the job. This means that if the caller
+ * does not have <code>MonitorPermission</code> with the proper
+ * <code>startjob</code> action for all the Status Variables monitored by a
+ * job, then that job will be silently omitted from the results.
+ * <p>
+ * The returned array cannot be <code>null</code>, an empty array is
+ * returned if there are no running jobs visible to the caller at the time
+ * of the call.
+ *
+ * @return the list of running jobs visible to the caller
+ */
+ public MonitoringJob[] getRunningJobs();
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitorListener.java b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitorListener.java
new file mode 100644
index 0000000..44fa845
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitorListener.java
@@ -0,0 +1,42 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/MonitorListener.java,v 1.11 2006/06/16 16:31:25 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.monitor;
+
+/**
+ * The <code>MonitorListener</code> is used by <code>Monitorable</code>
+ * services to send notifications when a <code>StatusVariable</code> value is
+ * changed. The <code>MonitorListener</code> should register itself as a
+ * service at the OSGi Service Registry. This interface must (only) be
+ * implemented by the Monitor Admin component.
+ */
+public interface MonitorListener {
+ /**
+ * Callback for notification of a <code>StatusVariable</code> change.
+ *
+ * @param monitorableId the identifier of the <code>Monitorable</code>
+ * instance reporting the change
+ * @param statusVariable the <code>StatusVariable</code> that has changed
+ * @throws java.lang.IllegalArgumentException if the specified monitorable
+ * ID is invalid (<code>null</code>, empty, or contains illegal
+ * characters) or points to a non-existing <code>Monitorable</code>,
+ * or if <code>statusVariable</code> is <code>null</code>
+ */
+ public void updated(String monitorableId, StatusVariable statusVariable)
+ throws IllegalArgumentException;
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitorPermission.java b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitorPermission.java
new file mode 100644
index 0000000..b0ca12d
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitorPermission.java
@@ -0,0 +1,366 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/MonitorPermission.java,v 1.17 2006/06/21 15:17:16 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 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.monitor;
+
+import java.io.UnsupportedEncodingException;
+import java.security.Permission;
+import java.util.StringTokenizer;
+
+/**
+ * Indicates the callers authority to publish, read or reset
+ * <code>StatusVariable</code>s, to switch event sending on or off or to
+ * start monitoring jobs. The target of the permission is the identifier of the
+ * <code>StatusVariable</code>, the action can be <code>read</code>,
+ * <code>publish</code>, <code>reset</code>, <code>startjob</code>,
+ * <code>switchevents</code>, or the combination of these separated by
+ * commas. Action names are interpreted case-insensitively, but the canonical
+ * action string returned by {@link #getActions} uses the forms defined by the
+ * action constants.
+ * <p>
+ * If the wildcard <code>*</code> appears in the actions field, all legal
+ * monitoring commands are allowed on the designated target(s) by the owner of
+ * the permission.
+ */
+public class MonitorPermission extends Permission {
+
+ /**
+ *
+ */
+ private static final long serialVersionUID = -9084425194463274314L;
+
+ /**
+ * Holders of <code>MonitorPermission</code> with the <code>read</code>
+ * action present are allowed to read the value of the
+ * <code>StatusVariable</code>s specified in the permission's target field.
+ */
+ public static final String READ = "read";
+
+ /**
+ * Holders of <code>MonitorPermission</code> with the <code>reset</code>
+ * action present are allowed to reset the value of the
+ * <code>StatusVariable</code>s specified in the permission's target field.
+ */
+ public static final String RESET = "reset";
+
+ /**
+ * Holders of <code>MonitorPermission</code> with the <code>publish</code>
+ * action present are <code>Monitorable</code> services that are allowed
+ * to publish the <code>StatusVariable</code>s specified in the
+ * permission's target field. Note, that this permission cannot be enforced
+ * when a <code>Monitorable</code> registers to the framework, because the
+ * Service Registry does not know about this permission. Instead, any
+ * <code>StatusVariable</code>s published by a <code>Monitorable</code>
+ * without the corresponding <code>publish</code> permission are silently
+ * ignored by <code>MonitorAdmin</code>, and are therefore invisible to the
+ * users of the monitoring service.
+ */
+ public static final String PUBLISH = "publish";
+
+ /**
+ * Holders of <code>MonitorPermission</code> with the <code>startjob</code>
+ * action present are allowed to initiate monitoring jobs involving the
+ * <code>StatusVariable</code>s specified in the permission's target field.
+ * <p>
+ * A minimal sampling interval can be optionally defined in the following
+ * form: <code>startjob:n</code>. This allows the holder of the permission
+ * to initiate time based jobs with a measurement interval of at least
+ * <code>n</code> seconds. If <code>n</code> is not specified or 0 then the
+ * holder of this permission is allowed to start monitoring jobs specifying
+ * any frequency.
+ */
+ public static final String STARTJOB = "startjob";
+
+ /**
+ * Holders of <code>MonitorPermission</code> with the
+ * <code>switchevents</code> action present are allowed to switch event
+ * sending on or off for the value of the <code>StatusVariable</code>s
+ * specified in the permission's target field.
+ */
+ public static final String SWITCHEVENTS = "switchevents";
+
+ private static final int READ_FLAG = 0x1;
+ private static final int RESET_FLAG = 0x2;
+ private static final int PUBLISH_FLAG = 0x4;
+ private static final int STARTJOB_FLAG = 0x8;
+ private static final int SWITCHEVENTS_FLAG = 0x10;
+
+ private static final int ALL_FLAGS = READ_FLAG | RESET_FLAG |
+ PUBLISH_FLAG | STARTJOB_FLAG | SWITCHEVENTS_FLAG;
+
+ private String monId;
+ private String varId;
+ private boolean prefixMonId;
+ private boolean prefixVarId;
+ private int mask;
+ private int minJobInterval;
+
+ /**
+ * Create a <code>MonitorPermission</code> object, specifying the target
+ * and actions.
+ * <p>
+ * The <code>statusVariable</code> parameter is the target of the
+ * permission, defining one or more status variable names to which the
+ * specified actions apply. Multiple status variable names can be selected
+ * by using the wildcard <code>*</code> in the target string. The wildcard
+ * is allowed in both fragments, but only at the end of the fragments.
+ * <p>
+ * For example, the following targets are valid:
+ * <code>com.mycomp.myapp/queue_length</code>,
+ * <code>com.mycomp.myapp/*</code>, <code>com.mycomp.*/*</code>,
+ * <code>*/*</code>, <code>*/queue_length</code>,
+ * <code>*/queue*</code>.
+ * <p>
+ * The following targets are invalid:
+ * <code>*.myapp/queue_length</code>, <code>com.*.myapp/*</code>,
+ * <code>*</code>.
+ * <p>
+ * The <code>actions</code> parameter specifies the allowed action(s):
+ * <code>read</code>, <code>publish</code>, <code>startjob</code>,
+ * <code>reset</code>, <code>switchevents</code>, or the combination of
+ * these separated by commas. String constants are defined in this class for
+ * each valid action. Passing <code>"*"</code> as the action
+ * string is equivalent to listing all actions.
+ *
+ * @param statusVariable the identifier of the <code>StatusVariable</code>
+ * in [Monitorable_id]/[StatusVariable_id] format
+ * @param actions the list of allowed actions separated by commas, or
+ * <code>*</code> for all actions
+ * @throws java.lang.IllegalArgumentException if either parameter is
+ * <code>null</code>, or invalid with regard to the constraints
+ * defined above and in the documentation of the used actions
+ */
+ public MonitorPermission(String statusVariable, String actions)
+ throws IllegalArgumentException {
+ super(statusVariable);
+
+ if(statusVariable == null)
+ throw new IllegalArgumentException(
+ "Invalid StatusVariable path 'null'.");
+
+ if(actions == null)
+ throw new IllegalArgumentException(
+ "Invalid actions string 'null'.");
+
+ int sep = statusVariable.indexOf('/');
+ int len = statusVariable.length();
+
+ if (sep == -1)
+ throw new IllegalArgumentException(
+ "Invalid StatusVariable path: should contain '/' separator.");
+ if (sep == 0 || sep == statusVariable.length() - 1)
+ throw new IllegalArgumentException(
+ "Invalid StatusVariable path: empty monitorable ID or StatusVariable name.");
+
+ prefixMonId = statusVariable.charAt(sep - 1) == '*';
+ prefixVarId = statusVariable.charAt(len - 1) == '*';
+
+ monId = statusVariable.substring(0, prefixMonId ? sep - 1 : sep);
+ varId = statusVariable.substring(sep + 1, prefixVarId ? len - 1 : len);
+
+ checkId(monId, "Monitorable ID part of the target");
+ checkId(varId, "Status Variable ID part of the target");
+
+ minJobInterval = 0;
+
+ if(actions.equals("*"))
+ mask = ALL_FLAGS;
+ else {
+ mask = 0;
+ StringTokenizer st = new StringTokenizer(actions, ",");
+ while (st.hasMoreTokens()) {
+ String action = st.nextToken();
+ if (action.equalsIgnoreCase(READ)) {
+ addToMask(READ_FLAG, READ);
+ } else if (action.equalsIgnoreCase(RESET)) {
+ addToMask(RESET_FLAG, RESET);
+ } else if (action.equalsIgnoreCase(PUBLISH)) {
+ addToMask(PUBLISH_FLAG, PUBLISH);
+ } else if (action.equalsIgnoreCase(SWITCHEVENTS)) {
+ addToMask(SWITCHEVENTS_FLAG, SWITCHEVENTS);
+ } else if (action.toLowerCase().startsWith(STARTJOB)) {
+ minJobInterval = 0;
+
+ int slen = STARTJOB.length();
+ if (action.length() != slen) {
+ if (action.charAt(slen) != ':')
+ throw new IllegalArgumentException(
+ "Invalid action '" + action + "'.");
+
+ try {
+ minJobInterval = Integer.parseInt(action
+ .substring(slen + 1));
+ } catch (NumberFormatException e) {
+ throw new IllegalArgumentException(
+ "Invalid parameter in startjob action '"
+ + action + "'.");
+ }
+ }
+ addToMask(STARTJOB_FLAG, STARTJOB);
+ } else
+ throw new IllegalArgumentException("Invalid action '" +
+ action + "'");
+ }
+ }
+ }
+
+ private void addToMask(int action, String actionString) {
+ if((mask & action) != 0)
+ throw new IllegalArgumentException("Invalid action string: " +
+ actionString + " appears multiple times.");
+
+ mask |= action;
+ }
+
+ private void checkId(String id, String idName)
+ throws IllegalArgumentException {
+
+ byte[] nameBytes;
+ try {
+ nameBytes = id.getBytes("UTF-8");
+ } catch (UnsupportedEncodingException e) {
+ // never happens, "UTF-8" must always be supported
+ throw new IllegalStateException(e.getMessage());
+ }
+ if(nameBytes.length > StatusVariable.MAX_ID_LENGTH)
+ throw new IllegalArgumentException(idName + " is too long (over " +
+ StatusVariable.MAX_ID_LENGTH + " bytes in UTF-8 encoding).");
+
+
+ if (id.equals(".") || id.equals(".."))
+ throw new IllegalArgumentException(idName + " is invalid.");
+
+ char[] chars = id.toCharArray();
+ for (int i = 0; i < chars.length; i++)
+ if (StatusVariable.SYMBOLIC_NAME_CHARACTERS.indexOf(chars[i]) == -1)
+ throw new IllegalArgumentException(idName +
+ " contains invalid characters.");
+ }
+
+ /**
+ * Create an integer hash of the object. The hash codes of
+ * <code>MonitorPermission</code>s <code>p1</code> and <code>p2</code> are
+ * the same if <code>p1.equals(p2)</code>.
+ *
+ * @return the hash of the object
+ */
+ public int hashCode() {
+ return new Integer(mask).hashCode()
+ ^ new Integer(minJobInterval).hashCode() ^ monId.hashCode()
+ ^ new Boolean(prefixMonId).hashCode()
+ ^ varId.hashCode()
+ ^ new Boolean(prefixVarId).hashCode();
+ }
+
+ /**
+ * Determines the equality of two <code>MonitorPermission</code> objects.
+ * Two <code>MonitorPermission</code> objects are equal if their target
+ * strings are equal and the same set of actions are listed in their action
+ * strings.
+ *
+ * @param o the object being compared for equality with this object
+ * @return <code>true</code> if the two permissions are equal
+ */
+ public boolean equals(Object o) {
+ if (!(o instanceof MonitorPermission))
+ return false;
+
+ MonitorPermission other = (MonitorPermission) o;
+
+ return mask == other.mask && minJobInterval == other.minJobInterval
+ && monId.equals(other.monId)
+ && prefixMonId == other.prefixMonId
+ && varId.equals(other.varId)
+ && prefixVarId == other.prefixVarId;
+ }
+
+ /**
+ * Get the action string associated with this permission. The actions are
+ * returned in the following order: <code>read</code>, <code>reset</code>,
+ * <code>publish</code>, <code>startjob</code>, <code>switchevents</code>.
+ *
+ * @return the allowed actions separated by commas, cannot be
+ * <code>null</code>
+ */
+ public String getActions() {
+ StringBuffer sb = new StringBuffer();
+
+ appendAction(sb, READ_FLAG, READ);
+ appendAction(sb, RESET_FLAG, RESET);
+ appendAction(sb, PUBLISH_FLAG, PUBLISH);
+ appendAction(sb, STARTJOB_FLAG, STARTJOB);
+ appendAction(sb, SWITCHEVENTS_FLAG, SWITCHEVENTS);
+
+ return sb.toString();
+ }
+
+ private void appendAction(StringBuffer sb, int flag, String actionName) {
+ if ((mask & flag) != 0) {
+ if(sb.length() != 0)
+ sb.append(',');
+ sb.append(actionName);
+
+ if(flag == STARTJOB_FLAG && minJobInterval != 0)
+ sb.append(':').append(minJobInterval);
+ }
+ }
+
+ /**
+ * Determines if the specified permission is implied by this permission.
+ * <p>
+ * This method returns <code>false</code> if and only if at least one of the
+ * following conditions are fulfilled for the specified permission:
+ * <ul>
+ * <li>it is not a <code>MonitorPermission</code>
+ * <li>it has a broader set of actions allowed than this one
+ * <li>it allows initiating time based monitoring jobs with a lower minimal
+ * sampling interval
+ * <li>the target set of <code>Monitorable</code>s is not the same nor a
+ * subset of the target set of <code>Monitorable</code>s of this permission
+ * <li>the target set of <code>StatusVariable</code>s is not the same
+ * nor a subset of the target set of <code>StatusVariable</code>s of this
+ * permission
+ * </ul>
+ *
+ * @param p the permission to be checked
+ * @return <code>true</code> if the given permission is implied by this
+ * permission
+ */
+ public boolean implies(Permission p) {
+ if (!(p instanceof MonitorPermission))
+ return false;
+
+ MonitorPermission other = (MonitorPermission) p;
+
+ if ((mask & other.mask) != other.mask)
+ return false;
+
+ if ((other.mask & STARTJOB_FLAG) != 0
+ && minJobInterval > other.minJobInterval)
+ return false;
+
+ return implies(monId, prefixMonId, other.monId, other.prefixMonId)
+ && implies(varId, prefixVarId, other.varId, other.prefixVarId);
+ }
+
+ private boolean implies(String id, boolean prefix, String oid,
+ boolean oprefix) {
+
+ return prefix ? oid.startsWith(id) : !oprefix && id.equals(oid);
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/monitor/Monitorable.java b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/Monitorable.java
new file mode 100644
index 0000000..8203ddd
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/Monitorable.java
@@ -0,0 +1,140 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/Monitorable.java,v 1.17 2006/06/16 16:31:25 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.monitor;
+
+/**
+ * A <code>Monitorable</code> can provide information about itself in the form
+ * of <code>StatusVariables</code>. Instances of this interface should
+ * register themselves at the OSGi Service Registry. The
+ * <code>MonitorAdmin</code> listens to the registration of
+ * <code>Monitorable</code> services, and makes the information they provide
+ * available also through the Device Management Tree (DMT) for remote access.
+ * <p>
+ * The monitorable service is identified by its PID string which must be a non-
+ * <code>null</code>, non-empty string that conforms to the "symbolic-name"
+ * definition in the OSGi core specification. This means that only the
+ * characters [-_.a-zA-Z0-9] may be used. The length of the PID must not exceed
+ * 20 characters.
+ * <p>
+ * A <code>Monitorable</code> may optionally support sending notifications
+ * when the status of its <code>StatusVariables</code> change. Support for
+ * change notifications can be defined per <code>StatusVariable</code>.
+ * <p>
+ * Publishing <code>StatusVariables</code> requires the presence of the
+ * <code>MonitorPermission</code> with the <code>publish</code> action
+ * string. This permission, however, is not checked during registration of the
+ * <code>Monitorable</code> service. Instead, the <code>MonitorAdmin</code>
+ * implemenatation must make sure that when a <code>StatusVariable</code> is
+ * queried, it is shown only if the <code>Monitorable</code> is authorized to
+ * publish the given <code>StatusVariable</code>.
+ */
+public interface Monitorable {
+ /**
+ * Returns the list of <code>StatusVariable</code> identifiers published
+ * by this <code>Monitorable</code>. A <code>StatusVariable</code> name
+ * is unique within the scope of a <code>Monitorable</code>. The array
+ * contains the elements in no particular order. The returned value must not
+ * be <code>null</code>.
+ *
+ * @return the <code>StatusVariable<code> identifiers published by this
+ * object, or an empty array if none are published
+ */
+ public String[] getStatusVariableNames();
+
+ /**
+ * Returns the <code>StatusVariable</code> object addressed by its
+ * identifier. The <code>StatusVariable</code> will hold the value taken
+ * at the time of this method call.
+ * <p>
+ * The given identifier does not contain the Monitorable PID, i.e. it
+ * specifies the name and not the path of the Status Variable.
+ *
+ * @param id the identifier of the <code>StatusVariable</code>, cannot be
+ * <code>null</code>
+ * @return the <code>StatusVariable</code> object
+ * @throws java.lang.IllegalArgumentException if <code>id</code> points to a
+ * non-existing <code>StatusVariable</code>
+ */
+ public StatusVariable getStatusVariable(String id)
+ throws IllegalArgumentException;
+
+ /**
+ * Tells whether the <code>StatusVariable</code> provider is able to send
+ * instant notifications when the given <code>StatusVariable</code>
+ * changes. If the <code>Monitorable</code> supports sending change
+ * updates it must notify the <code>MonitorListener</code> when the value
+ * of the <code>StatusVariable</code> changes. The
+ * <code>Monitorable</code> finds the <code>MonitorListener</code>
+ * service through the Service Registry.
+ * <p>
+ * The given identifier does not contain the Monitorable PID, i.e. it
+ * specifies the name and not the path of the Status Variable.
+ *
+ * @param id the identifier of the <code>StatusVariable</code>, cannot be
+ * <code>null</code>
+ * @return <code>true</code> if the <code>Monitorable</code> can send
+ * notification when the given <code>StatusVariable</code>
+ * changes, <code>false</code> otherwise
+ * @throws java.lang.IllegalArgumentException if <code>id</code> points to a
+ * non-existing <code>StatusVariable</code>
+ */
+ public boolean notifiesOnChange(String id) throws IllegalArgumentException;
+
+ /**
+ * Issues a request to reset a given <code>StatusVariable</code>.
+ * Depending on the semantics of the actual Status Variable this call may or
+ * may not succeed: it makes sense to reset a counter to its starting value,
+ * but for example a <code>StatusVariable</code> of type <code>String</code>
+ * might not have a meaningful default value. Note that for numeric
+ * <code>StatusVariables</code> the starting value may not necessarily be
+ * 0. Resetting a <code>StatusVariable</code> must trigger a monitor event.
+ * <p>
+ * The given identifier does not contain the Monitorable PID, i.e. it
+ * specifies the name and not the path of the Status Variable.
+ *
+ * @param id the identifier of the <code>StatusVariable</code>, cannot be
+ * <code>null</code>
+ * @return <code>true</code> if the <code>Monitorable</code> could
+ * successfully reset the given <code>StatusVariable</code>,
+ * <code>false</code> otherwise
+ * @throws java.lang.IllegalArgumentException if <code>id</code> points to a
+ * non-existing <code>StatusVariable</code>
+ */
+ public boolean resetStatusVariable(String id)
+ throws IllegalArgumentException;
+
+ /**
+ * Returns a human readable description of a <code>StatusVariable</code>.
+ * This can be used by management systems on their GUI. The
+ * <code>null</code> return value is allowed if there is no description for
+ * the specified Status Variable.
+ * <p>
+ * The given identifier does not contain the Monitorable PID, i.e. it
+ * specifies the name and not the path of the Status Variable.
+ *
+ * @param id the identifier of the <code>StatusVariable</code>, cannot be
+ * <code>null</code>
+ * @return the human readable description of this
+ * <code>StatusVariable</code> or <code>null</code> if it is not
+ * set
+ * @throws java.lang.IllegalArgumentException if <code>id</code> points to a
+ * non-existing <code>StatusVariable</code>
+ */
+ public String getDescription(String id) throws IllegalArgumentException;
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitoringJob.java b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitoringJob.java
new file mode 100644
index 0000000..75b9d2e
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/MonitoringJob.java
@@ -0,0 +1,126 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/MonitoringJob.java,v 1.14 2006/06/16 16:31:25 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.monitor;
+
+/**
+ * A Monitoring Job is a request for scheduled or event based notifications on
+ * update of a set of <code>StatusVariable</code>s. The job is a data
+ * structure that holds a non-empty list of <code>StatusVariable</code> names,
+ * an identification of the initiator of the job, and the sampling parameters.
+ * There are two kinds of monitoring jobs: time based and change based. Time
+ * based jobs take samples of all <code>StatusVariable</code>s with a
+ * specified frequency. The number of samples to be taken before the job
+ * finishes may be specified. Change based jobs are only interested in the
+ * changes of the monitored <code>StatusVariable</code>s. In this case, the
+ * number of changes that must take place between two notifications can be
+ * specified.
+ * <p>
+ * The job can be started on the <code>MonitorAdmin</code> interface. Running
+ * the job (querying the <code>StatusVariable</code>s, listening to changes,
+ * and sending out notifications on updates) is the task of the
+ * <code>MonitorAdmin</code> implementation.
+ * <p>
+ * Whether a monitoring job keeps track dynamically of the
+ * <code>StatusVariable</code>s it monitors is not specified. This means that
+ * if we monitor a <code>StatusVariable</code> of a <code>Monitorable</code>
+ * service which disappears and later reappears then it is implementation
+ * specific whether we still receive updates of the <code>StatusVariable</code>
+ * changes or not.
+ */
+public interface MonitoringJob {
+ /**
+ * Stops a Monitoring Job. Note that a time based job can also stop
+ * automatically if the specified number of samples have been taken.
+ */
+ public void stop();
+
+ /**
+ * Returns the identitifier of the principal who initiated the job. This is
+ * set at the time when
+ * {@link MonitorAdmin#startJob MonitorAdmin.startJob()} method is called.
+ * This string holds the ServerID if the operation was initiated from a
+ * remote manager, or an arbitrary ID of the initiator entity in the local
+ * case (used for addressing notification events).
+ *
+ * @return the ID of the initiator, cannot be <code>null</code>
+ */
+ public String getInitiator();
+
+ /**
+ * Returns the list of <code>StatusVariable</code> names that are the
+ * targets of this measurement job. For time based jobs, the
+ * <code>MonitorAdmin</code> will iterate through this list and query all
+ * <code>StatusVariable</code>s when its timer set by the job's frequency
+ * rate expires.
+ *
+ * @return the target list of the measurement job in
+ * [Monitorable_ID]/[StatusVariable_ID] format, cannot be
+ * <code>null</code>
+ */
+ public String[] getStatusVariableNames();
+
+ /**
+ * Returns the delay (in seconds) between two samples. If this call returns
+ * N (greater than 0) then the <code>MonitorAdmin</code> queries each
+ * <code>StatusVariable</code> that belongs to this job every N seconds.
+ * The value 0 means that the job is not scheduled but event based: in this
+ * case instant notification on changes is requested (at every nth change of
+ * the value, as specified by the report count parameter).
+ *
+ * @return the delay (in seconds) between samples, or 0 for change based
+ * jobs
+ */
+ public int getSchedule();
+
+ /**
+ * Returns the number of times <code>MonitorAdmin</code> will query the
+ * <code>StatusVariable</code>s (for time based jobs), or the number of
+ * changes of a <code>StatusVariable</code> between notifications (for
+ * change based jobs). Time based jobs with non-zero report count will take
+ * <code>getReportCount()</code>*<code>getSchedule()</code> time to
+ * finish. Time based jobs with 0 report count and change based jobs do not
+ * stop automatically, but all jobs can be stopped with the {@link #stop}
+ * method.
+ *
+ * @return the number of measurements to be taken, or the number of changes
+ * between notifications
+ */
+ public int getReportCount();
+
+ /**
+ * Returns whether the job was started locally or remotely. Jobs started by
+ * the clients of this API are always local, remote jobs can only be started
+ * using the Device Management Tree.
+ *
+ * @return <code>true</code> if the job was started from the local device,
+ * <code>false</code> if the job was initiated from a management
+ * server through the device management tree
+ */
+ public boolean isLocal();
+
+ /**
+ * Returns whether the job is running. A job is running until it is
+ * explicitely stopped, or, in case of time based jobs with a finite report
+ * count, until the given number of measurements have been made.
+ *
+ * @return <code>true</code> if the job is still running, <code>false</code>
+ * if it has finished
+ */
+ public boolean isRunning();
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/monitor/StatusVariable.java b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/StatusVariable.java
new file mode 100644
index 0000000..74ff9df
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/monitor/StatusVariable.java
@@ -0,0 +1,433 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/StatusVariable.java,v 1.14 2006/06/16 16:31:25 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.monitor;
+
+import java.io.UnsupportedEncodingException;
+import java.util.Date;
+
+/**
+ * A <code>StatusVariable</code> object represents the value of a status
+ * variable taken with a certain collection method at a certain point of time.
+ * The type of the <code>StatusVariable</code> can be <code>int</code>,
+ * <code>float</code>, <code>boolean</code> or <code>String</code>.
+ * <p>
+ * A <code>StatusVariable</code> is identified by an ID string that is unique
+ * within the scope of a <code>Monitorable</code>. The ID must be a non-
+ * <code>null</code>, non-empty string that conforms to the "symbolic-name"
+ * definition in the OSGi core specification. This means that only the
+ * characters [-_.a-zA-Z0-9] may be used. The length of the ID must not exceed
+ * 32 bytes when UTF-8 encoded.
+ */
+public final class StatusVariable {
+ //----- Public constants -----//
+ /**
+ * Constant for identifying <code>int</code> data type.
+ */
+ public static final int TYPE_INTEGER = 0;
+
+ /**
+ * Constant for identifying <code>float</code> data type.
+ */
+ public static final int TYPE_FLOAT = 1;
+
+ /**
+ * Constant for identifying <code>String</code> data type.
+ */
+ public static final int TYPE_STRING = 2;
+
+ /**
+ * Constant for identifying <code>boolean</code> data type.
+ */
+ public static final int TYPE_BOOLEAN = 3;
+
+ /**
+ * Constant for identifying 'Cumulative Counter' data collection method.
+ */
+ public static final int CM_CC = 0;
+
+ /**
+ * Constant for identifying 'Discrete Event Registration' data collection
+ * method.
+ */
+ public static final int CM_DER = 1;
+
+ /**
+ * Constant for identifying 'Gauge' data collection method.
+ */
+ public static final int CM_GAUGE = 2;
+
+ /**
+ * Constant for identifying 'Status Inspection' data collection method.
+ */
+ public static final int CM_SI = 3;
+
+ //----- Package private constants -----//
+
+ static final String SYMBOLIC_NAME_CHARACTERS =
+ "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ" + "0123456789" +
+ "-_."; // a subset of the characters allowed in DMT URIs
+
+ static final int MAX_ID_LENGTH = 32;
+
+ //----- Private fields -----//
+ private String id;
+ private Date timeStamp;
+ private int cm;
+ private int type;
+
+ private int intData;
+ private float floatData;
+ private String stringData;
+ private boolean booleanData;
+
+
+ //----- Constructors -----//
+ /**
+ * Constructor for a <code>StatusVariable</code> of <code>int</code>
+ * type.
+ *
+ * @param id the identifier of the <code>StatusVariable</code>
+ * @param cm the collection method, one of the <code>CM_</code> constants
+ * @param data the <code>int</code> value of the
+ * <code>StatusVariable</code>
+ * @throws java.lang.IllegalArgumentException if the given <code>id</code>
+ * is not a valid <code>StatusVariable</code> name, or if
+ * <code>cm</code> is not one of the collection method constants
+ * @throws java.lang.NullPointerException if the <code>id</code>
+ * parameter is <code>null</code>
+ */
+ public StatusVariable(String id, int cm, int data) {
+ setCommon(id, cm);
+ type = TYPE_INTEGER;
+ intData = data;
+ }
+
+ /**
+ * Constructor for a <code>StatusVariable</code> of <code>float</code>
+ * type.
+ *
+ * @param id the identifier of the <code>StatusVariable</code>
+ * @param cm the collection method, one of the <code>CM_</code> constants
+ * @param data the <code>float</code> value of the
+ * <code>StatusVariable</code>
+ * @throws java.lang.IllegalArgumentException if the given <code>id</code>
+ * is not a valid <code>StatusVariable</code> name, or if
+ * <code>cm</code> is not one of the collection method constants
+ * @throws java.lang.NullPointerException if the <code>id</code> parameter
+ * is <code>null</code>
+ */
+ public StatusVariable(String id, int cm, float data) {
+ setCommon(id, cm);
+ type = TYPE_FLOAT;
+ floatData = data;
+ }
+
+ /**
+ * Constructor for a <code>StatusVariable</code> of <code>boolean</code>
+ * type.
+ *
+ * @param id the identifier of the <code>StatusVariable</code>
+ * @param cm the collection method, one of the <code>CM_</code> constants
+ * @param data the <code>boolean</code> value of the
+ * <code>StatusVariable</code>
+ * @throws java.lang.IllegalArgumentException if the given <code>id</code>
+ * is not a valid <code>StatusVariable</code> name, or if
+ * <code>cm</code> is not one of the collection method constants
+ * @throws java.lang.NullPointerException if the <code>id</code> parameter
+ * is <code>null</code>
+ */
+ public StatusVariable(String id, int cm, boolean data) {
+ setCommon(id, cm);
+ type = TYPE_BOOLEAN;
+ booleanData = data;
+ }
+
+ /**
+ * Constructor for a <code>StatusVariable</code> of <code>String</code>
+ * type.
+ *
+ * @param id the identifier of the <code>StatusVariable</code>
+ * @param cm the collection method, one of the <code>CM_</code> constants
+ * @param data the <code>String</code> value of the
+ * <code>StatusVariable</code>, can be <code>null</code>
+ * @throws java.lang.IllegalArgumentException if the given <code>id</code>
+ * is not a valid <code>StatusVariable</code> name, or if
+ * <code>cm</code> is not one of the collection method constants
+ * @throws java.lang.NullPointerException if the <code>id</code> parameter
+ * is <code>null</code>
+ */
+ public StatusVariable(String id, int cm, String data) {
+ setCommon(id, cm);
+ type = TYPE_STRING;
+ stringData = data;
+ }
+
+
+ // ----- Public methods -----//
+ /**
+ * Returns the ID of this <code>StatusVariable</code>. The ID is unique
+ * within the scope of a <code>Monitorable</code>.
+ *
+ * @return the ID of this <code>StatusVariable</code>
+ */
+ public String getID() {
+ return id;
+ }
+
+ /**
+ * Returns information on the data type of this <code>StatusVariable</code>.
+ *
+ * @return one of the <code>TYPE_</code> constants indicating the type of
+ * this <code>StatusVariable</code>
+ */
+ public int getType() {
+ return type;
+ }
+
+ /**
+ * Returns the timestamp associated with the <code>StatusVariable</code>.
+ * The timestamp is stored when the <code>StatusVariable</code> instance is
+ * created, generally during the {@link Monitorable#getStatusVariable}
+ * method call.
+ *
+ * @return the time when the <code>StatusVariable</code> value was
+ * queried, cannot be <code>null</code>
+ *
+ */
+ public Date getTimeStamp() {
+ return timeStamp;
+ }
+
+ /**
+ * Returns the <code>StatusVariable</code> value if its type is
+ * <code>String</code>.
+ *
+ * @return the <code>StatusVariable</code> value as a <code>String</code>
+ * @throws java.lang.IllegalStateException if the type of the
+ * <code>StatusVariable</code> is not <code>String</code>
+ */
+ public String getString() throws IllegalStateException {
+ if (type != TYPE_STRING)
+ throw new IllegalStateException(
+ "This StatusVariable does not contain a String value.");
+ return stringData;
+ }
+
+ /**
+ * Returns the <code>StatusVariable</code> value if its type is
+ * <code>int</code>.
+ *
+ * @return the <code>StatusVariable</code> value as an <code>int</code>
+ * @throws java.lang.IllegalStateException if the type of this
+ * <code>StatusVariable</code> is not <code>int</code>
+ */
+ public int getInteger() throws IllegalStateException {
+ if (type != TYPE_INTEGER)
+ throw new IllegalStateException(
+ "This StatusVariable does not contain an integer value.");
+ return intData;
+ }
+
+ /**
+ * Returns the <code>StatusVariable</code> value if its type is
+ * <code>float</code>.
+ *
+ * @return the <code>StatusVariable</code> value as a <code>float</code>
+ * @throws java.lang.IllegalStateException if the type of this
+ * <code>StatusVariable</code> is not <code>float</code>
+ */
+ public float getFloat() throws IllegalStateException {
+ if (type != TYPE_FLOAT)
+ throw new IllegalStateException(
+ "This StatusVariable does not contain a float value.");
+ return floatData;
+ }
+
+ /**
+ * Returns the <code>StatusVariable</code> value if its type is
+ * <code>boolean</code>.
+ *
+ * @return the <code>StatusVariable</code> value as a <code>boolean</code>
+ * @throws java.lang.IllegalStateException if the type of this
+ * <code>StatusVariable</code> is not <code>boolean</code>
+ */
+ public boolean getBoolean() throws IllegalStateException {
+ if (type != TYPE_BOOLEAN)
+ throw new IllegalStateException(
+ "This StatusVariable does not contain a boolean value.");
+ return booleanData;
+ }
+
+ /**
+ * Returns the collection method of this <code>StatusVariable</code>. See
+ * section 3.3 b) in [ETSI TS 132 403]
+ *
+ * @return one of the <code>CM_</code> constants
+ */
+ public int getCollectionMethod() {
+ return cm;
+ }
+
+ /**
+ * Compares the specified object with this <code>StatusVariable</code>.
+ * Two <code>StatusVariable</code> objects are considered equal if their
+ * full path, collection method and type are identical, and the data
+ * (selected by their type) is equal.
+ *
+ * @param obj the object to compare with this <code>StatusVariable</code>
+ * @return <code>true</code> if the argument represents the same
+ * <code>StatusVariable</code> as this object
+ */
+ public boolean equals(Object obj) {
+ if (!(obj instanceof StatusVariable))
+ return false;
+
+ StatusVariable other = (StatusVariable) obj;
+
+ if (!equals(id, other.id) || cm != other.cm || type != other.type)
+ return false;
+
+ switch (type) {
+ case TYPE_INTEGER: return intData == other.intData;
+ case TYPE_FLOAT: return floatData == other.floatData;
+ case TYPE_STRING: return equals(stringData, other.stringData);
+ case TYPE_BOOLEAN: return booleanData == other.booleanData;
+ }
+
+ return false; // never reached
+ }
+
+ /**
+ * Returns the hash code value for this <code>StatusVariable</code>. The
+ * hash code is calculated based on the full path, collection method and
+ * value of the <code>StatusVariable</code>.
+ *
+ * @return the hash code of this object
+ */
+ public int hashCode() {
+ int hash = hashCode(id) ^ cm;
+
+ switch (type) {
+ case TYPE_INTEGER: return hash ^ intData;
+ case TYPE_FLOAT: return hash ^ hashCode(new Float(floatData));
+ case TYPE_BOOLEAN: return hash ^ hashCode(new Boolean(booleanData));
+ case TYPE_STRING: return hash ^ hashCode(stringData);
+ }
+
+ return 0; // never reached
+ }
+
+ // String representation: StatusVariable(path, cm, time, type, value)
+ /**
+ * Returns a <code>String</code> representation of this
+ * <code>StatusVariable</code>. The returned <code>String</code>
+ * contains the full path, collection method, timestamp, type and value
+ * parameters of the <code>StatusVariable</code> in the following format:
+ * <pre>StatusVariable(<path>, <cm>, <timestamp>, <type>, <value>)</pre>
+ * The collection method identifiers used in the string representation are
+ * "CC", "DER", "GAUGE" and "SI" (without the quotes). The format of the
+ * timestamp is defined by the <code>Date.toString</code> method, while the
+ * type is identified by one of the strings "INTEGER", "FLOAT", "STRING" and
+ * "BOOLEAN". The final field contains the string representation of the
+ * value of the status variable.
+ *
+ * @return the <code>String</code> representation of this
+ * <code>StatusVariable</code>
+ */
+ public String toString() {
+ String cmName = null;
+ switch (cm) {
+ case CM_CC: cmName = "CC"; break;
+ case CM_DER: cmName = "DER"; break;
+ case CM_GAUGE: cmName = "GAUGE"; break;
+ case CM_SI: cmName = "SI"; break;
+ }
+
+ String beg = "StatusVariable(" + id + ", " + cmName + ", "
+ + timeStamp + ", ";
+
+ switch (type) {
+ case TYPE_INTEGER: return beg + "INTEGER, " + intData + ")";
+ case TYPE_FLOAT: return beg + "FLOAT, " + floatData + ")";
+ case TYPE_STRING: return beg + "STRING, " + stringData + ")";
+ case TYPE_BOOLEAN: return beg + "BOOLEAN, " + booleanData + ")";
+ }
+
+ return null; // never reached
+ }
+
+ //----- Private methods -----//
+
+ private void setCommon(String id, int cm)
+ throws IllegalArgumentException, NullPointerException {
+ checkId(id, "StatusVariable ID");
+
+ if (cm != CM_CC && cm != CM_DER && cm != CM_GAUGE && cm != CM_SI)
+ throw new IllegalArgumentException(
+ "Unknown data collection method constant '" + cm + "'.");
+
+ this.id = id;
+ this.cm = cm;
+ timeStamp = new Date();
+ }
+
+
+ private boolean equals(Object o1, Object o2) {
+ return o1 == null ? o2 == null : o1.equals(o2);
+ }
+
+ private int hashCode(Object o) {
+ return o == null ? 0 : o.hashCode();
+ }
+
+ private static void checkId(String id, String idName)
+ throws IllegalArgumentException, NullPointerException {
+ if (id == null)
+ throw new NullPointerException(idName + " is null.");
+ if(id.length() == 0)
+ throw new IllegalArgumentException(idName + " is empty.");
+
+ byte[] nameBytes;
+ try {
+ nameBytes = id.getBytes("UTF-8");
+ } catch (UnsupportedEncodingException e) {
+ // never happens, "UTF-8" must always be supported
+ throw new IllegalStateException(e.getMessage());
+ }
+ if(nameBytes.length > MAX_ID_LENGTH)
+ throw new IllegalArgumentException(idName + " is too long " +
+ "(over " + MAX_ID_LENGTH + " bytes in UTF-8 encoding).");
+
+ if(id.equals(".") || id.equals(".."))
+ throw new IllegalArgumentException(idName + " is invalid.");
+
+ if(!containsValidChars(id))
+ throw new IllegalArgumentException(idName +
+ " contains invalid characters.");
+ }
+
+ private static boolean containsValidChars(String name) {
+ char[] chars = name.toCharArray();
+ for(int i = 0; i < chars.length; i++)
+ if(SYMBOLIC_NAME_CHARACTERS.indexOf(chars[i]) == -1)
+ return false;
+
+ return true;
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/service/useradmin/Authorization.java b/org.osgi.compendium/src/main/java/org/osgi/service/useradmin/Authorization.java
index 08f0205..618a0f1 100644
--- a/org.osgi.compendium/src/main/java/org/osgi/service/useradmin/Authorization.java
+++ b/org.osgi.compendium/src/main/java/org/osgi/service/useradmin/Authorization.java
@@ -1,7 +1,7 @@
/*
- * $Header: /cvshome/build/org.osgi.service.useradmin/src/org/osgi/service/useradmin/Authorization.java,v 1.9 2006/07/11 00:54:01 hargrave Exp $
+ * $Header: /cvshome/build/org.osgi.service.useradmin/src/org/osgi/service/useradmin/Authorization.java,v 1.11 2007/02/07 18:53:08 hargrave Exp $
*
- * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2001, 2007). 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.
@@ -60,7 +60,7 @@
* <code>Authorization</code> object), the service explicitly checks that the
* calling bundle has permission to make the call.
*
- * @version $Revision: 1.9 $
+ * @version $Revision: 1.11 $
*/
public interface Authorization {
/**
@@ -92,10 +92,10 @@
public boolean hasRole(String name);
/**
- * Gets the names of all roles encapsulated by this <code>Authorization</code>
+ * Gets the names of all roles implied by this <code>Authorization</code>
* context.
*
- * @return The names of all roles encapsulated by this
+ * @return The names of all roles implied by this
* <code>Authorization</code> context, or <code>null</code> if no roles
* are in the context. The predefined role <code>user.anyone</code>
* will not be included in this list.
diff --git a/org.osgi.compendium/src/main/java/org/osgi/util/gsm/IMEICondition.java b/org.osgi.compendium/src/main/java/org/osgi/util/gsm/IMEICondition.java
new file mode 100644
index 0000000..958b55b
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/util/gsm/IMEICondition.java
@@ -0,0 +1,85 @@
+/*
+ * $Header: /cvshome/build/org.osgi.util.gsm/src/org/osgi/util/gsm/IMEICondition.java,v 1.21 2007/02/19 21:32: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.util.gsm;
+
+import java.security.AccessController;
+import java.security.PrivilegedAction;
+
+import org.osgi.framework.Bundle;
+import org.osgi.service.condpermadmin.Condition;
+import org.osgi.service.condpermadmin.ConditionInfo;
+
+/**
+ * Class representing an IMEI condition. Instances of this class contain a
+ * string value that is matched against the IMEI of the device.
+ */
+public class IMEICondition {
+ private static final String ORG_OSGI_UTIL_GSM_IMEI = "org.osgi.util.gsm.imei";
+ private static final String imei ;
+
+ static {
+ imei = (String)
+ AccessController.doPrivileged(
+ new PrivilegedAction() {
+ public Object run() {
+ return System.getProperty(ORG_OSGI_UTIL_GSM_IMEI);
+ }
+ }
+ );
+ }
+
+ private IMEICondition() {
+ }
+
+ /**
+ * Creates an IMEICondition object.
+ *
+ * @param bundle ignored, as the IMEI number is the property of the mobile device,
+ * and thus the same for all bundles.
+ * @param conditionInfo contains the IMEI value to match the device's IMEI against. Its
+ * {@link ConditionInfo#getArgs()} method should return a String array with one value, the
+ * IMEI string. The IMEI is 15 digits without hypens. Limited pattern matching is allowed,
+ * then the string is 0 to 14 digits, followed by an asterisk(<code>*</code>).
+ * @return An IMEICondition object, that can tell whether its IMEI number matches that of the device.
+ * If the number contains an asterisk(<code>*</code>), then the beginning
+ * of the imei is compared to the pattern.
+ * @throws NullPointerException if one of the parameters is <code>null</code>.
+ * @throws IllegalArgumentException if the IMEI is not a string of 15 digits, or
+ * 0 to 14 digits with an <code>*</code> at the end.
+ */
+ public static Condition getCondition(Bundle bundle, ConditionInfo conditionInfo) {
+ if (bundle==null) throw new NullPointerException("bundle");
+ String imei = conditionInfo.getArgs()[0];
+ if (imei.length()>15) throw new IllegalArgumentException("imei too long: "+imei);
+ if (imei.endsWith("*")) {
+ imei = imei.substring(0,imei.length()-1);
+ } else {
+ if (imei.length()!=15) throw new IllegalArgumentException("not a valid imei: "+imei);
+ }
+ for(int i=0;i<imei.length();i++) {
+ int c = imei.charAt(i);
+ if (c<'0'||c>'9') throw new IllegalArgumentException("not a valid imei: "+imei);
+ }
+ if (IMEICondition.imei==null) {
+ System.err.println("The OSGi Reference Implementation of org.osgi.util.gsm.IMEICondition ");
+ System.err.println("needs the system property "+ORG_OSGI_UTIL_GSM_IMEI+" set.");
+ return Condition.FALSE;
+ }
+ return IMEICondition.imei.startsWith(imei)?Condition.TRUE:Condition.FALSE;
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/util/gsm/IMSICondition.java b/org.osgi.compendium/src/main/java/org/osgi/util/gsm/IMSICondition.java
new file mode 100644
index 0000000..740bda1
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/util/gsm/IMSICondition.java
@@ -0,0 +1,84 @@
+/*
+ * $Header: /cvshome/build/org.osgi.util.gsm/src/org/osgi/util/gsm/IMSICondition.java,v 1.23 2007/02/19 21:32: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.util.gsm;
+
+import java.security.AccessController;
+import java.security.PrivilegedAction;
+
+import org.osgi.framework.Bundle;
+import org.osgi.service.condpermadmin.Condition;
+import org.osgi.service.condpermadmin.ConditionInfo;
+
+/**
+ * Class representing an IMSI condition. Instances of this class contain a
+ * string value that is matched against the IMSI of the subscriber.
+ */
+public class IMSICondition {
+ private static final String ORG_OSGI_UTIL_GSM_IMSI = "org.osgi.util.gsm.imsi";
+ private static final String imsi;
+
+ static {
+ imsi = (String)
+ AccessController.doPrivileged(
+ new PrivilegedAction() {
+ public Object run() {
+ return System.getProperty(ORG_OSGI_UTIL_GSM_IMSI);
+ }
+ }
+ );
+ }
+
+ private IMSICondition() {}
+
+ /**
+ * Creates an IMSI condition object.
+ *
+ * @param bundle ignored, as the IMSI number is the same for all bundles.
+ * @param conditionInfo contains the IMSI value to match the device's IMSI against. Its
+ * {@link ConditionInfo#getArgs()} method should return a String array with one value, the
+ * IMSI string. The IMSI is 15 digits without hypens. Limited pattern matching is allowed,
+ * then the string is 0 to 14 digits, followed by an asterisk(<code>*</code>).
+ * @return An IMSICondition object, that can tell whether its IMSI number matches that of the device.
+ * If the number contains an asterisk(<code>*</code>), then the beginning
+ * of the IMSI is compared to the pattern.
+ * @throws NullPointerException if one of the parameters is <code>null</code>.
+ * @throws IllegalArgumentException if the IMSI is not a string of 15 digits, or
+ * 0 to 14 digits with an <code>*</code> at the end.
+ */
+ public static Condition getCondition(Bundle bundle, ConditionInfo conditionInfo) {
+ if (bundle==null) throw new NullPointerException("bundle");
+ if (conditionInfo==null) throw new NullPointerException("conditionInfo");
+ String imsi = conditionInfo.getArgs()[0];
+ if (imsi.length()>15) throw new IllegalArgumentException("imsi too long: "+imsi);
+ if (imsi.endsWith("*")) {
+ imsi = imsi.substring(0,imsi.length()-1);
+ } else {
+ if (imsi.length()!=15) throw new IllegalArgumentException("not a valid imei: "+imsi);
+ }
+ for(int i=0;i<imsi.length();i++) {
+ int c = imsi.charAt(i);
+ if (c<'0'||c>'9') throw new IllegalArgumentException("not a valid imei: "+imsi);
+ }
+ if (IMSICondition.imsi==null) {
+ System.err.println("The OSGi Reference Implementation of org.osgi.util.gsm.IMSICondition ");
+ System.err.println("needs the system property "+ORG_OSGI_UTIL_GSM_IMSI+" set.");
+ return Condition.FALSE;
+ }
+ return (IMSICondition.imsi.startsWith(imsi))?Condition.TRUE:Condition.FALSE;
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/util/mobile/UserPromptCondition.java b/org.osgi.compendium/src/main/java/org/osgi/util/mobile/UserPromptCondition.java
new file mode 100644
index 0000000..423ba1a
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/org/osgi/util/mobile/UserPromptCondition.java
@@ -0,0 +1,256 @@
+/*
+ * $Header: /cvshome/build/org.osgi.util.mobile/src/org/osgi/util/mobile/UserPromptCondition.java,v 1.26 2006/07/10 08:18:30 pnagy 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.util.mobile;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.util.Dictionary;
+
+import org.osgi.framework.Bundle;
+import org.osgi.service.condpermadmin.Condition;
+import org.osgi.service.condpermadmin.ConditionInfo;
+
+/**
+ * Class representing a user prompt condition. Instances of this class hold two
+ * values: a prompt string that is to be displayed to the user and the
+ * permission level string according to MIDP2.0 (oneshot, session, blanket).
+ *
+ */
+public class UserPromptCondition implements Condition {
+
+ /*
+ * NOTE: An implementor may also choose to replace this class in
+ * their distribution with a class that directly interfaces with the
+ * policy implementation. This replacement class MUST NOT alter the
+ * public/protected signature of this class.
+ */
+ // this will need to be set by the implementation class
+ static Method factory = null;
+ Condition realUserPromptCondition;
+
+ private final Bundle bundle;
+ private final String levels;
+ private final String defaultLevel;
+ private final String catalogName;
+ private final String message;
+
+ /**
+ * Returns a UserPromptCondition object with the given prompt string and permission
+ * level. The user should be given choice as to what level of permission is
+ * given. Thus, the lifetime of the permission is controlled by the user.
+ *
+ * @param bundle the bundle to ask about.
+ * @param conditionInfo the conditionInfo containing the construction information. Its
+ * {@link ConditionInfo#getArgs()} method should return a String array with 4
+ * strings in it:
+ * <ol start="0">
+ * <li>the possible permission levels. This is a comma-separated list that can contain
+ * following strings: ONESHOT SESSION BLANKET. The order is not important. This
+ * parameter is case-insensitive.
+ * </li>
+ * <li>the default permission level, one chosen from the possible permission levels. If
+ * it is an empty string, then there is no default. This parameter
+ * is case-insensitive.</li>
+ * <li>the message catalog base name. It will be loaded by a {@link java.util.ResourceBundle},
+ * or equivalent
+ * from an exporting OSGi Bundle. Thus, if the catalogName is "com.provider.messages.userprompt",
+ * then there should be an OSGi Bundle exporting the "com.provider.messages" package, and inside
+ * it files like "userprompt_en_US.properties".</li>
+ * <li>textual description of the condition, to be displayed to the user. If
+ * it starts with a '%' sign, then the message is looked up from the catalog specified previously.
+ * The key is the rest of the string after the '%' sign.</li>
+ * </ol>
+ * @return The requested UserPromptCondition.
+ * @throws IllegalArgumentException if the parameters are malformed.
+ * @throws NullPointerException if one of the parameters is <code>null</code>.
+ */
+ public static Condition getCondition(Bundle bundle,ConditionInfo conditionInfo)
+ {
+ String[] args = conditionInfo.getArgs();
+ if (args==null) throw new NullPointerException("args");
+ if (args.length!=4) throw new IllegalArgumentException("args.length=="+args.length+" (should be 4)");
+ if (bundle==null) throw new NullPointerException("bundle");
+ String levels = args[0];
+ String defaultLevel = args[1];
+ String catalogName = args[2];
+ String message = args[3];
+ if (levels==null) throw new NullPointerException("levels");
+ if (defaultLevel==null) throw new NullPointerException("defaultLevel");
+ if (catalogName==null) throw new NullPointerException("catalogName");
+ if (message==null) throw new NullPointerException("message");
+
+ if (factory==null) {
+ // the bundle implementing the UserPromptCondition has not started yet.
+ // Do wrapping magick.
+ return new UserPromptCondition(bundle,levels,defaultLevel,catalogName,message);
+ } else {
+ // there is already a factory, no need to do any wrapping magic
+ try {
+ return (Condition) factory.invoke(null,new Object[]{bundle,levels,defaultLevel,catalogName,message});
+ } catch (IllegalAccessException e) {
+ e.printStackTrace();
+ } catch (InvocationTargetException e) {
+ Throwable original = e.getTargetException();
+ if (original instanceof NullPointerException) throw (NullPointerException) original;
+ if (original instanceof IllegalArgumentException) throw (IllegalArgumentException) original;
+ e.printStackTrace();
+ }
+ // the factory method is not working, fallback behavior:
+ factory = null;
+ return new UserPromptCondition(bundle,levels,defaultLevel,catalogName,message);
+ }
+ }
+
+ /**
+ * Instances of the UserPromptCondition are simply store the construction parameters
+ * until a "real" UserPromptCondition is registered in setFactory(). At that point, it
+ * will delegate all calls there.
+ * @param unused this parameter is here so that ConditionalPermissionAdmin would not
+ * use this as the constructor instead of the getInstance
+ * @param bundle
+ * @param levels
+ * @param defaultLevel
+ * @param catalogName
+ * @param message
+ */
+ private UserPromptCondition(Bundle bundle,String levels,String defaultLevel,String catalogName,String message) {
+ this.bundle=bundle;
+ this.levels=levels;
+ this.defaultLevel=defaultLevel;
+ this.catalogName=catalogName;
+ this.message=message;
+ }
+
+ /**
+ * Check if a factory is registered, and if yes, create userprompt to delegate calls to.
+ */
+ private void lookForImplementation() {
+ if ((realUserPromptCondition==null)&&(factory!=null)) {
+ try {
+ realUserPromptCondition = (Condition) factory.invoke(null,new Object[]{bundle,levels,defaultLevel,catalogName,message});
+ return;
+ } catch (IllegalAccessException e) {
+ e.printStackTrace();
+ } catch (InvocationTargetException e) {
+ e.printStackTrace();
+ }
+ // only if the factory call fails with some invocation exception
+ factory = null;
+ }
+ }
+
+ /**
+ * Checks if the {@link #isSatisfied()} method needs to prompt the user, thus cannot
+ * give results instantly.
+ * This depends on the permission level given in
+ * {@link UserPromptCondition#getCondition(Bundle, ConditionInfo)}.
+ * <ul>
+ * <li>ONESHOT - isPostponed always returns true. The user is prompted for question every time.</li>
+ * <li>SESSION - isPostponed returns true until the user decides either yes or no for the current session.</li>
+ * <li>BLANKET - isPostponed returns true until the user decides either always or never.</li>
+ * </ul>
+ * Regardless of the session level, the user is always given the option to reject the prompt
+ * permanently, as if BLANKET/never was chosen. In this case, the question is not postponed
+ * anymore, and {@link #isSatisfied()} returns false.<br/>
+ * If the system supports an separately accessible permission management GUI,
+ * that may reset the condition
+ * to its initial state.
+ *
+ * @return True, if user interaction is needed.
+ */
+ public boolean isPostponed() {
+ lookForImplementation();
+ if (realUserPromptCondition!=null) {
+ return realUserPromptCondition.isPostponed();
+ } else {
+ return true;
+ }
+ }
+
+ /**
+ * Checks whether the condition may change during the lifetime of the UserPromptCondition object.
+ * This depends on the permission level given in
+ * {@link UserPromptCondition#getCondition(Bundle, ConditionInfo)}.
+ * <ul>
+ * <li>ONESHOT - true</li>
+ * <li>SESSION - true, if the application model's session lifetime is
+ * shorter than the UserPromptCondition object lifetime</li>
+ * <li>BLANKET - false</li>
+ * </ul>
+ * If the system supports separately accessible permission management GUI,
+ * then this function may also return true for SESSION and BLANKET.
+ *
+ * @return True, if the condition can change.
+ */
+ public boolean isMutable() {
+ lookForImplementation();
+ if (realUserPromptCondition!=null) {
+ return realUserPromptCondition.isMutable();
+ } else {
+ // since we don't know what the actual status is, we cannot say
+ // "the condition cannot change anymore"
+ return true;
+ }
+ }
+
+ /**
+ * Displays the prompt string to
+ * the user and returns true if the user accepts. Depending on the
+ * amount of levels the condition is assigned to, the prompt may have
+ * multiple accept buttons and one of them can be selected by default (see
+ * default level parameter at {@link UserPromptCondition#getCondition(Bundle, ConditionInfo)}).
+ * It must always be possible for the user
+ * to stop further prompting of this question, even with ONESHOT and SESSION levels.
+ * In case of BLANKET
+ * and SESSION levels, it is possible that the user has already answered the question,
+ * in this case there will be no prompting, but immediate return with the previous answer.
+ *
+ * @return True if the user accepts the prompt (or accepts any prompt in
+ * case there are multiple permission levels).
+ */
+ public boolean isSatisfied() {
+ lookForImplementation();
+ if (realUserPromptCondition!=null) {
+ return realUserPromptCondition.isSatisfied();
+ } else {
+ // paranoid security option
+ return false;
+ }
+ }
+
+ /**
+ * Checks an array of UserPrompt conditions.
+ *
+ * @param conds The array containing the UserPrompt conditions to evaluate.
+ * @param context Storage area for evaluation. The {@link org.osgi.service.condpermadmin.ConditionalPermissionAdmin}
+ * may evaluate a condition several times for one permission check, so this context
+ * will be used to store results of ONESHOT questions. This way asking the same question
+ * twice in a row can be avoided. If context is null, temporary results will not be stored.
+ * @return True, if all conditions are satisfied.
+ * @throws NullPointerException if conds is null.
+ */
+ public boolean isSatisfied(Condition[] conds, Dictionary context) {
+ lookForImplementation();
+ if (realUserPromptCondition!=null) {
+ return realUserPromptCondition.isSatisfied(conds,context);
+ } else {
+ // paranoid security option
+ return false;
+ }
+ }
+}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/util/tracker/ServiceTracker.java b/org.osgi.compendium/src/main/java/org/osgi/util/tracker/ServiceTracker.java
index 253b9f6..c945088 100644
--- a/org.osgi.compendium/src/main/java/org/osgi/util/tracker/ServiceTracker.java
+++ b/org.osgi.compendium/src/main/java/org/osgi/util/tracker/ServiceTracker.java
@@ -1,7 +1,7 @@
/*
- * $Header: /cvshome/build/org.osgi.util.tracker/src/org/osgi/util/tracker/ServiceTracker.java,v 1.21 2006/07/12 21:05:17 hargrave Exp $
+ * $Header: /cvshome/build/org.osgi.util.tracker/src/org/osgi/util/tracker/ServiceTracker.java,v 1.29 2007/02/19 19:04:33 hargrave Exp $
*
- * Copyright (c) OSGi Alliance (2000, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2007). 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.
@@ -40,14 +40,21 @@
* references to the services being tracked. The <code>getService</code> and
* <code>getServices</code> methods can be called to get the service objects
* for the tracked service.
+ * <p>
+ * The <code>ServiceTracker</code> class is thread-safe. It does not call a
+ * <code>ServiceTrackerCustomizer</code> object while holding any locks.
+ * <code>ServiceTrackerCustomizer</code> implementations must also be
+ * thread-safe.
*
- * @version $Revision: 1.21 $
+ * @ThreadSafe
+ * @version $Revision: 1.29 $
*/
public class ServiceTracker implements ServiceTrackerCustomizer {
/* set this to true to compile in debug messages */
static final boolean DEBUG = false;
/**
- * Bundle context against which this <code>ServiceTracker</code> object is tracking.
+ * Bundle context against which this <code>ServiceTracker</code> object is
+ * tracking.
*/
protected final BundleContext context;
/**
@@ -80,7 +87,7 @@
* Tracked services: <code>ServiceReference</code> object -> customized
* Object and <code>ServiceListener</code> object
*/
- private Tracked tracked;
+ private volatile Tracked tracked;
/**
* Modification count. This field is initialized to zero by open, set to -1
* by close and incremented by modified.
@@ -700,16 +707,17 @@
*
* The tracking count is initialized to 0 when this
* <code>ServiceTracker</code> object is opened. Every time a service is
- * added or removed from this <code>ServiceTracker</code> object the
- * tracking count is incremented.
+ * added, modified or removed from this <code>ServiceTracker</code> object
+ * the tracking count is incremented.
*
* <p>
* The tracking count can be used to determine if this
- * <code>ServiceTracker</code> object has added or removed a service by
- * comparing a tracking count value previously collected with the current
- * tracking count value. If the value has not changed, then no service has
- * been added or removed from this <code>ServiceTracker</code> object
- * since the previous tracking count was collected.
+ * <code>ServiceTracker</code> object has added, modified or removed a
+ * service by comparing a tracking count value previously collected with the
+ * current tracking count value. If the value has not changed, then no
+ * service has been added, modified or removed from this
+ * <code>ServiceTracker</code> object since the previous tracking count
+ * was collected.
*
* @since 1.2
* @return The tracking count for this <code>ServiceTracker</code> object
@@ -722,6 +730,8 @@
/**
* Called by the Tracked object whenever the set of tracked services is
* modified. Increments the tracking count and clears the cache.
+ *
+ * @GuardedBy tracked
*/
/*
* This method must not be synchronized since it is called by Tracked while
@@ -738,13 +748,6 @@
}
/**
- * Finalize. This method no longer performs any function but it kept to
- * maintain binary compatibility with prior versions of this class.
- */
- protected void finalize() throws Throwable {
- }
-
- /**
* Inner class to track services. If a <code>ServiceTracker</code> object
* is reused (closed then reopened), then a new Tracked object is used. This
* class is a hashtable mapping <code>ServiceReference</code> object ->
@@ -753,6 +756,7 @@
* tracked services. This is not a public class. It is only for use by the
* implementation of the <code>ServiceTracker</code> class.
*
+ * @ThreadSafe
*/
class Tracked extends Hashtable implements ServiceListener {
static final long serialVersionUID = -7420065199791006079L;
@@ -767,9 +771,11 @@
*
* Since the ArrayList implementation is not synchronized, all access to
* this list must be protected by the same synchronized object for
- * thread safety.
+ * thread-safety.
+ *
+ * @GuardedBy this
*/
- private ArrayList adding;
+ private final ArrayList adding;
/**
* true if the tracked object is closed.
@@ -793,9 +799,11 @@
*
* Since the LinkedList implementation is not synchronized, all access
* to this list must be protected by the same synchronized object for
- * thread safety.
+ * thread-safety.
+ *
+ * @GuardedBy this
*/
- private LinkedList initial;
+ private final LinkedList initial;
/**
* Tracked constructor.
@@ -816,6 +824,7 @@
* addServiceListener call.
*
* @param references The initial list of services to be tracked.
+ * @GuardedBy this
*/
protected void setInitialServices(ServiceReference[] references) {
if (references == null) {
@@ -920,7 +929,7 @@
case ServiceEvent.REGISTERED :
case ServiceEvent.MODIFIED :
if (listenerFilter != null) { // constructor supplied
- // filter
+ // filter
track(reference);
/*
* If the customizer throws an unchecked exception, it
@@ -959,7 +968,7 @@
*
* @param reference Reference to a service to be tracked.
*/
- protected void track(ServiceReference reference) {
+ private void track(ServiceReference reference) {
Object object;
synchronized (this) {
object = this.get(reference);
@@ -1127,6 +1136,7 @@
* This class is used by the ServiceTracker if open is called with true.
*
* @since 1.3
+ * @ThreadSafe
*/
class AllTracked extends Tracked implements AllServiceListener {
static final long serialVersionUID = 4050764875305137716L;
diff --git a/org.osgi.compendium/src/main/java/org/osgi/util/tracker/ServiceTrackerCustomizer.java b/org.osgi.compendium/src/main/java/org/osgi/util/tracker/ServiceTrackerCustomizer.java
index c6f9e20..e091078 100644
--- a/org.osgi.compendium/src/main/java/org/osgi/util/tracker/ServiceTrackerCustomizer.java
+++ b/org.osgi.compendium/src/main/java/org/osgi/util/tracker/ServiceTrackerCustomizer.java
@@ -1,7 +1,7 @@
/*
- * $Header: /cvshome/build/org.osgi.util.tracker/src/org/osgi/util/tracker/ServiceTrackerCustomizer.java,v 1.10 2006/06/16 16:31:13 hargrave Exp $
+ * $Header: /cvshome/build/org.osgi.util.tracker/src/org/osgi/util/tracker/ServiceTrackerCustomizer.java,v 1.13 2007/02/19 19:04:33 hargrave Exp $
*
- * Copyright (c) OSGi Alliance (2000, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2007). 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.
@@ -22,25 +22,32 @@
/**
* The <code>ServiceTrackerCustomizer</code> interface allows a
- * <code>ServiceTracker</code> object to customize the service objects that are
- * tracked. The <code>ServiceTrackerCustomizer</code> object is called when a
- * service is being added to the <code>ServiceTracker</code> object. The
- * <code>ServiceTrackerCustomizer</code> can then return an object for the tracked
- * service. The <code>ServiceTrackerCustomizer</code> object is also called when a
- * tracked service is modified or has been removed from the
+ * <code>ServiceTracker</code> object to customize the service objects that
+ * are tracked. The <code>ServiceTrackerCustomizer</code> object is called
+ * when a service is being added to the <code>ServiceTracker</code> object.
+ * The <code>ServiceTrackerCustomizer</code> can then return an object for the
+ * tracked service. The <code>ServiceTrackerCustomizer</code> object is also
+ * called when a tracked service is modified or has been removed from the
* <code>ServiceTracker</code> object.
*
* <p>
* The methods in this interface may be called as the result of a
- * <code>ServiceEvent</code> being received by a <code>ServiceTracker</code> object.
- * Since <code>ServiceEvent</code> s are synchronously delivered by the Framework,
- * it is highly recommended that implementations of these methods do not
- * register (<code>BundleContext.registerService</code>), modify (
+ * <code>ServiceEvent</code> being received by a <code>ServiceTracker</code>
+ * object. Since <code>ServiceEvent</code> s are synchronously delivered by
+ * the Framework, it is highly recommended that implementations of these methods
+ * do not register (<code>BundleContext.registerService</code>), modify (
* <code>ServiceRegistration.setProperties</code>) or unregister (
* <code>ServiceRegistration.unregister</code>) a service while being
* synchronized on any object.
*
- * @version $Revision: 1.10 $
+ * <p>
+ * The <code>ServiceTracker</code> class is thread-safe. It does not call a
+ * <code>ServiceTrackerCustomizer</code> object while holding any locks.
+ * <code>ServiceTrackerCustomizer</code> implementations must also be
+ * thread-safe.
+ *
+ * @ThreadSafe
+ * @version $Revision: 1.13 $
*/
public interface ServiceTrackerCustomizer {
/**
@@ -48,17 +55,17 @@
*
* <p>
* This method is called before a service which matched the search
- * parameters of the <code>ServiceTracker</code> object is added to it. This
- * method should return the service object to be tracked for this
- * <code>ServiceReference</code> object. The returned service object is stored
- * in the <code>ServiceTracker</code> object and is available from the
- * <code>getService</code> and <code>getServices</code> methods.
+ * parameters of the <code>ServiceTracker</code> object is added to it.
+ * This method should return the service object to be tracked for this
+ * <code>ServiceReference</code> object. The returned service object is
+ * stored in the <code>ServiceTracker</code> object and is available from
+ * the <code>getService</code> and <code>getServices</code> methods.
*
* @param reference Reference to service being added to the
* <code>ServiceTracker</code> object.
* @return The service object to be tracked for the
- * <code>ServiceReference</code> object or <code>null</code> if the
- * <code>ServiceReference</code> object should not be tracked.
+ * <code>ServiceReference</code> object or <code>null</code> if
+ * the <code>ServiceReference</code> object should not be tracked.
*/
public Object addingService(ServiceReference reference);
@@ -73,8 +80,7 @@
* @param reference Reference to service that has been modified.
* @param service The service object for the modified service.
*/
- public void modifiedService(ServiceReference reference,
- Object service);
+ public void modifiedService(ServiceReference reference, Object service);
/**
* A service tracked by the <code>ServiceTracker</code> object has been
@@ -87,6 +93,5 @@
* @param reference Reference to service that has been removed.
* @param service The service object for the removed service.
*/
- public void removedService(ServiceReference reference,
- Object service);
+ public void removedService(ServiceReference reference, Object service);
}
diff --git a/org.osgi.compendium/src/main/java/org/osgi/util/xml/XMLParserActivator.java b/org.osgi.compendium/src/main/java/org/osgi/util/xml/XMLParserActivator.java
index 77ba538..c1e6cd8 100644
--- a/org.osgi.compendium/src/main/java/org/osgi/util/xml/XMLParserActivator.java
+++ b/org.osgi.compendium/src/main/java/org/osgi/util/xml/XMLParserActivator.java
@@ -1,5 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.util.xml/src/org/osgi/util/xml/XMLParserActivator.java,v 1.10 2006/06/21 17:41:20 hargrave Exp $
+ * $Header: /cvshome/build/org.osgi.util.xml/src/org/osgi/util/xml/XMLParserActivator.java,v 1.11 2006/10/27 18:17:06 hargrave Exp $
*
* Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
*
@@ -137,7 +137,6 @@
* bundle is marked as stopped and the Framework will remove this
* bundle's listeners, unregister all services registered by this
* bundle, and release all services used by this bundle.
- * @see Bundle#start
*/
public void start(BundleContext context) throws Exception {
this.context = context;
@@ -159,7 +158,6 @@
}
/**
- * <p>
* This method has nothing to do as all active service registrations will
* automatically get unregistered when the bundle stops.
*
@@ -168,7 +166,6 @@
* bundle is still marked as stopped, and the Framework will remove
* the bundle's listeners, unregister all services registered by the
* bundle, and release all services used by the bundle.
- * @see Bundle#stop
*/
public void stop(BundleContext context) throws Exception {
}