bundle.java

OSGI这是一个中间件,与UPNP齐名,是用于移植到嵌入式平台之上

	 * <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);
}