db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rhille...@apache.org
Subject svn commit: r737043 [2/4] - in /db/derby/code/trunk: ./ java/stubs/felix/ java/stubs/felix/org/ java/stubs/felix/org/osgi/ java/stubs/felix/org/osgi/framework/ tools/ant/properties/ tools/ide/netbeans/6.0/nbproject/ tools/java/
Date Fri, 23 Jan 2009 15:05:48 GMT
Added: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleContext.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleContext.java?rev=737043&view=auto
==============================================================================
--- db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleContext.java (added)
+++ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleContext.java Fri Jan 23 07:05:47 2009
@@ -0,0 +1,825 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleContext.java,v 1.22 2007/02/21 16:49:05 hargrave Exp $
+ * 
+ * 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.
+ * 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.framework;
+
+import java.io.File;
+import java.io.InputStream;
+import java.util.Dictionary;
+
+/**
+ * A bundle's execution context within the Framework. The context is used to
+ * grant access to other methods so that this bundle can interact with the
+ * Framework.
+ * 
+ * <p>
+ * <code>BundleContext</code> methods allow a bundle to:
+ * <ul>
+ * <li>Subscribe to events published by the Framework.
+ * <li>Register service objects with the Framework service registry.
+ * <li>Retrieve <code>ServiceReferences</code> from the Framework service
+ * registry.
+ * <li>Get and release service objects for a referenced service.
+ * <li>Install new bundles in the Framework.
+ * <li>Get the list of bundles installed in the Framework.
+ * <li>Get the {@link Bundle} object for a bundle.
+ * <li>Create <code>File</code> objects for files in a persistent storage
+ * area provided for the bundle by the Framework.
+ * </ul>
+ * 
+ * <p>
+ * A <code>BundleContext</code> object will be created and provided to the
+ * bundle associated with this context when it is started using the
+ * {@link BundleActivator#start} method. The same <code>BundleContext</code>
+ * object will be passed to the bundle associated with this context when it is
+ * stopped using the {@link BundleActivator#stop} method. A
+ * <code>BundleContext</code> object is generally for the private use of its
+ * associated bundle and is not meant to be shared with other bundles in the
+ * OSGi environment.
+ * 
+ * <p>
+ * The <code>Bundle</code> object associated with a <code>BundleContext</code>
+ * object is called the <em>context bundle</em>.
+ * 
+ * <p>
+ * The <code>BundleContext</code> object is only valid during the execution of
+ * its context bundle; that is, during the period from when the context bundle
+ * is in the <code>STARTING</code>, <code>STOPPING</code>, and
+ * <code>ACTIVE</code> bundle states. If the <code>BundleContext</code>
+ * object is used subsequently, an <code>IllegalStateException</code> must be
+ * thrown. The <code>BundleContext</code> object must never be reused after
+ * its context bundle is stopped.
+ * 
+ * <p>
+ * The Framework is the only entity that can create <code>BundleContext</code>
+ * objects and they are only valid within the Framework that created them.
+ * 
+ * @ThreadSafe
+ * @version $Revision: 1.22 $
+ */
+
+public interface BundleContext {
+	/**
+	 * Returns the value of the specified property. If the key is not found in
+	 * the Framework properties, the system properties are then searched. The
+	 * method returns <code>null</code> if the property is not found.
+	 * 
+	 * <p>
+	 * The Framework defines the following standard property keys:
+	 * </p>
+	 * <ul>
+	 * <li>{@link Constants#FRAMEWORK_VERSION} - The OSGi Framework version.
+	 * </li>
+	 * <li>{@link Constants#FRAMEWORK_VENDOR} - The Framework implementation
+	 * vendor.</li>
+	 * <li>{@link Constants#FRAMEWORK_LANGUAGE} - The language being used. See
+	 * ISO 639 for possible values.</li>
+	 * <li>{@link Constants#FRAMEWORK_OS_NAME} - The host computer operating
+	 * system.</li>
+	 * <li>{@link Constants#FRAMEWORK_OS_VERSION} - The host computer
+	 * operating system version number.</li>
+	 * <li>{@link Constants#FRAMEWORK_PROCESSOR} - The host computer processor
+	 * name.</li>
+	 * </ul>
+	 * <p>
+	 * All bundles must have permission to read these properties.
+	 * 
+	 * <p>
+	 * Note: The last four standard properties are used by the
+	 * {@link Constants#BUNDLE_NATIVECODE} <code>Manifest</code> header's
+	 * matching algorithm for selecting native language code.
+	 * 
+	 * @param key The name of the requested property.
+	 * @return The value of the requested property, or <code>null</code> if
+	 *         the property is undefined.
+	 * @throws java.lang.SecurityException If the caller does not have the
+	 *         appropriate <code>PropertyPermission</code> to read the
+	 *         property, and the Java Runtime Environment supports permissions.
+	 */
+	public String getProperty(String key);
+
+	/**
+	 * Returns the <code>Bundle</code> object associated with this
+	 * <code>BundleContext</code>. This bundle is called the context bundle.
+	 * 
+	 * @return The <code>Bundle</code> object associated with this
+	 *         <code>BundleContext</code>.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 */
+	public Bundle getBundle();
+
+	/**
+	 * Installs a bundle from the specified location string. A bundle is
+	 * obtained from <code>location</code> as interpreted by the Framework in
+	 * an implementation dependent manner.
+	 * <p>
+	 * Every installed bundle is uniquely identified by its location string,
+	 * typically in the form of a URL.
+	 * 
+	 * <p>
+	 * The following steps are required to install a bundle:
+	 * <ol>
+	 * <li>If a bundle containing the same location string is already
+	 * installed, the <code>Bundle</code> object for that bundle is returned.
+	 * 
+	 * <li>The bundle's content is read from the location string. If this
+	 * fails, a {@link BundleException} is thrown.
+	 * 
+	 * <li>The bundle's <code>Bundle-NativeCode</code> dependencies are
+	 * resolved. If this fails, a <code>BundleException</code> is thrown.
+	 * 
+	 * <li>The bundle's associated resources are allocated. The associated
+	 * resources minimally consist of a unique identifier and a persistent
+	 * storage area if the platform has file system support. If this step fails,
+	 * a <code>BundleException</code> is thrown.
+	 * 
+	 * <li>If the bundle has declared an Bundle-RequiredExecutionEnvironment
+	 * header, then the listed execution environments must be verified against
+	 * the installed execution environments. If none of the listed execution 
+	 * environments match an installed execution environment, a
+	 * <code>BundleException</code> must be thrown.
+	 * 
+	 * <li>The bundle's state is set to <code>INSTALLED</code>.
+	 * 
+	 * <li>A bundle event of type {@link BundleEvent#INSTALLED} is fired.
+	 * 
+	 * <li>The <code>Bundle</code> object for the newly or previously
+	 * installed bundle is returned.
+	 * </ol>
+	 * 
+	 * <b>Postconditions, no exceptions thrown </b>
+	 * <ul>
+	 * <li><code>getState()</code> in {<code>INSTALLED</code>,<code>RESOLVED</code>}.
+	 * <li>Bundle has a unique ID.
+	 * </ul>
+	 * <b>Postconditions, when an exception is thrown </b>
+	 * <ul>
+	 * <li>Bundle is not installed and no trace of the bundle exists.
+	 * </ul>
+	 * 
+	 * @param location The location identifier of the bundle to install.
+	 * @return The <code>Bundle</code> object of the installed bundle.
+	 * @throws BundleException If the installation failed.
+	 * @throws java.lang.SecurityException If the caller does not have the
+	 *         appropriate <code>AdminPermission[installed bundle,LIFECYCLE]</code>, and the
+	 *         Java Runtime Environment supports permissions.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 */
+	public Bundle installBundle(String location)
+			throws BundleException;
+
+	/**
+	 * Installs a bundle from the specified <code>InputStream</code> object.
+	 * 
+	 * <p>
+	 * This method performs all of the steps listed in
+	 * <code>BundleContext.installBundle(String location)</code>, except that
+	 * the bundle's content will be read from the <code>InputStream</code>
+	 * object. The location identifier string specified will be used as the
+	 * identity of the bundle.
+	 * 
+	 * <p>
+	 * This method must always close the <code>InputStream</code> object, even
+	 * if an exception is thrown.
+	 * 
+	 * @param location The location identifier of the bundle to install.
+	 * @param input The <code>InputStream</code> object from which this bundle
+	 *        will be read.
+	 * @return The <code>Bundle</code> object of the installed bundle.
+	 * @throws BundleException If the provided stream cannot be read or the
+	 *         installation failed.
+	 * @throws java.lang.SecurityException If the caller does not have the
+	 *         appropriate <code>AdminPermission[installed bundle,LIFECYCLE]</code>, and the
+	 *         Java Runtime Environment supports permissions.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * @see #installBundle(java.lang.String)
+	 */
+	public Bundle installBundle(String location, InputStream input)
+			throws BundleException;
+
+	/**
+	 * Returns the bundle with the specified identifier.
+	 * 
+	 * @param id The identifier of the bundle to retrieve.
+	 * @return A <code>Bundle</code> object or <code>null</code> if the
+	 *         identifier does not match any installed bundle.
+	 */
+	public Bundle getBundle(long id);
+
+	/**
+	 * Returns a list of all installed bundles.
+	 * <p>
+	 * This method returns a list of all bundles installed in the OSGi
+	 * environment at the time of the call to this method. However, since the
+	 * Framework is a very dynamic environment, bundles can be installed or
+	 * uninstalled at anytime.
+	 * 
+	 * @return An array of <code>Bundle</code> objects, one object per
+	 *         installed bundle.
+	 */
+	public Bundle[] getBundles();
+
+	/**
+	 * Adds the specified <code>ServiceListener</code> object with the
+	 * specified <code>filter</code> to the context bundle's list of
+	 * listeners. See {@link Filter} for a description of the filter syntax.
+	 * <code>ServiceListener</code> objects are notified when a service has a
+	 * lifecycle state change.
+	 * 
+	 * <p>
+	 * If the context bundle's list of listeners already contains a listener
+	 * <code>l</code> such that <code>(l==listener)</code>, then this
+	 * method replaces that listener's filter (which may be <code>null</code>)
+	 * with the specified one (which may be <code>null</code>).
+	 * 
+	 * <p>
+	 * The listener is called if the filter criteria is met. To filter based
+	 * upon the class of the service, the filter should reference the
+	 * {@link Constants#OBJECTCLASS} property. If <code>filter</code> is
+	 * <code>null</code>, all services are considered to match the filter.
+	 * 
+	 * <p>
+	 * When using a <code>filter</code>, it is possible that the
+	 * <code>ServiceEvent</code>s for the complete lifecycle of a service
+	 * will not be delivered to the listener. For example, if the
+	 * <code>filter</code> only matches when the property <code>x</code> has
+	 * the value <code>1</code>, the listener will not be called if the
+	 * service is registered with the property <code>x</code> not set to the
+	 * value <code>1</code>. Subsequently, when the service is modified
+	 * setting property <code>x</code> to the value <code>1</code>, the
+	 * filter will match and the listener will be called with a
+	 * <code>ServiceEvent</code> of type <code>MODIFIED</code>. Thus, the
+	 * listener will not be called with a <code>ServiceEvent</code> of type
+	 * <code>REGISTERED</code>.
+	 * 
+	 * <p>
+	 * If the Java Runtime Environment supports permissions, the
+	 * <code>ServiceListener</code> object will be notified of a service event
+	 * only if the bundle that is registering it has the
+	 * <code>ServicePermission</code> to get the service using at least one of
+	 * the named classes the service was registered under.
+	 * 
+	 * @param listener The <code>ServiceListener</code> object to be added.
+	 * @param filter The filter criteria.
+	 * 
+	 * @throws InvalidSyntaxException If <code>filter</code> contains an
+	 *         invalid filter string that cannot be parsed.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * 
+	 * @see ServiceEvent
+	 * @see ServiceListener
+	 * @see ServicePermission
+	 */
+	public void addServiceListener(ServiceListener listener,
+			String filter) throws InvalidSyntaxException;
+
+	/**
+	 * Adds the specified <code>ServiceListener</code> object to the context
+	 * bundle's list of listeners.
+	 * 
+	 * <p>
+	 * This method is the same as calling
+	 * <code>BundleContext.addServiceListener(ServiceListener listener,
+	 * String filter)</code>
+	 * with <code>filter</code> set to <code>null</code>.
+	 * 
+	 * @param listener The <code>ServiceListener</code> object to be added.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * 
+	 * @see #addServiceListener(ServiceListener, String)
+	 */
+	public void addServiceListener(ServiceListener listener);
+
+	/**
+	 * Removes the specified <code>ServiceListener</code> object from the
+	 * context bundle's list of listeners.
+	 * 
+	 * <p>
+	 * If <code>listener</code> is not contained in this context bundle's list
+	 * of listeners, this method does nothing.
+	 * 
+	 * @param listener The <code>ServiceListener</code> to be removed.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 */
+	public void removeServiceListener(ServiceListener listener);
+
+	/**
+	 * Adds the specified <code>BundleListener</code> object to the context
+	 * bundle's list of listeners if not already present. BundleListener objects
+	 * are notified when a bundle has a lifecycle state change.
+	 * 
+	 * <p>
+	 * If the context bundle's list of listeners already contains a listener
+	 * <code>l</code> such that <code>(l==listener)</code>, this method
+	 * does nothing.
+	 * 
+	 * @param listener The <code>BundleListener</code> to be added.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * @throws java.lang.SecurityException If listener is a
+	 *         <code>SynchronousBundleListener</code> and the caller does not
+	 *         have the appropriate <code>AdminPermission[context bundle,LISTENER]</code>,
+	 *         and the Java Runtime Environment supports permissions.
+	 * 
+	 * @see BundleEvent
+	 * @see BundleListener
+	 */
+	public void addBundleListener(BundleListener listener);
+
+	/**
+	 * Removes the specified <code>BundleListener</code> object from the
+	 * context bundle's list of listeners.
+	 * 
+	 * <p>
+	 * If <code>listener</code> is not contained in the context bundle's list
+	 * of listeners, this method does nothing.
+	 * 
+	 * @param listener The <code>BundleListener</code> object to be removed.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * @throws java.lang.SecurityException If listener is a
+	 *         <code>SynchronousBundleListener</code> and the caller does not
+	 *         have the appropriate <code>AdminPermission[context bundle,LISTENER]</code>,
+	 *         and the Java Runtime Environment supports permissions.
+	 */
+	public void removeBundleListener(BundleListener listener);
+
+	/**
+	 * Adds the specified <code>FrameworkListener</code> object to the context
+	 * bundle's list of listeners if not already present. FrameworkListeners are
+	 * notified of general Framework events.
+	 * 
+	 * <p>
+	 * If the context bundle's list of listeners already contains a listener
+	 * <code>l</code> such that <code>(l==listener)</code>, this method
+	 * does nothing.
+	 * 
+	 * @param listener The <code>FrameworkListener</code> object to be added.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * 
+	 * @see FrameworkEvent
+	 * @see FrameworkListener
+	 */
+	public void addFrameworkListener(FrameworkListener listener);
+
+	/**
+	 * Removes the specified <code>FrameworkListener</code> object from the
+	 * context bundle's list of listeners.
+	 * 
+	 * <p>
+	 * If <code>listener</code> is not contained in the context bundle's list
+	 * of listeners, this method does nothing.
+	 * 
+	 * @param listener The <code>FrameworkListener</code> object to be
+	 *        removed.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 */
+	public void removeFrameworkListener(FrameworkListener listener);
+
+	/**
+	 * Registers the specified service object with the specified properties
+	 * under the specified class names into the Framework. A
+	 * <code>ServiceRegistration</code> object is returned. The
+	 * <code>ServiceRegistration</code> object is for the private use of the
+	 * bundle registering the service and should not be shared with other
+	 * bundles. The registering bundle is defined to be the context bundle.
+	 * Other bundles can locate the service by using either the
+	 * {@link #getServiceReferences} or {@link #getServiceReference} method.
+	 * 
+	 * <p>
+	 * A bundle can register a service object that implements the
+	 * {@link ServiceFactory} interface to have more flexibility in providing
+	 * service objects to other 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 Constants#SERVICE_ID} identifying the registration number of
+	 * the service and a property named {@link 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 other bundles.
+	 * <li>A service event of type {@link ServiceEvent#REGISTERED} is
+	 * fired.
+	 * <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 Constants#OBJECTCLASS}.
+	 * @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 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 ServiceRegistration#setProperties} method must be called.
+	 *        The set of properties may be <code>null</code> if the service
+	 *        has no properties.
+	 * 
+	 * @return A <code>ServiceRegistration</code> object for use by the bundle
+	 *         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 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 BundleContext is no
+	 *         longer valid.
+	 * 
+	 * @see ServiceRegistration
+	 * @see 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.
+	 * @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 bundle
+	 *         registering the service to update the service's properties or to
+	 *         unregister the service.
+	 *         
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * @see #registerService(java.lang.String[], java.lang.Object,
+	 *      java.util.Dictionary)
+	 */
+	public ServiceRegistration registerService(String clazz,
+			Object service, Dictionary properties);
+
+	/**
+	 * Returns an array of <code>ServiceReference</code> objects. The returned
+	 * array of <code>ServiceReference</code> objects contains services that
+	 * were registered under the specified class, match the specified filter
+	 * criteria, and the packages for the class names under which the services
+	 * were registered match the context bundle's packages as defined in
+	 * {@link ServiceReference#isAssignableTo(Bundle, String)}.
+	 * 
+	 * <p>
+	 * The list is valid at the time of the call to this method, however since
+	 * the Framework is a very dynamic environment, services can be modified or
+	 * unregistered at anytime.
+	 * 
+	 * <p>
+	 * <code>filter</code> is used to select the registered service whose
+	 * properties objects contain keys and values which satisfy the filter. See
+	 * {@link Filter} for a description of the filter string syntax.
+	 * 
+	 * <p>
+	 * If <code>filter</code> is <code>null</code>, all registered services
+	 * are considered to match the filter. If <code>filter</code> cannot be
+	 * parsed, an {@link InvalidSyntaxException} will be thrown with a human
+	 * readable message where the filter became unparsable.
+	 * 
+	 * <p>
+	 * The following steps are required to select a set of
+	 * <code>ServiceReference</code> objects:
+	 * <ol>
+	 * <li>If the filter string is not <code>null</code>, the filter string
+	 * is parsed and the set <code>ServiceReference</code> objects of
+	 * registered services that satisfy the filter is produced. If the filter
+	 * string is <code>null</code>, then all registered services are
+	 * considered to satisfy the filter.
+	 * <li>If the Java Runtime Environment supports permissions, the set of
+	 * <code>ServiceReference</code> objects produced by the previous step is
+	 * reduced by checking that the caller has the
+	 * <code>ServicePermission</code> to get at least one of the class names
+	 * under which the service was registered. If the caller does not have the
+	 * correct permission for a particular <code>ServiceReference</code>
+	 * object, then it is removed from the set.
+	 * <li>If <code>clazz</code> is not <code>null</code>, the set is
+	 * further reduced to those services that are an <code>instanceof</code>
+	 * and were registered under the specified class. The complete list of
+	 * classes of which a service is an instance and which were specified when
+	 * the service was registered is available from the service's
+	 * {@link Constants#OBJECTCLASS} property.
+	 * <li>The set is reduced one final time by cycling through each
+	 * <code>ServiceReference</code> object and calling
+	 * {@link ServiceReference#isAssignableTo(Bundle, String)} with the context
+	 * bundle and each class name under which the <code>ServiceReference</code>
+	 * object was registered. For any given <code>ServiceReference</code>
+	 * object, if any call to
+	 * {@link ServiceReference#isAssignableTo(Bundle, String)} returns
+	 * <code>false</code>, then it is removed from the set of
+	 * <code>ServiceReference</code> objects.
+	 * <li>An array of the remaining <code>ServiceReference</code> objects is
+	 * returned.
+	 * </ol>
+	 * 
+	 * @param clazz The class name with which the service was registered or
+	 *        <code>null</code> for all services.
+	 * @param filter The filter criteria.
+	 * @return An array of <code>ServiceReference</code> objects or
+	 *         <code>null</code> if no services are registered which satisfy
+	 *         the search.
+	 * @throws InvalidSyntaxException If <code>filter</code> contains an
+	 *         invalid filter string that cannot be parsed.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 */
+	public ServiceReference[] getServiceReferences(String clazz,
+			String filter) throws InvalidSyntaxException;
+
+	/**
+	 * Returns an array of <code>ServiceReference</code> objects. The returned
+	 * array of <code>ServiceReference</code> objects contains services that
+	 * were registered under the specified class and match the specified filter
+	 * criteria.
+	 * 
+	 * <p>
+	 * The list is valid at the time of the call to this method, however since
+	 * the Framework is a very dynamic environment, services can be modified or
+	 * unregistered at anytime.
+	 * 
+	 * <p>
+	 * <code>filter</code> is used to select the registered service whose
+	 * properties objects contain keys and values which satisfy the filter. See
+	 * {@link Filter} for a description of the filter string syntax.
+	 * 
+	 * <p>
+	 * If <code>filter</code> is <code>null</code>, all registered services
+	 * are considered to match the filter. If <code>filter</code> cannot be
+	 * parsed, an {@link InvalidSyntaxException} will be thrown with a human
+	 * readable message where the filter became unparsable.
+	 * 
+	 * <p>
+	 * The following steps are required to select a set of
+	 * <code>ServiceReference</code> objects:
+	 * <ol>
+	 * <li>If the filter string is not <code>null</code>, the filter string
+	 * is parsed and the set <code>ServiceReference</code> objects of
+	 * registered services that satisfy the filter is produced. If the filter
+	 * string is <code>null</code>, then all registered services are
+	 * considered to satisfy the filter.
+	 * <li>If the Java Runtime Environment supports permissions, the set of
+	 * <code>ServiceReference</code> objects produced by the previous step is
+	 * reduced by checking that the caller has the
+	 * <code>ServicePermission</code> to get at least one of the class names
+	 * under which the service was registered. If the caller does not have the
+	 * correct permission for a particular <code>ServiceReference</code>
+	 * object, then it is removed from the set.
+	 * <li>If <code>clazz</code> is not <code>null</code>, the set is
+	 * further reduced to those services that are an <code>instanceof</code>
+	 * and were registered under the specified class. The complete list of
+	 * classes of which a service is an instance and which were specified when
+	 * the service was registered is available from the service's
+	 * {@link Constants#OBJECTCLASS} property.
+	 * <li>An array of the remaining <code>ServiceReference</code> objects is
+	 * returned.
+	 * </ol>
+	 * 
+	 * @param clazz The class name with which the service was registered or
+	 *        <code>null</code> for all services.
+	 * @param filter The filter criteria.
+	 * @return An array of <code>ServiceReference</code> objects or
+	 *         <code>null</code> if no services are registered which satisfy
+	 *         the search.
+	 * @throws InvalidSyntaxException If <code>filter</code> contains an
+	 *         invalid filter string that cannot be parsed.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * @since 1.3
+	 */
+	public ServiceReference[] getAllServiceReferences(String clazz,
+			String filter) throws InvalidSyntaxException;
+
+	/**
+	 * Returns a <code>ServiceReference</code> object for a service that
+	 * implements and was registered under the specified class.
+	 * 
+	 * <p>
+	 * This <code>ServiceReference</code> object is valid at the time of the
+	 * call to this method, however as the Framework is a very dynamic
+	 * environment, services can be modified or unregistered at anytime.
+	 * 
+	 * <p>
+	 * This method is the same as calling
+	 * {@link BundleContext#getServiceReferences(String, String)} with a
+	 * <code>null</code> filter string. It is provided as a convenience for
+	 * when the caller is interested in any service that implements the
+	 * specified class.
+	 * <p>
+	 * If multiple such services exist, the service with the highest ranking (as
+	 * specified in its {@link Constants#SERVICE_RANKING} property) is returned.
+	 * <p>
+	 * If there is a tie in ranking, the service with the lowest service ID (as
+	 * specified in its {@link Constants#SERVICE_ID} property); that is, the
+	 * service that was registered first is returned.
+	 * 
+	 * @param clazz The class name with which the service was registered.
+	 * @return A <code>ServiceReference</code> object, or <code>null</code>
+	 *         if no services are registered which implement the named class.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * @see #getServiceReferences(String, String)
+	 */
+	public ServiceReference getServiceReference(String clazz);
+
+	/**
+	 * Returns the specified service object for a service.
+	 * <p>
+	 * A bundle's use of a service is tracked by the bundle's use count of that
+	 * service. Each time a service's service object is returned by
+	 * {@link #getService(ServiceReference)} the context bundle's use count for
+	 * that service is incremented by one. Each time the service is released by
+	 * {@link #ungetService(ServiceReference)} the context bundle's use count
+	 * for that service is decremented by one.
+	 * <p>
+	 * When a bundle's use count for a service drops to zero, the bundle should
+	 * no longer use that service.
+	 * 
+	 * <p>
+	 * This method will always return <code>null</code> when the service
+	 * associated with this <code>reference</code> has been unregistered.
+	 * 
+	 * <p>
+	 * The following steps are required to get the service object:
+	 * <ol>
+	 * <li>If the service has been unregistered, <code>null</code> is
+	 * returned.
+	 * <li>The context bundle's use count for this service is incremented by
+	 * one.
+	 * <li>If the context bundle's use count for the service is currently one
+	 * and the service was registered with an object implementing the
+	 * <code>ServiceFactory</code> interface, the
+	 * {@link ServiceFactory#getService(Bundle, ServiceRegistration)} method is
+	 * called to create a service object for the context bundle. This service
+	 * object is cached by the Framework. While the context bundle's use count
+	 * for the service is greater than zero, subsequent calls to get the
+	 * services's service object for the context bundle will return the cached
+	 * service object. <br>
+	 * If the service object returned by the <code>ServiceFactory</code>
+	 * object is not an <code>instanceof</code> all the classes named when the
+	 * service was registered or the <code>ServiceFactory</code> object throws
+	 * an exception, <code>null</code> is returned and a Framework event of
+	 * type {@link FrameworkEvent#ERROR} is fired.
+	 * <li>The service object for the service is returned.
+	 * </ol>
+	 * 
+	 * @param reference A reference to the service.
+	 * @return A service object for the service associated with
+	 *         <code>reference</code> or <code>null</code> if the service is
+	 *         not registered or does not implement the classes under which it
+	 *         was registered in the case of a <code>ServiceFactory</code>.
+	 * @throws java.lang.SecurityException If the caller does not have the
+	 *         <code>ServicePermission</code> to get the service using at
+	 *         least one of the named classes the service was registered under
+	 *         and the Java Runtime Environment supports permissions.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * @see #ungetService(ServiceReference)
+	 * @see ServiceFactory
+	 */
+	public Object getService(ServiceReference reference);
+
+	/**
+	 * Releases the service object referenced by the specified
+	 * <code>ServiceReference</code> object. If the context bundle's use count
+	 * for the service is zero, this method returns <code>false</code>.
+	 * Otherwise, the context bundle's use count for the service is decremented
+	 * by one.
+	 * 
+	 * <p>
+	 * The service's service object should no longer be used and all references
+	 * to it should be destroyed when a bundle's use count for the service drops
+	 * to zero.
+	 * 
+	 * <p>
+	 * The following steps are required to unget the service object:
+	 * <ol>
+	 * <li>If the context bundle's use count for the service is zero or the
+	 * service has been unregistered, <code>false</code> is returned.
+	 * <li>The context bundle's use count for this service is decremented by
+	 * one.
+	 * <li>If the context bundle's use count for the service is currently zero
+	 * and the service was registered with a <code>ServiceFactory</code>
+	 * object, the
+	 * {@link ServiceFactory#ungetService(Bundle, ServiceRegistration, Object)}
+	 * method is called to release the service object for the context bundle.
+	 * <li><code>true</code> is returned.
+	 * </ol>
+	 * 
+	 * @param reference A reference to the service to be released.
+	 * @return <code>false</code> if the context bundle's use count for the
+	 *         service is zero or if the service has been unregistered;
+	 *         <code>true</code> otherwise.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * @see #getService
+	 * @see ServiceFactory
+	 */
+	public boolean ungetService(ServiceReference reference);
+
+	/**
+	 * Creates a <code>File</code> object for a file in the persistent storage
+	 * area provided for the bundle by the Framework. This method will return
+	 * <code>null</code> if the platform does not have file system support.
+	 * 
+	 * <p>
+	 * A <code>File</code> object for the base directory of the persistent
+	 * storage area provided for the context bundle by the Framework can be
+	 * obtained by calling this method with an empty string as
+	 * <code>filename</code>.
+	 * 
+	 * <p>
+	 * If the Java Runtime Environment supports permissions, the Framework will
+	 * ensure that the bundle has the <code>java.io.FilePermission</code> with
+	 * actions <code>read</code>,<code>write</code>,<code>delete</code>
+	 * for all files (recursively) in the persistent storage area provided for
+	 * the context bundle.
+	 * 
+	 * @param filename A relative name to the file to be accessed.
+	 * @return A <code>File</code> object that represents the requested file
+	 *         or <code>null</code> if the platform does not have file system
+	 *         support.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 */
+	public File getDataFile(String filename);
+
+	/**
+	 * Creates a <code>Filter</code> object. This <code>Filter</code> object
+	 * may be used to match a <code>ServiceReference</code> object or a
+	 * <code>Dictionary</code> object.
+	 * 
+	 * <p>
+	 * If the filter cannot be parsed, an {@link InvalidSyntaxException} will be
+	 * thrown with a human readable message where the filter became unparsable.
+	 * 
+	 * @param filter The filter string.
+	 * @return A <code>Filter</code> object encapsulating the filter string.
+	 * @throws InvalidSyntaxException If <code>filter</code> contains an
+	 *         invalid filter string that cannot be parsed.
+	 * @throws NullPointerException If <code>filter</code> is null.
+	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         longer valid.
+	 * 
+	 * @since 1.1
+	 * @see "Framework specification for a description of the filter string syntax."
+	 * @see FrameworkUtil#createFilter(String)
+	 */
+	public Filter createFilter(String filter)
+			throws InvalidSyntaxException;
+}

