You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by ri...@apache.org on 2006/03/16 16:57:43 UTC
svn commit: r386363 [3/10] - in
/incubator/felix/trunk/org.osgi/src/main/java/org/osgi: framework/
service/condpermadmin/ service/packageadmin/ service/startlevel/
service/url/ util/tracker/
Modified: incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleContext.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleContext.java?rev=386363&r1=386362&r2=386363&view=diff
==============================================================================
--- incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleContext.java (original)
+++ incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleContext.java Thu Mar 16 07:57:37 2006
@@ -1,790 +1,823 @@
-/*
- * $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;
-}
-
+/*
+ * $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;
+}
Modified: incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleEvent.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleEvent.java?rev=386363&r1=386362&r2=386363&view=diff
==============================================================================
--- incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleEvent.java (original)
+++ incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleEvent.java Thu Mar 16 07:57:37 2006
@@ -1,146 +1,177 @@
-/*
- * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleEvent.java,v 1.10 2005/05/13 20:32:54 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.util.EventObject;
-
-/**
- * A Framework event describing a bundle lifecycle change.
- * <p>
- * <code>BundleEvent</code> objects are delivered to <code>BundleListener</code>
- * objects when a change occurs in a bundle's lifecycle. A type code is used to
- * identify the event type for future extendability.
- *
- * <p>
- * OSGi Alliance reserves the right to extend the set of types.
- *
- * @version $Revision: 1.10 $
- */
-
-public class BundleEvent extends EventObject {
- static final long serialVersionUID = 4080640865971756012L;
- /**
- * Bundle that had a change occur in its lifecycle.
- */
- private Bundle bundle;
-
- /**
- * Type of bundle lifecycle change.
- */
- private int type;
-
- /**
- * The bundle has been installed.
- * <p>
- * The value of <code>INSTALLED</code> is 0x00000001.
- *
- * @see BundleContext#installBundle(String)
- */
- public final static int INSTALLED = 0x00000001;
-
- /**
- * The bundle has been started.
- * <p>
- * The value of <code>STARTED</code> is 0x00000002.
- *
- * @see Bundle#start
- */
- public final static int STARTED = 0x00000002;
-
- /**
- * The bundle has been stopped.
- * <p>
- * The value of <code>STOPPED</code> is 0x00000004.
- *
- * @see Bundle#stop
- */
- public final static int STOPPED = 0x00000004;
-
- /**
- * The bundle has been updated.
- * <p>
- * The value of <code>UPDATED</code> is 0x00000008.
- *
- * @see Bundle#update()
- */
- public final static int UPDATED = 0x00000008;
-
- /**
- * The bundle has been uninstalled.
- * <p>
- * The value of <code>UNINSTALLED</code> is 0x00000010.
- *
- * @see Bundle#uninstall
- */
- public final static int UNINSTALLED = 0x00000010;
-
- /**
- * The bundle has been resolved.
- * <p>
- * The value of <code>RESOLVED</code> is 0x00000020.
- *
- * @see Bundle#RESOLVED
- * @since 1.3
- */
- public final static int RESOLVED = 0x00000020;
-
- /**
- * The bundle has been unresolved.
- * <p>
- * The value of <code>UNRESOLVED</code> is 0x00000040.
- *
- * @see Bundle#INSTALLED
- * @since 1.3
- */
- public final static int UNRESOLVED = 0x00000040;
-
- /**
- * Creates a bundle event of the specified type.
- *
- * @param type The event type.
- * @param bundle The bundle which had a lifecycle change.
- */
-
- public BundleEvent(int type, Bundle bundle) {
- super(bundle);
- this.bundle = bundle;
- this.type = type;
- }
-
- /**
- * Returns the bundle which had a lifecycle change. This bundle is the
- * source of the event.
- *
- * @return The bundle that had a change occur in its lifecycle.
- */
- public Bundle getBundle() {
- return bundle;
- }
-
- /**
- * Returns the type of lifecyle event. The type values are:
- * <ul>
- * <li>{@link #INSTALLED}
- * <li>{@link #STARTED}
- * <li>{@link #STOPPED}
- * <li>{@link #UPDATED}
- * <li>{@link #UNINSTALLED}
- * <li>{@link #RESOLVED}
- * <li>{@link #UNRESOLVED}
- * </ul>
- *
- * @return The type of lifecycle event.
- */
-
- public int getType() {
- return type;
- }
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleEvent.java,v 1.14 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.util.EventObject;
+
+/**
+ * An event from the Framework describing a bundle lifecycle change.
+ * <p>
+ * <code>BundleEvent</code> objects are delivered to
+ * <code>BundleListener</code> objects when a change occurs in a bundle's
+ * lifecycle. A type code is used to identify the event type for future
+ * extendability.
+ *
+ * <p>
+ * OSGi Alliance reserves the right to extend the set of types.
+ *
+ * @version $Revision: 1.14 $
+ */
+
+public class BundleEvent extends EventObject {
+ static final long serialVersionUID = 4080640865971756012L;
+ /**
+ * Bundle that had a change occur in its lifecycle.
+ */
+ private Bundle bundle;
+
+ /**
+ * Type of bundle lifecycle change.
+ */
+ private int type;
+
+ /**
+ * The bundle has been installed.
+ * <p>
+ * The value of <code>INSTALLED</code> is 0x00000001.
+ *
+ * @see BundleContext#installBundle(String)
+ */
+ public final static int INSTALLED = 0x00000001;
+
+ /**
+ * The bundle has been started.
+ * <p>
+ * The value of <code>STARTED</code> is 0x00000002.
+ *
+ * @see Bundle#start
+ */
+ public final static int STARTED = 0x00000002;
+
+ /**
+ * The bundle has been stopped.
+ * <p>
+ * The value of <code>STOPPED</code> is 0x00000004.
+ *
+ * @see Bundle#stop
+ */
+ public final static int STOPPED = 0x00000004;
+
+ /**
+ * The bundle has been updated.
+ * <p>
+ * The value of <code>UPDATED</code> is 0x00000008.
+ *
+ * @see Bundle#update()
+ */
+ public final static int UPDATED = 0x00000008;
+
+ /**
+ * The bundle has been uninstalled.
+ * <p>
+ * The value of <code>UNINSTALLED</code> is 0x00000010.
+ *
+ * @see Bundle#uninstall
+ */
+ public final static int UNINSTALLED = 0x00000010;
+
+ /**
+ * The bundle has been resolved.
+ * <p>
+ * The value of <code>RESOLVED</code> is 0x00000020.
+ *
+ * @see Bundle#RESOLVED
+ * @since 1.3
+ */
+ public final static int RESOLVED = 0x00000020;
+
+ /**
+ * The bundle has been unresolved.
+ * <p>
+ * The value of <code>UNRESOLVED</code> is 0x00000040.
+ *
+ * @see Bundle#INSTALLED
+ * @since 1.3
+ */
+ public final static int UNRESOLVED = 0x00000040;
+
+ /**
+ * The bundle is about to start.
+ * <p>
+ * The value of <code>STARTING</code> is 0x00000080.
+ *
+ * @see Bundle#start()
+ * @since 1.3
+ */
+ public final static int STARTING = 0x00000080;
+
+ /**
+ * The bundle is about to stop.
+ * <p>
+ * The value of <code>STOPPING</code> is 0x00000100.
+ *
+ * @see Bundle#stop()
+ * @since 1.3
+ */
+ public final static int STOPPING = 0x00000100;
+
+ /**
+ * Creates a bundle event of the specified type.
+ *
+ * @param type The event type.
+ * @param bundle The bundle which had a lifecycle change.
+ */
+
+ public BundleEvent(int type, Bundle bundle) {
+ super(bundle);
+ this.bundle = bundle;
+ this.type = type;
+ }
+
+ /**
+ * Returns the bundle which had a lifecycle change. This bundle is the
+ * source of the event.
+ *
+ * @return The bundle that had a change occur in its lifecycle.
+ */
+ public Bundle getBundle() {
+ return bundle;
+ }
+
+ /**
+ * Returns the type of lifecyle event. The type values are:
+ * <ul>
+ * <li>{@link #INSTALLED}
+ * <li>{@link #RESOLVED}
+ * <li>{@link #STARTING}
+ * <li>{@link #STARTED}
+ * <li>{@link #STOPPING}
+ * <li>{@link #STOPPED}
+ * <li>{@link #UPDATED}
+ * <li>{@link #UNRESOLVED}
+ * <li>{@link #UNINSTALLED}
+ * </ul>
+ *
+ * @return The type of lifecycle event.
+ */
+
+ public int getType() {
+ return type;
+ }
}
Modified: incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleException.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleException.java?rev=386363&r1=386362&r2=386363&view=diff
==============================================================================
--- incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleException.java (original)
+++ incubator/felix/trunk/org.osgi/src/main/java/org/osgi/framework/BundleException.java Thu Mar 16 07:57:37 2006
@@ -1,95 +1,106 @@
-/*
- * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleException.java,v 1.10 2005/05/13 20:32:55 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;
-
-/**
- * A Framework exception used to indicate that a bundle lifecycle problem
- * occurred.
- *
- * <p>
- * <code>BundleException</code> object is created by the Framework to denote an
- * exception condition in the lifecycle of a bundle. <code>BundleException</code>s
- * should not be created by bundle developers.
- *
- * <p>
- * This exception is updated to conform to the general purpose exception
- * chaining mechanism.
- *
- * @version $Revision: 1.10 $
- */
-
-public class BundleException extends Exception {
- static final long serialVersionUID = 3571095144220455665L;
- /**
- * Nested exception.
- */
- private Throwable cause;
-
- /**
- * Creates a <code>BundleException</code> that wraps another exception.
- *
- * @param msg The associated message.
- * @param cause The cause of this exception.
- */
- public BundleException(String msg, Throwable cause) {
- super(msg);
- this.cause = cause;
- }
-
- /**
- * Creates a <code>BundleException</code> object with the specified message.
- *
- * @param msg The message.
- */
- public BundleException(String msg) {
- super(msg);
- this.cause = null;
- }
-
- /**
- * Returns any nested exceptions included in this exception.
- *
- * <p>
- * This method predates the general purpose exception chaining mechanism.
- * The {@link #getCause()} method is now the preferred means of obtaining
- * this information.
- *
- * @return The nested exception; <code>null</code> if there is no nested
- * exception.
- */
- public Throwable getNestedException() {
- return cause;
- }
-
- /**
- * Returns the cause of this exception or <code>null</code> if no cause was
- * specified when this exception was created.
- *
- * @return The cause of this exception or <code>null</code> if no cause was
- * specified.
- * @since 1.3
- */
- public Throwable getCause() {
- return cause;
- }
-
- /**
- * The cause of this exception can only be set when constructed.
- *
- * @throws java.lang.IllegalStateException This method will always throw an
- * <code>IllegalStateException</code> since the cause of this
- * exception can only be set when constructed.
- * @since 1.3
- */
- public Throwable initCause(Throwable cause) {
- throw new IllegalStateException();
- }
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleException.java,v 1.13 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;
+
+/**
+ * A Framework exception used to indicate that a bundle lifecycle problem
+ * occurred.
+ *
+ * <p>
+ * <code>BundleException</code> object is created by the Framework to denote
+ * an exception condition in the lifecycle of a bundle.
+ * <code>BundleException</code>s should not be created by bundle developers.
+ *
+ * <p>
+ * This exception is updated to conform to the general purpose exception
+ * chaining mechanism.
+ *
+ * @version $Revision: 1.13 $
+ */
+
+public class BundleException extends Exception {
+ static final long serialVersionUID = 3571095144220455665L;
+ /**
+ * Nested exception.
+ */
+ private Throwable cause;
+
+ /**
+ * Creates a <code>BundleException</code> that wraps another exception.
+ *
+ * @param msg The associated message.
+ * @param cause The cause of this exception.
+ */
+ public BundleException(String msg, Throwable cause) {
+ super(msg);
+ this.cause = cause;
+ }
+
+ /**
+ * Creates a <code>BundleException</code> object with the specified
+ * message.
+ *
+ * @param msg The message.
+ */
+ public BundleException(String msg) {
+ super(msg);
+ this.cause = null;
+ }
+
+ /**
+ * Returns any nested exceptions included in this exception.
+ *
+ * <p>
+ * This method predates the general purpose exception chaining mechanism.
+ * The {@link #getCause()} method is now the preferred means of obtaining
+ * this information.
+ *
+ * @return The nested exception; <code>null</code> if there is no nested
+ * exception.
+ */
+ public Throwable getNestedException() {
+ return cause;
+ }
+
+ /**
+ * Returns the cause of this exception or <code>null</code> if no cause
+ * was specified when this exception was created.
+ *
+ * @return The cause of this exception or <code>null</code> if no cause
+ * was specified.
+ * @since 1.3
+ */
+ public Throwable getCause() {
+ return cause;
+ }
+
+ /**
+ * The cause of this exception can only be set when constructed.
+ *
+ * @param cause Cause of the exception.
+ * @return This object.
+ * @throws java.lang.IllegalStateException This method will always throw an
+ * <code>IllegalStateException</code> since the cause of this
+ * exception can only be set when constructed.
+ * @since 1.3
+ */
+ public Throwable initCause(Throwable cause) {
+ throw new IllegalStateException();
+ }
}