felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rickh...@apache.org
Subject svn commit: r465392 [3/10] - in /incubator/felix/trunk/org.osgi.core/src/main/java/org/osgi: framework/ service/condpermadmin/ service/packageadmin/ service/permissionadmin/ service/startlevel/ service/url/
Date Wed, 18 Oct 2006 22:01:24 GMT
Modified: incubator/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleActivator.java
URL: http://svn.apache.org/viewvc/incubator/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleActivator.java?view=diff&rev=465392&r1=465391&r2=465392
==============================================================================
--- incubator/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleActivator.java (original)
+++ incubator/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleActivator.java Wed Oct 18 15:01:22 2006
@@ -1,89 +1,89 @@
-/*
- * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleActivator.java,v 1.10 2006/03/14 01:21:02 hargrave Exp $
- * 
- * Copyright (c) OSGi Alliance (2000, 2005). 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;
-
-/**
- * Customizes the starting and stopping of a bundle.
- * <p>
- * <code>BundleActivator</code> is an interface that may be implemented when a
- * bundle is started or stopped. The Framework can create instances of a
- * bundle's <code>BundleActivator</code> as required. If an instance's
- * <code>BundleActivator.start</code> method executes successfully, it is
- * guaranteed that the same instance's <code>BundleActivator.stop</code>
- * method will be called when the bundle is to be stopped.
- * 
- * <p>
- * <code>BundleActivator</code> is specified through the
- * <code>Bundle-Activator</code> Manifest header. A bundle can only specify a
- * single <code>BundleActivator</code> in the Manifest file. Fragment bundles
- * must not have a <code>BundleActivator</code>. The form of the Manifest
- * header is:
- * 
- * <pre>
- *   Bundle-Activator: &lt;i&gt;class-name&lt;/i&gt;
- * </pre>
- * 
- * where <code>class-name</code> is a fully qualified Java classname.
- * <p>
- * The specified <code>BundleActivator</code> class must have a public
- * constructor that takes no parameters so that a <code>BundleActivator</code>
- * object can be created by <code>Class.newInstance()</code>.
- * 
- * @version $Revision: 1.10 $
- */
-
-public interface BundleActivator {
-	/**
-	 * Called when this bundle is started so the Framework can perform the
-	 * bundle-specific activities necessary to start this bundle. This method
-	 * can be used to register services or to allocate any resources that this
-	 * bundle needs.
-	 * 
-	 * <p>
-	 * This method must complete and return to its caller in a timely manner.
-	 * 
-	 * @param context The execution context of the bundle being started.
-	 * @throws java.lang.Exception If this method throws an exception, this
-	 *         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;
-
-	/**
-	 * Called when this bundle is stopped so the Framework can perform the
-	 * bundle-specific activities necessary to stop the bundle. In general, this
-	 * method should undo the work that the <code>BundleActivator.start</code>
-	 * method started. There should be no active threads that were started by
-	 * this bundle when this bundle returns. A stopped bundle must not call any
-	 * Framework objects.
-	 * 
-	 * <p>
-	 * This method must complete and return to its caller in a timely manner.
-	 * 
-	 * @param context The execution context of the bundle being stopped.
-	 * @throws java.lang.Exception If this method throws an exception, the
-	 *         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;
-}
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleActivator.java,v 1.11 2006/06/16 16:31:18 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;
+
+/**
+ * Customizes the starting and stopping of a bundle.
+ * <p>
+ * <code>BundleActivator</code> is an interface that may be implemented when a
+ * bundle is started or stopped. The Framework can create instances of a
+ * bundle's <code>BundleActivator</code> as required. If an instance's
+ * <code>BundleActivator.start</code> method executes successfully, it is
+ * guaranteed that the same instance's <code>BundleActivator.stop</code>
+ * method will be called when the bundle is to be stopped.
+ * 
+ * <p>
+ * <code>BundleActivator</code> is specified through the
+ * <code>Bundle-Activator</code> Manifest header. A bundle can only specify a
+ * single <code>BundleActivator</code> in the Manifest file. Fragment bundles
+ * must not have a <code>BundleActivator</code>. The form of the Manifest
+ * header is:
+ * 
+ * <pre>
+ *   Bundle-Activator: &lt;i&gt;class-name&lt;/i&gt;
+ * </pre>
+ * 
+ * where <code>class-name</code> is a fully qualified Java classname.
+ * <p>
+ * The specified <code>BundleActivator</code> class must have a public
+ * constructor that takes no parameters so that a <code>BundleActivator</code>
+ * object can be created by <code>Class.newInstance()</code>.
+ * 
+ * @version $Revision: 1.11 $
+ */
+
+public interface BundleActivator {
+	/**
+	 * Called when this bundle is started so the Framework can perform the
+	 * bundle-specific activities necessary to start this bundle. This method
+	 * can be used to register services or to allocate any resources that this
+	 * bundle needs.
+	 * 
+	 * <p>
+	 * This method must complete and return to its caller in a timely manner.
+	 * 
+	 * @param context The execution context of the bundle being started.
+	 * @throws java.lang.Exception If this method throws an exception, this
+	 *         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;
+
+	/**
+	 * Called when this bundle is stopped so the Framework can perform the
+	 * bundle-specific activities necessary to stop the bundle. In general, this
+	 * method should undo the work that the <code>BundleActivator.start</code>
+	 * method started. There should be no active threads that were started by
+	 * this bundle when this bundle returns. A stopped bundle must not call any
+	 * Framework objects.
+	 * 
+	 * <p>
+	 * This method must complete and return to its caller in a timely manner.
+	 * 
+	 * @param context The execution context of the bundle being stopped.
+	 * @throws java.lang.Exception If this method throws an exception, the
+	 *         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;
+}

Modified: incubator/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleContext.java
URL: http://svn.apache.org/viewvc/incubator/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleContext.java?view=diff&rev=465392&r1=465391&r2=465392
==============================================================================
--- incubator/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleContext.java (original)
+++ incubator/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleContext.java Wed Oct 18 15:01:22 2006
@@ -1,823 +1,823 @@
-/*
- * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleContext.java,v 1.18 2006/03/14 01:21:02 hargrave Exp $
- * 
- * Copyright (c) OSGi Alliance (2000, 2005). 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.
- * 
- * @version $Revision: 1.18 $
- */
-
-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 they are not all present, 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;
-}
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleContext.java,v 1.19 2006/06/16 16:31:18 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;
+
+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.
+ * 
+ * @version $Revision: 1.19 $
+ */
+
+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 they are not all present, 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;
+}



Mime
View raw message