Propchange: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleContext.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleEvent.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleEvent.java?rev=737043&view=auto
==============================================================================
--- db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleEvent.java (added)
+++ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleEvent.java Fri Jan 23 07:05:47 2009
@@ -0,0 +1,217 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleEvent.java,v 1.19 2007/02/20 00:14:12 hargrave Exp $
+ * 
+ * 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.
+ * 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.framework;
+
+import java.util.EventObject;
+
+/**
+ * An event from the Framework describing a bundle lifecycle change.
+ * <p>
+ * <code>BundleEvent</code> objects are delivered to
+ * <code>SynchronousBundleListener</code>s and <code>BundleListener</code>s
+ * when a change occurs in a bundle's lifecycle. A type code is used to identify
+ * the event type for future extendability.
+ * 
+ * <p>
+ * OSGi Alliance reserves the right to extend the set of types.
+ * 
+ * @Immutable
+ * @see BundleListener
+ * @see SynchronousBundleListener
+ * @version $Revision: 1.19 $
+ */
+
+public class BundleEvent extends EventObject {
+	static final long		serialVersionUID	= 4080640865971756012L;
+	/**
+	 * Bundle that had a change occur in its lifecycle.
+	 */
+	private final Bundle	bundle;
+
+	/**
+	 * Type of bundle lifecycle change.
+	 */
+	private final int		type;
+
+	/**
+	 * The bundle has been installed.
+	 * <p>
+	 * The value of <code>INSTALLED</code> is 0x00000001.
+	 * 
+	 * @see BundleContext#installBundle(String)
+	 */
+	public final static int	INSTALLED			= 0x00000001;
+
+	/**
+	 * The bundle has been started.
+	 * <p>
+	 * The bundle's
+	 * {@link BundleActivator#start(BundleContext) BundleActivator start} method
+	 * has been executed if the bundle has a bundle activator class.
+	 * <p>
+	 * The value of <code>STARTED</code> is 0x00000002.
+	 * 
+	 * @see Bundle#start()
+	 */
+	public final static int	STARTED				= 0x00000002;
+
+	/**
+	 * The bundle has been stopped.
+	 * <p>
+	 * The bundle's
+	 * {@link BundleActivator#stop(BundleContext) BundleActivator stop} method
+	 * has been executed if the bundle has a bundle activator class.
+	 * <p>
+	 * The value of <code>STOPPED</code> is 0x00000004.
+	 * 
+	 * @see Bundle#stop()
+	 */
+	public final static int	STOPPED				= 0x00000004;
+
+	/**
+	 * The bundle has been updated.
+	 * <p>
+	 * The value of <code>UPDATED</code> is 0x00000008.
+	 * 
+	 * @see Bundle#update()
+	 */
+	public final static int	UPDATED				= 0x00000008;
+
+	/**
+	 * The bundle has been uninstalled.
+	 * <p>
+	 * The value of <code>UNINSTALLED</code> is 0x00000010.
+	 * 
+	 * @see Bundle#uninstall
+	 */
+	public final static int	UNINSTALLED			= 0x00000010;
+
+	/**
+	 * The bundle has been resolved.
+	 * <p>
+	 * The value of <code>RESOLVED</code> is 0x00000020.
+	 * 
+	 * @see Bundle#RESOLVED
+	 * @since 1.3
+	 */
+	public final static int	RESOLVED			= 0x00000020;
+
+	/**
+	 * The bundle has been unresolved.
+	 * <p>
+	 * The value of <code>UNRESOLVED</code> is 0x00000040.
+	 * 
+	 * @see Bundle#INSTALLED
+	 * @since 1.3
+	 */
+	public final static int	UNRESOLVED			= 0x00000040;
+
+	/**
+	 * The bundle is about to be activated.
+	 * <p>
+	 * The bundle's
+	 * {@link BundleActivator#start(BundleContext) BundleActivator start} method
+	 * is about to be called if the bundle has a bundle activator class. This
+	 * event is only delivered to {@link SynchronousBundleListener}s. It is not
+	 * delivered to <code>BundleListener</code>s.
+	 * <p>
+	 * The value of <code>STARTING</code> is 0x00000080.
+	 * 
+	 * @see Bundle#start()
+	 * @since 1.3
+	 */
+	public final static int	STARTING			= 0x00000080;
+
+	/**
+	 * The bundle is about to deactivated.
+	 * <p>
+	 * The bundle's
+	 * {@link BundleActivator#stop(BundleContext) BundleActivator stop} method
+	 * is about to be called if the bundle has a bundle activator class. This
+	 * event is only delivered to {@link SynchronousBundleListener}s. It is not
+	 * delivered to <code>BundleListener</code>s.
+	 * <p>
+	 * The value of <code>STOPPING</code> is 0x00000100.
+	 * 
+	 * @see Bundle#stop()
+	 * @since 1.3
+	 */
+	public final static int	STOPPING			= 0x00000100;
+
+	/**
+	 * The bundle will be lazily activated.
+	 * <p>
+	 * The bundle has a {@link Constants#ACTIVATION_LAZY lazy activation policy}
+	 * and is waiting to be activated. It is now in the
+	 * {@link Bundle#STARTING STARTING} state and has a valid
+	 * <code>BundleContext</code>. This event is only delivered to
+	 * {@link SynchronousBundleListener}s. It is not delivered to
+	 * <code>BundleListener</code>s.
+	 * <p>
+	 * The value of <code>LAZY_ACTIVATION</code> is 0x00000200.
+	 * 
+	 * @since 1.4
+	 */
+	public final static int	LAZY_ACTIVATION		= 0x00000200;
+
+	/**
+	 * Creates a bundle event of the specified type.
+	 * 
+	 * @param type The event type.
+	 * @param bundle The bundle which had a lifecycle change.
+	 */
+
+	public BundleEvent(int type, Bundle bundle) {
+		super(bundle);
+		this.bundle = bundle;
+		this.type = type;
+	}
+
+	/**
+	 * Returns the bundle which had a lifecycle change. This bundle is the
+	 * source of the event.
+	 * 
+	 * @return The bundle that had a change occur in its lifecycle.
+	 */
+	public Bundle getBundle() {
+		return bundle;
+	}
+
+	/**
+	 * Returns the type of lifecyle event. The type values are:
+	 * <ul>
+	 * <li>{@link #INSTALLED}
+	 * <li>{@link #RESOLVED}
+	 * <li>{@link #LAZY_ACTIVATION}
+	 * <li>{@link #STARTING}
+	 * <li>{@link #STARTED}
+	 * <li>{@link #STOPPING}
+	 * <li>{@link #STOPPED}
+	 * <li>{@link #UPDATED}
+	 * <li>{@link #UNRESOLVED}
+	 * <li>{@link #UNINSTALLED}
+	 * </ul>
+	 * 
+	 * @return The type of lifecycle event.
+	 */
+
+	public int getType() {
+		return type;
+	}
+}

