* <p> The following steps are required to update a bundle:	 * <ol>	 * <li>If this bundle's state is <tt>UNINSTALLED</tt> then	 * an <tt>IllegalStateException</tt> is thrown.	 *	 * <li>If this bundle's state is <tt>ACTIVE</tt>, <tt>STARTING</tt> or <tt>STOPPING</tt>,	 * the bundle is stopped as described in the <tt>Bundle.stop</tt> method.	 * If <tt>Bundle.stop</tt> throws an exception, the exception is rethrown	 * terminating the update.	 *	 * <li>The download location of the new version of this bundle	 * is determined from either the bundle's {@link Constants#BUNDLE_UPDATELOCATION} Manifest	 * header (if available) or the bundle's original location.	 *	 * <li>The location is interpreted in an implementation dependent manner,	 * typically as a URL, and the new version of this bundle is obtained from	 * this location.	 *	 * <li>The new version of this bundle is installed. If the Framework is	 * unable to install the new version of this bundle, the original version	 * of this bundle will be restored and a <tt>BundleException</tt> will be thrown	 * after completion of the remaining steps.	 *	 * <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 do not all match, the original version	 * of this bundle will be restored and a <tt>BundleException</tt> will be thrown	 * after completion of the remaining steps.	 *	 * <li>This bundle's state is set to <tt>INSTALLED</tt>.	 *	 *	 * <li> If this bundle has not declared an <tt>Import-Package</tt> header	 * in its Manifest file (specifically, this bundle does not depend on any packages from	 * other bundles), this bundle's state may be set to <tt>RESOLVED</tt>.	 *	 * <li>If the new version of this bundle was successfully installed,	 * a bundle event of type {@link BundleEvent#UPDATED}is broadcast.	 *	 * <li>If this bundle's state was originally <tt>ACTIVE</tt>,	 * the updated bundle is started as described in the <tt>Bundle.start</tt> method.	 * If <tt>Bundle.start</tt> throws an exception, a Framework event of	 * type {@link FrameworkEvent#ERROR}is broadcast containing the exception.	 * </ol>	 *	 * <b>Preconditions</b>	 * <ul>	 * <li><tt>getState()</tt> not in {<tt>UNINSTALLED</tt>}.	 * </ul>	 * <b>Postconditions, no exceptions thrown</b>	 * <ul>	 * <li><tt>getState()</tt> in	 * {<tt>INSTALLED</tt>, <tt>RESOLVED</tt>, <tt>ACTIVE</tt>}.	 * <li>This bundle has been updated.	 * </ul>	 * <b>Postconditions, when an exception is thrown</b>	 * <ul>	 * <li><tt>getState()</tt> in {<tt>INSTALLED</tt>, <tt>RESOLVED</tt>, <tt>ACTIVE</tt>}.	 * <li>Original bundle is still used; no update occurred.	 * </ul>	 *	 * @exception BundleException If the update fails.	 * @exception java.lang.IllegalStateException If this	 * bundle has been uninstalled or this bundle tries to change its own state.	 * @exception java.lang.SecurityException If the caller does not have	 * the appropriate <tt>AdminPermission</tt>, and the Java Runtime Environment	 * supports permissions.	 * @see #stop()	 * @see #start()	 */    public abstract void update() throws BundleException;    /**	 * Updates this bundle from an <tt>InputStream</tt>.	 *	 * <p>This method performs all the steps listed in <tt>Bundle.update()</tt>, except the bundle	 * will be read from the supplied <tt>InputStream</tt>, rather than a <tt>URL</tt>.	 * <p>This method will always close the <tt>InputStream</tt>	 * when it is done, even if an exception is thrown.	 *	 * @param in The <tt>InputStream</tt> from which to read the new bundle.	 * @exception BundleException If the provided stream cannot be read or the update fails.	 * @exception java.lang.IllegalStateException If this	 * bundle has been uninstalled or this bundle tries to change its own state.	 * @exception java.lang.SecurityException If the caller does not have	 * the appropriate <tt>AdminPermission</tt>, and the Java Runtime Environment	 * supports permissions.	 * @see #update()	 */    public abstract void update(InputStream in) throws BundleException;    /**	 * Uninstalls this bundle.	 *	 * <p>This method causes the Framework to notify other bundles that this bundle	 * is being uninstalled, and then puts this bundle into the <tt>UNINSTALLED</tt>	 * state. The Framework will remove any resources related to this	 * bundle that it is able to remove.	 *	 * <p>If this bundle has exported any packages, the Framework will	 * continue to make these packages available to their importing bundles	 * until the <tt>PackageAdmin.refreshPackages</tt> method has been called	 * or the Framework is relaunched.	 *	 * <p>The following steps are required to uninstall a bundle:	 * <ol>	 * <li>If this bundle's state is <tt>UNINSTALLED</tt> then	 * an <tt>IllegalStateException</tt> is thrown.	 *	 * <li>If this bundle's state is <tt>ACTIVE</tt>, <tt>STARTING</tt> or <tt>STOPPING</tt>,	 * this bundle is stopped as described in the <tt>Bundle.stop</tt> method.	 * If <tt>Bundle.stop</tt> throws an exception, a Framework event of type	 * {@link FrameworkEvent#ERROR}is broadcast containing the exception.	 *	 * <li>This bundle's state is set to <tt>UNINSTALLED</tt>.	 *	 * <li>A bundle event of type {@link BundleEvent#UNINSTALLED}is broadcast.	 *	 * <li>This bundle and any persistent storage area provided for this bundle	 * by the Framework are removed.	 * </ol>	 *	 * <b>Preconditions</b>	 * <ul>	 * <li><tt>getState()</tt> not in {<tt>UNINSTALLED</tt>}.	 * </ul>	 * <b>Postconditions, no exceptions thrown</b>	 * <ul>	 * <li><tt>getState()</tt> in {<tt>UNINSTALLED</tt>}.	 * <li>This bundle has been uninstalled.	 * </ul>	 * <b>Postconditions, when an exception is thrown</b>	 * <ul>	 * <li><tt>getState()</tt> not in {<tt>UNINSTALLED</tt>}.	 * <li>This Bundle has not been uninstalled.	 * </ul>	 *	 * @exception BundleException If the uninstall failed.	 * This can occur if another thread is attempting to change the bundle's state	 * and does not complete in a timely manner.	 * @exception java.lang.IllegalStateException If this	 * bundle has been uninstalled or this bundle tries to change its own state.	 * @exception java.lang.SecurityException If the caller does not have	 * the appropriate <tt>AdminPermission</tt>, and the Java Runtime Environment	 * supports permissions.	 * @see #stop()	 */    public abstract void uninstall() throws BundleException;    /**	 * Returns this bundle's Manifest headers and values.	 * This method returns all the Manifest headers and values	 * from the main section of the bundle's Manifest file; that is, all lines prior	 * to the first blank line.	 *	 * <p>Manifest header names are case-insensitive. The methods of the returned	 * <tt>Dictionary</tt> object will operate on header names in a case-insensitive manner.	 *	 * <p>For example, the following Manifest headers and values are included	 * if they are present in the Manifest file:	 * <pre>	 * Bundle-Name	 * Bundle-Vendor	 * Bundle-Version	 * Bundle-Description	 * Bundle-DocURL	 * Bundle-ContactAddress	 * </pre>	 * <p>This method will continue to return Manifest header information	 * while this bundle is in the <tt>UNINSTALLED</tt> state.	 *	 * @return A <tt>Dictionary</tt> object containing this bundle's Manifest headers and values.	 *	 * @exception java.lang.SecurityException If the caller does not have	 * the <tt>AdminPermission</tt>, and the Java Runtime Environment supports permissions.	 */    public abstract Dictionary getHeaders();    /**	 * Returns this bundle's identifier. The bundle is assigned a unique identifier by the Framework	 * when it is installed in the OSGi environment.	 *	 * <p>A bundle's unique identifier has the following attributes:	 * <ul>	 * <li>Is unique and persistent.	 * <li>Is a <tt>long</tt>.	 * <li>Its value is not reused for another bundle, even after the bundle is uninstalled.	 * <li>Does not change while the bundle remains installed.	 * <li>Does not change when the bundle is updated.	 * </ul>	 *	 * <p>This method will continue to return this bundle's unique identifier	 * while this bundle is in the <tt>UNINSTALLED</tt> state.	 *	 * @return The unique identifier of this bundle.	 */    public abstract long getBundleId();    /**	 * Returns this bundle's location identifier.	 *	 * <p>The bundle location identifier is the location passed to	 * {@link BundleContext#installBundle}when a bundle is installed.	 *	 * <p>This method will continue to return this bundle's location	 * identifier while this bundle is in the <tt>UNINSTALLED</tt> state.	 *	 * @return The string representation of this bundle's location identifier.	 * @exception java.lang.SecurityException If the caller does not have	 * the appropriate <tt>AdminPermission</tt>, and the Java Runtime Environment	 * supports permissions.	 */    public abstract String getLocation();    /**	 * Returns this bundle's <tt>ServiceReference</tt> list for all	 * services it has registered or <tt>null</tt> if this bundle	 * has no registered services.	 *	 * <p>If the Java runtime supports permissions, a <tt>ServiceReference</tt> object to a	 * service is included in the returned list only if the	 * caller has the <tt>ServicePermission</tt> to get the service	 * using at least one of the named classes the service was registered under.	 *	 * <p>The list 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.	 *	 * @return An array of <tt>ServiceReference</tt> objects or <tt>null</tt>.	 * @exception java.lang.IllegalStateException If this bundle has been uninstalled.	 * @see ServiceRegistration	 * @see ServiceReference	 * @see ServicePermission	 */    public abstract ServiceReference[] getRegisteredServices();    /**	 * Returns this bundle's <tt>ServiceReference</tt> list for all	 * services it is using or returns <tt>null</tt> if this bundle is not using any services.	 * A bundle is considered to be using a service if its use count for that service is greater than zero.	 *	 * <p>If the Java Runtime Environment supports permissions,	 * a <tt>ServiceReference</tt> object to a service is included in the returned list only if the	 * caller has the <tt>ServicePermission</tt> to get the service	 * using at least one of the named classes the service was registered under.	 * <p>The list 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.	 *	 * @return An array of <tt>ServiceReference</tt> objects or <tt>null</tt>.	 * @exception java.lang.IllegalStateException If this bundle has been uninstalled.	 * @see ServiceReference	 * @see ServicePermission	 */    public abstract ServiceReference[] getServicesInUse();    /**	 * Determines if this bundle has the specified permissions.	 *	 * <p>If the Java Runtime Environment does not support permissions,	 * this method always returns <tt>true</tt>.	 * <p><tt>permission</tt> is of type <tt>Object</tt> to	 * avoid referencing the <tt>java.security.Permission</tt> class	 * directly. This is to allow the Framework to be implemented in Java	 * environments which do not support permissions.	 *	 * <p>If the Java Runtime Environment does support permissions, this	 * bundle and all its resources including nested JAR files, belong	 * to the same <tt>java.security.ProtectionDomain</tt>; that is, they will share	 * the same set of permissions.	 *	 * @param permission The permission to verify.	 *	 * @return <tt>true</tt> if this bundle has the specified permission or	 * the permissions possessed by this bundle imply the specified permission;	 * <tt>false</tt> if this bundle does not have the specified permission or <tt>permission</tt>	 * is not an <tt>instanceof</tt> <tt>java.security.Permission</tt>.	 *	 * @exception java.lang.IllegalStateException If this bundle has been uninstalled.	 */    public abstract boolean hasPermission(Object permission);    /**	 * Find the specified resource in this bundle.	 *	 * This bundle's class loader is called to search for the named resource.	 * If this bundle's state is <tt>INSTALLED</tt>, then only this bundle will	 * be searched for the specified resource. Imported packages cannot be searched	 * when a bundle has not been resolved.	 *	 * @param name The name of the resource.	 * See <tt>java.lang.ClassLoader.getResource</tt> for a description of	 * the format of a resource name.	 * @return a URL to the named resource, or <tt>null</tt> if the resource could	 * not be found or if the caller does not have	 * the <tt>AdminPermission</tt>, and the Java Runtime Environment supports permissions.	 *	 * @since 1.1	 * @exception java.lang.IllegalStateException If this bundle has been uninstalled.	 */    public abstract URL getResource(String name);}