Initial source commit.
git-svn-id: https://svn.apache.org/repos/asf/incubator/oscar/trunk@233031 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/org/osgi/framework/BundleContext.java b/src/org/osgi/framework/BundleContext.java
new file mode 100644
index 0000000..91fa559
--- /dev/null
+++ b/src/org/osgi/framework/BundleContext.java
@@ -0,0 +1,790 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleContext.java,v 1.13 2005/06/21 16:22:12 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2000, 2005). All Rights Reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this
+ * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
+ */
+
+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.13 $
+ */
+
+public abstract 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.
+ * @exception 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 abstract 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>.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract 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 broadcast.
+ *
+ * <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.
+ * @exception BundleException If the installation failed.
+ * @exception java.lang.SecurityException If the caller does not have the
+ * appropriate <code>AdminPermission</code>, and the Java Runtime
+ * Environment supports permissions.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract 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.
+ * @exception BundleException If the provided stream cannot be read or the
+ * installation failed.
+ * @exception java.lang.SecurityException If the caller does not have the
+ * appropriate <code>AdminPermission</code>, and the Java Runtime
+ * Environment supports permissions.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ * @see #installBundle(java.lang.String)
+ */
+ public abstract 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 abstract 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 abstract 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.
+ *
+ * @exception InvalidSyntaxException If <code>filter</code> contains an
+ * invalid filter string that cannot be parsed.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @see ServiceEvent
+ * @see ServiceListener
+ * @see ServicePermission
+ */
+ public abstract 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.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @see #addServiceListener(ServiceListener, String)
+ */
+ public abstract 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.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract 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.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @see BundleEvent
+ * @see BundleListener
+ */
+ public abstract 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.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract 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.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @see FrameworkEvent
+ * @see FrameworkListener
+ */
+ public abstract 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.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract 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
+ * synchronously sent.
+ * <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.
+ *
+ * @exception 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>
+ *
+ * @exception 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.
+ *
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @see ServiceRegistration
+ * @see ServiceFactory
+ */
+ public abstract 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.
+ *
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ * @see #registerService(java.lang.String[], java.lang.Object,
+ * java.util.Dictionary)
+ */
+ public abstract 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.
+ * @exception InvalidSyntaxException If <code>filter</code> contains an
+ * invalid filter string that cannot be parsed.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract 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.
+ * @exception InvalidSyntaxException If <code>filter</code> contains an
+ * invalid filter string that cannot be parsed.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract 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.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ * @see #getServiceReferences(String, String)
+ */
+ public abstract 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 broadcast.
+ * <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>.
+ * @exception 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.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ * @see #ungetService(ServiceReference)
+ * @see ServiceFactory
+ */
+ public abstract 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.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ * @see #getService
+ * @see ServiceFactory
+ */
+ public abstract 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.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract 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.
+ * @exception InvalidSyntaxException If <code>filter</code> contains an
+ * invalid filter string that cannot be parsed.
+ * @exception NullPointerException If <code>filter</code> is null.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @since 1.1
+ * @see "Framework specification for a description of the filter string syntax."
+ */
+ public abstract Filter createFilter(String filter)
+ throws InvalidSyntaxException;
+}
+