Propchange: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleEvent.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleException.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleException.java?rev=737043&view=auto
==============================================================================
--- db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleException.java (added)
+++ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleException.java Fri Jan 23 07:05:47 2009
@@ -0,0 +1,106 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleException.java,v 1.15 2006/07/11 13:15:54 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2000, 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.framework;
+
+/**
+ * A Framework exception used to indicate that a bundle lifecycle problem
+ * occurred.
+ * 
+ * <p>
+ * <code>BundleException</code> object is created by the Framework to denote
+ * an exception condition in the lifecycle of a bundle.
+ * <code>BundleException</code>s should not be created by bundle developers.
+ * 
+ * <p>
+ * This exception is updated to conform to the general purpose exception
+ * chaining mechanism.
+ * 
+ * @version $Revision: 1.15 $
+ */
+
+public class BundleException extends Exception {
+	static final long	serialVersionUID	= 3571095144220455665L;
+	/**
+	 * Nested exception.
+	 */
+	private final Throwable	cause;
+
+	/**
+	 * Creates a <code>BundleException</code> that wraps another exception.
+	 * 
+	 * @param msg The associated message.
+	 * @param cause The cause of this exception.
+	 */
+	public BundleException(String msg, Throwable cause) {
+		super(msg);
+		this.cause = cause;
+	}
+
+	/**
+	 * Creates a <code>BundleException</code> object with the specified
+	 * message.
+	 * 
+	 * @param msg The message.
+	 */
+	public BundleException(String msg) {
+		super(msg);
+		this.cause = null;
+	}
+
+	/**
+	 * Returns any nested exceptions included in this exception.
+	 * 
+	 * <p>
+	 * This method predates the general purpose exception chaining mechanism.
+	 * The {@link #getCause()} method is now the preferred means of obtaining
+	 * this information.
+	 * 
+	 * @return The nested exception; <code>null</code> if there is no nested
+	 *         exception.
+	 */
+	public Throwable getNestedException() {
+		return cause;
+	}
+
+	/**
+	 * Returns the cause of this exception or <code>null</code> if no cause
+	 * was specified when this exception was created.
+	 * 
+	 * @return The cause of this exception or <code>null</code> if no cause
+	 *         was specified.
+	 * @since 1.3
+	 */
+	public Throwable getCause() {
+		return cause;
+	}
+
+	/**
+	 * The cause of this exception can only be set when constructed.
+	 * 
+	 * @param cause Cause of the exception.
+	 * @return This object.
+	 * @throws java.lang.IllegalStateException This method will always throw an
+	 *         <code>IllegalStateException</code> since the cause of this
+	 *         exception can only be set when constructed.
+	 * @since 1.3
+	 */
+	public Throwable initCause(Throwable cause) {
+		throw new IllegalStateException();
+	}
+}

Propchange: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleException.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleListener.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleListener.java?rev=737043&view=auto
==============================================================================
--- db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleListener.java (added)
+++ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleListener.java Fri Jan 23 07:05:47 2009
@@ -0,0 +1,49 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleListener.java,v 1.13 2007/02/21 16:49:05 hargrave Exp $
+ * 
+ * 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.
+ * 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.framework;
+
+import java.util.EventListener;
+
+/**
+ * A <code>BundleEvent</code> listener. <code>BundleListener</code> is a
+ * listener interface that may be implemented by a bundle developer. When a
+ * <code>BundleEvent</code> is fired, it is asynchronously delivered to a
+ * <code>BundleListener</code>. The Framework delivers
+ * <code>BundleEvent</code> objects to a <code>BundleListener</code> in
+ * order and must not concurrently call a <code>BundleListener</code>.
+ * <p>
+ * A <code>BundleListener</code> object is registered with the Framework using
+ * the {@link BundleContext#addBundleListener} method.
+ * <code>BundleListener</code>s are called with a <code>BundleEvent</code>
+ * object when a bundle has been installed, resolved, started, stopped, updated,
+ * unresolved, or uninstalled.
+ * 
+ * @see BundleEvent
+ * @NotThreadSafe
+ * @version $Revision: 1.13 $
+ */
+
+public interface BundleListener extends EventListener {
+	/**
+	 * Receives notification that a bundle has had a lifecycle change.
+	 * 
+	 * @param event The <code>BundleEvent</code>.
+	 */
+	public void bundleChanged(BundleEvent event);
+}

Propchange: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleListener.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundlePermission.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundlePermission.java?rev=737043&view=auto
==============================================================================
--- db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundlePermission.java (added)
+++ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundlePermission.java Fri Jan 23 07:05:47 2009
@@ -0,0 +1,584 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundlePermission.java,v 1.16 2007/02/20 00:06:02 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2004, 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.framework;
+
+import java.io.IOException;
+import java.security.*;
+import java.util.Enumeration;
+import java.util.Hashtable;
+
+/**
+ * A bundle's authority to require or provide a bundle or to receive or attach
+ * fragments.
+ * 
+ * <p>
+ * A bundle symbolic name defines a unique fully qualified name.
+ * <p>
+ * For example:
+ * 
+ * <pre>
+ * <code>
+ * org.osgi.example.bundle
+ * </code>
+ * </pre>
+ * 
+ * <p>
+ * <code>BundlePermission</code> has four actions: <code>PROVIDE</code>,
+ * <code>REQUIRE</code>,<code>HOST</code>, and <code>FRAGMENT</code>.
+ * The <code>PROVIDE</code> action implies the <code>REQUIRE</code> action.
+ * 
+ * @since 1.3
+ * @version $Revision: 1.16 $
+ */
+
+public final class BundlePermission extends BasicPermission {
+
+	private static final long	serialVersionUID	= 3257846601685873716L;
+
+	/**
+	 * The action string <code>provide</code>.
+	 */
+	public final static String	PROVIDE				= "provide";
+
+	/**
+	 * The action string <code>require</code>.
+	 */
+	public final static String	REQUIRE				= "require";
+
+	/**
+	 * The action string <code>host</code>.
+	 */
+	public final static String	HOST				= "host";
+
+	/**
+	 * The action string <code>fragment</code>.
+	 */
+	public final static String	FRAGMENT			= "fragment";
+
+	private final static int	ACTION_PROVIDE		= 0x00000001;
+	private final static int	ACTION_REQUIRE		= 0x00000002;
+	private final static int	ACTION_HOST			= 0x00000004;
+	private final static int	ACTION_FRAGMENT		= 0x00000008;
+	private final static int	ACTION_ALL			= ACTION_PROVIDE
+															| ACTION_REQUIRE
+															| ACTION_HOST
+															| ACTION_FRAGMENT;
+	private final static int	ACTION_NONE			= 0;
+	/**
+	 * The actions mask.
+	 */
+	private transient int		action_mask			= ACTION_NONE;
+
+	/**
+	 * The actions in canonical form.
+	 * 
+	 * @serial
+	 */
+	private String				actions				= null;
+
+	/**
+	 * Defines the authority to provide and/or require and or specify a host
+	 * fragment symbolic name within the OSGi environment.
+	 * <p>
+	 * Bundle Permissions are granted over all possible versions of a bundle.
+	 * 
+	 * A bundle that needs to provide a bundle must have the appropriate
+	 * <code>BundlePermission</code> for the symbolic name; a bundle that
+	 * requires a bundle must have the appropriate <code>BundlePermssion</code>
+	 * for that symbolic name; a bundle that specifies a fragment host must have
+	 * the appropriate <code>BundlePermission</code> for that symbolic name.
+	 * 
+	 * @param symbolicName the bundle symbolic name.
+	 * @param actions <code>PROVIDE</code>,<code>REQUIRE</code>,
+	 *        <code>HOST</code>,<code>FRAGMENT</code> (canonical order).
+	 */
+
+	public BundlePermission(String symbolicName, String actions) {
+		this(symbolicName, getMask(actions));
+	}
+
+	/**
+	 * Bundle private constructor used by BundlePermissionCollection.
+	 * 
+	 * @param symbolicName the bundle symbolic name
+	 * @param mask the action mask
+	 */
+	BundlePermission(String symbolicName, int mask) {
+		super(symbolicName);
+		init(mask);
+	}
+
+	/**
+	 * Called by constructors and when deserialized.
+	 * 
+	 * @param mask
+	 */
+	private void init(int mask) {
+		if ((mask == ACTION_NONE) || ((mask & ACTION_ALL) != mask)) {
+			throw new IllegalArgumentException("invalid action string");
+		}
+
+		action_mask = mask;
+	}
+
+	/**
+	 * Parse action string into action mask.
+	 * 
+	 * @param actions Action string.
+	 * @return action mask.
+	 */
+	private static int getMask(String actions) {
+		boolean seencomma = false;
+
+		int mask = ACTION_NONE;
+
+		if (actions == null) {
+			return (mask);
+		}
+
+		char[] a = actions.toCharArray();
+
+		int i = a.length - 1;
+		if (i < 0)
+			return (mask);
+
+		while (i != -1) {
+			char c;
+
+			// skip whitespace
+			while ((i != -1)
+					&& ((c = a[i]) == ' ' || c == '\r' || c == '\n'
+							|| c == '\f' || c == '\t'))
+				i--;
+
+			// check for the known strings
+			int matchlen;
+
+			if (i >= 6 && (a[i - 6] == 'p' || a[i - 6] == 'P')
+					&& (a[i - 5] == 'r' || a[i - 5] == 'R')
+					&& (a[i - 4] == 'o' || a[i - 4] == 'O')
+					&& (a[i - 3] == 'v' || a[i - 3] == 'V')
+					&& (a[i - 2] == 'i' || a[i - 2] == 'I')
+					&& (a[i - 1] == 'd' || a[i - 1] == 'D')
+					&& (a[i] == 'e' || a[i] == 'E')) {
+				matchlen = 7;
+				mask |= ACTION_PROVIDE | ACTION_REQUIRE;
+			}
+			else
+				if (i >= 6 && (a[i - 6] == 'r' || a[i - 6] == 'R')
+						&& (a[i - 5] == 'e' || a[i - 5] == 'E')
+						&& (a[i - 4] == 'q' || a[i - 4] == 'Q')
+						&& (a[i - 3] == 'u' || a[i - 3] == 'U')
+						&& (a[i - 2] == 'i' || a[i - 2] == 'I')
+						&& (a[i - 1] == 'r' || a[i - 1] == 'R')
+						&& (a[i] == 'e' || a[i] == 'E')) {
+					matchlen = 7;
+					mask |= ACTION_REQUIRE;
+				}
+				else
+					if (i >= 3 && (a[i - 3] == 'h' || a[i - 3] == 'H')
+							&& (a[i - 2] == 'o' || a[i - 2] == 'O')
+							&& (a[i - 1] == 's' || a[i - 1] == 'S')
+							&& (a[i] == 't' || a[i] == 'T')) {
+						matchlen = 4;
+						mask |= ACTION_HOST;
+					}
+					else
+						if (i >= 7 && (a[i - 7] == 'f' || a[i - 7] == 'F')
+								&& (a[i - 6] == 'r' || a[i - 6] == 'R')
+								&& (a[i - 5] == 'a' || a[i - 5] == 'A')
+								&& (a[i - 4] == 'g' || a[i - 4] == 'G')
+								&& (a[i - 3] == 'm' || a[i - 3] == 'M')
+								&& (a[i - 2] == 'e' || a[i - 2] == 'E')
+								&& (a[i - 1] == 'n' || a[i - 1] == 'N')
+								&& (a[i] == 't' || a[i] == 'T')) {
+							matchlen = 8;
+							mask |= ACTION_FRAGMENT;
+						}
+						else {
+							// parse error
+							throw new IllegalArgumentException(
+									"invalid permission: " + actions);
+						}
+
+			// make sure we didn't just match the tail of a word
+			// like "ackbarfrequire". Also, skip to the comma.
+			seencomma = false;
+			while (i >= matchlen && !seencomma) {
+				switch (a[i - matchlen]) {
+					case ',' :
+						seencomma = true;
+					/* FALLTHROUGH */
+					case ' ' :
+					case '\r' :
+					case '\n' :
+					case '\f' :
+					case '\t' :
+						break;
+					default :
+						throw new IllegalArgumentException(
+								"invalid permission: " + actions);
+				}
+				i--;
+			}
+
+			// point i at the location of the comma minus one (or -1).
+			i -= matchlen;
+		}
+
+		if (seencomma) {
+			throw new IllegalArgumentException("invalid permission: " + actions);
+		}
+
+		return (mask);
+	}
+
+	/**
+	 * Determines if the specified permission is implied by this object.
+	 * 
+	 * <p>
+	 * This method checks that the symbolic name of the target is implied by the
+	 * symbolic name of this object. The list of <code>BundlePermission</code>
+	 * actions must either match or allow for the list of the target object to
+	 * imply the target <code>BundlePermission</code> action.
+	 * <p>
+	 * The permission to provide a bundle implies the permission to require the
+	 * named symbolic name.
+	 * 
+	 * <pre>
+	 *       x.y.*,&quot;provide&quot; -&gt; x.y.z,&quot;provide&quot; is true
+	 *       *,&quot;require&quot; -&gt; x.y, &quot;require&quot;      is true
+	 *       *,&quot;provide&quot; -&gt; x.y, &quot;require&quot;      is true
+	 *       x.y,&quot;provide&quot; -&gt; x.y.z, &quot;provide&quot;  is false
+	 * </pre>
+	 * 
+	 * @param p The target permission to interrogate.
+	 * @return <code>true</code> if the specified
+	 *         <code>BundlePermission</code> action is implied by this object;
+	 *         <code>false</code> otherwise.
+	 */
+
+	public boolean implies(Permission p) {
+		if (p instanceof BundlePermission) {
+			BundlePermission target = (BundlePermission) p;
+
+			return (((action_mask & target.action_mask) == target.action_mask) && super
+					.implies(p));
+		}
+
+		return (false);
+	}
+
+	/**
+	 * Returns the canonical string representation of the
+	 * <code>BundlePermission</code> actions.
+	 * 
+	 * <p>
+	 * Always returns present <code>BundlePermission</code> actions in the
+	 * following order: <code>PROVIDE</code>,<code>REQUIRE</code>,
+	 * <code>HOST</code>,<code>FRAGMENT.
+	 * @return Canonical string representation of the <code>BundlePermission</code> actions.
+	 */
+
+	public String getActions() {
+		if (actions == null) {
+			StringBuffer sb = new StringBuffer();
+			boolean comma = false;
+
+			if ((action_mask & ACTION_PROVIDE) == ACTION_PROVIDE) {
+				sb.append(PROVIDE);
+				comma = true;
+			}
+
+			if ((action_mask & ACTION_REQUIRE) == ACTION_REQUIRE) {
+				if (comma)
+					sb.append(',');
+				sb.append(REQUIRE);
+				comma = true;
+			}
+
+			if ((action_mask & ACTION_HOST) == ACTION_HOST) {
+				if (comma)
+					sb.append(',');
+				sb.append(HOST);
+				comma = true;
+			}
+
+			if ((action_mask & ACTION_FRAGMENT) == ACTION_FRAGMENT) {
+				if (comma)
+					sb.append(',');
+				sb.append(FRAGMENT);
+			}
+
+			actions = sb.toString();
+		}
+
+		return (actions);
+	}
+
+	/**
+	 * Returns a new <code>PermissionCollection</code> object suitable for
+	 * storing <code>BundlePermission</code> objects.
+	 * 
+	 * @return A new <code>PermissionCollection</code> object.
+	 */
+	public PermissionCollection newPermissionCollection() {
+		return (new BundlePermissionCollection());
+	}
+
+	/**
+	 * Determines the equality of two <code>BundlePermission</code> objects.
+	 * 
+	 * This method checks that specified bundle has the same bundle symbolic
+	 * name and <code>BundlePermission</code> actions as this
+	 * <code>BundlePermission</code> object.
+	 * 
+	 * @param obj The object to test for equality with this
+	 *        <code>BundlePermission</code> object.
+	 * @return <code>true</code> if <code>obj</code> is a
+	 *         <code>BundlePermission</code>, and has the same bundle
+	 *         symbolic name and actions as this <code>BundlePermission</code>
+	 *         object; <code>false</code> otherwise.
+	 */
+	public boolean equals(Object obj) {
+		if (obj == this) {
+			return (true);
+		}
+
+		if (!(obj instanceof BundlePermission)) {
+			return (false);
+		}
+
+		BundlePermission p = (BundlePermission) obj;
+
+		return ((action_mask == p.action_mask) && getName().equals(p.getName()));
+	}
+
+	/**
+	 * Returns the hash code value for this object.
+	 * 
+	 * @return A hash code value for this object.
+	 */
+
+	public int hashCode() {
+		return (getName().hashCode() ^ getActions().hashCode());
+	}
+
+	/**
+	 * Returns the current action mask.
+	 * <p>
+	 * Used by the BundlePermissionCollection class.
+	 * 
+	 * @return Current action mask.
+	 */
+	int getMask() {
+		return (action_mask);
+	}
+
+	/**
+	 * WriteObject is called to save the state of the
+	 * <code>BundlePermission</code> object to a stream. The actions are
+	 * serialized, and the superclass takes care of the name.
+	 */
+
+	private synchronized void writeObject(java.io.ObjectOutputStream s)
+			throws IOException {
+		// Write out the actions. The superclass takes care of the name
+		// call getActions to make sure actions field is initialized
+		if (actions == null)
+			getActions();
+		s.defaultWriteObject();
+	}
+
+	/**
+	 * readObject is called to restore the state of the BundlePermission from a
+	 * stream.
+	 */
+	private synchronized void readObject(java.io.ObjectInputStream s)
+			throws IOException, ClassNotFoundException {
+		// Read in the action, then initialize the rest
+		s.defaultReadObject();
+		init(getMask(actions));
+	}
+}
+
+/**
+ * Stores a set of <code>BundlePermission</code> permissions.
+ * 
+ * @see java.security.Permission
+ * @see java.security.Permissions
+ * @see java.security.PermissionCollection
+ */
+
+final class BundlePermissionCollection extends PermissionCollection {
+
+	/**
+	 * Comment for <code>serialVersionUID</code>
+	 */
+	private static final long	serialVersionUID	= 3258407326846433079L;
+
+	/**
+	 * Table of permissions.
+	 * 
+	 * @serial
+	 */
+	private Hashtable			permissions;
+
+	/**
+	 * Boolean saying if "*" is in the collection.
+	 * 
+	 * @serial
+	 */
+	private boolean				all_allowed;
+
+	/**
+	 * Create an empty BundlePermissions object.
+	 * 
+	 */
+
+	public BundlePermissionCollection() {
+		permissions = new Hashtable();
+		all_allowed = false;
+	}
+
+	/**
+	 * Adds a permission to the <code>BundlePermission</code> objects. The key
+	 * for the hash is the symbolic name.
+	 * 
+	 * @param permission The <code>BundlePermission</code> object to add.
+	 * 
+	 * @throws IllegalArgumentException If the permission is not a
+	 *         <code>BundlePermission</code> instance.
+	 * @throws SecurityException If this <code>BundlePermissionCollection</code>
+	 *         object has been marked read-only.
+	 */
+
+	public void add(Permission permission) {
+		if (!(permission instanceof BundlePermission))
+			throw new IllegalArgumentException("invalid permission: "
+					+ permission);
+		if (isReadOnly())
+			throw new SecurityException("attempt to add a Permission to a "
+					+ "readonly PermissionCollection");
+
+		BundlePermission bp = (BundlePermission) permission;
+		String name = bp.getName();
+
+		BundlePermission existing = (BundlePermission) permissions.get(name);
+
+		if (existing != null) {
+			int oldMask = existing.getMask();
+			int newMask = bp.getMask();
+			if (oldMask != newMask) {
+				permissions.put(name, new BundlePermission(name, oldMask
+						| newMask));
+
+			}
+		}
+		else {
+			permissions.put(name, permission);
+		}
+
+		if (!all_allowed) {
+			if (name.equals("*"))
+				all_allowed = true;
+		}
+	}
+
+	/**
+	 * Determines if the specified permissions implies the permissions expressed
+	 * in <code>permission</code>.
+	 * 
+	 * @param permission The Permission object to compare with this
+	 *        <code>BundlePermission</code> object.
+	 * 
+	 * @return <code>true</code> if <code>permission</code> is a proper
+	 *         subset of a permission in the set; <code>false</code>
+	 *         otherwise.
+	 */
+
+	public boolean implies(Permission permission) {
+		if (!(permission instanceof BundlePermission))
+			return (false);
+
+		BundlePermission bp = (BundlePermission) permission;
+		BundlePermission x;
+
+		int desired = bp.getMask();
+		int effective = 0;
+
+		// short circuit if the "*" Permission was added
+		if (all_allowed) {
+			x = (BundlePermission) permissions.get("*");
+			if (x != null) {
+				effective |= x.getMask();
+				if ((effective & desired) == desired)
+					return (true);
+			}
+		}
+
+		// strategy:
+		// Check for full match first. Then work our way up the
+		// name looking for matches on a.b.*
+
+		String name = bp.getName();
+
+		x = (BundlePermission) permissions.get(name);
+
+		if (x != null) {
+			// we have a direct hit!
+			effective |= x.getMask();
+			if ((effective & desired) == desired)
+				return (true);
+		}
+
+		// work our way up the tree...
+		int last, offset;
+
+		offset = name.length() - 1;
+
+		while ((last = name.lastIndexOf(".", offset)) != -1) {
+
+			name = name.substring(0, last + 1) + "*";
+			x = (BundlePermission) permissions.get(name);
+
+			if (x != null) {
+				effective |= x.getMask();
+				if ((effective & desired) == desired)
+					return (true);
+			}
+			offset = last - 1;
+		}
+
+		// we don't have to check for "*" as it was already checked
+		// at the top (all_allowed), so we just return false
+		return (false);
+	}
+
+	/**
+	 * Returns an enumeration of all <code>BundlePermission</code> objects in
+	 * the container.
+	 * 
+	 * @return Enumeration of all <code>BundlePermission</code> objects.
+	 */
+
+	public Enumeration elements() {
+		return (permissions.elements());
+	}
+}

Propchange: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundlePermission.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Configurable.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Configurable.java?rev=737043&view=auto
==============================================================================
--- db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Configurable.java (added)
+++ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Configurable.java Fri Jan 23 07:05:47 2009
@@ -0,0 +1,53 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/Configurable.java,v 1.12 2007/02/20 00:07:22 hargrave Exp $
+ * 
+ * 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.
+ * 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.framework;
+
+/**
+ * Supports a configuration object.
+ * 
+ * <p>
+ * <code>Configurable</code> is an interface that should be used by a bundle
+ * developer in support of a configurable service. Bundles that need to
+ * configure a service may test to determine if the service object is an
+ * <code>instanceof Configurable</code>.
+ * 
+ * @deprecated As of 1.2. Please use Configuration Admin service.
+ * @version $Revision: 1.12 $
+ */
+public interface Configurable {
+	/**
+	 * Returns this service's configuration object.
+	 * 
+	 * <p>
+	 * Services implementing <code>Configurable</code> should take care when
+	 * returning a service configuration object since this object is probably
+	 * sensitive.
+	 * <p>
+	 * If the Java Runtime Environment supports permissions, it is recommended
+	 * that the caller is checked for some appropriate permission before
+	 * returning the configuration object.
+	 * 
+	 * @return The configuration object for this service.
+	 * @throws java.lang.SecurityException If the caller does not have an
+	 *         appropriate permission and the Java Runtime Environment supports
+	 *         permissions.
+	 * @deprecated As of 1.2. Please use Configuration Admin service.
+	 */
+	public Object getConfigurationObject();
+}

Propchange: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Configurable.java
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message