bundle.java

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

/*
 * Copyright (c) The Open Services Gateway Initiative (2000, 2002).
 * All Rights Reserved.
 *
 * Implementation of certain elements of the Open Services Gateway Initiative
 * (OSGI) Specification may be subject to third party intellectual property
 * rights, including without limitation, patent rights (such a third party may
 * or may not be a member of OSGi). OSGi is not responsible and shall not be
 * held responsible in any manner for identifying or failing to identify any or
 * all such third party intellectual property rights.
 *
 * This document and the information contained herein are provided on an "AS
 * IS" basis and OSGI DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL
 * NOT INFRINGE ANY RIGHTS AND ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
 * FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL OSGI BE LIABLE FOR ANY
 * LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF
 * BUSINESS, OR FOR DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTIAL,
 * PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND IN CONNECTION WITH THIS
 * DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH LOSS OR DAMAGE.
 *
 * All Company, brand and product names may be trademarks that are the sole
 * property of their respective owners. All rights reserved.
 */

package org.osgi.framework;

import java.io.InputStream;
import java.util.Dictionary;
import java.net.URL;

/**
 * An installed bundle in the Framework.
 *
 * <p>A <tt>Bundle</tt> object is the access point to define the life cycle
 * of an installed bundle. Each bundle installed in the OSGi environment
 * will have an associated <tt>Bundle</tt> object.
 *
 * <p>A bundle will have a unique identity, a <tt>long</tt>, chosen by the
 * Framework. This identity will not change during the life cycle of a bundle, even when
 * the bundle is updated. Uninstalling and then reinstalling the bundle will create
 * a new unique identity.
 *
 * <p>A bundle can be in one of six states:
 * <ul>
 * <li>{@link #UNINSTALLED}
 * <li>{@link #INSTALLED}
 * <li>{@link #RESOLVED}
 * <li>{@link #STARTING}
 * <li>{@link #STOPPING}
 * <li>{@link #ACTIVE}
 * </ul>
 * <p>Values assigned to these states have no specified ordering;
 * they represent bit values that may be ORed together to determine if
 * a bundle is in one of the valid states.
 *
 * <p>A bundle should only execute code when its state is one of
 * <tt>STARTING</tt>, <tt>ACTIVE</tt>, or <tt>STOPPING</tt>.
 * An <tt>UNINSTALLED</tt> bundle can not be set to another state; it
 * is a zombie and can only be reached because invalid references are kept somewhere.
 *
 * <p>The Framework is the only entity that is allowed to
 * create <tt>Bundle</tt> objects, and these objects are only valid
 * within the Framework that created them.
 *
 * @version $Revision: 1.1.1.1 $
 * @author Open Services Gateway Initiative
 */
public abstract interface Bundle
{
    /**
	 * This bundle is uninstalled and may not be used.
	 *
	 * <p>The <tt>UNINSTALLED</tt> state is only visible after a bundle
	 * is uninstalled; the bundle is in an unusable state
	 * and all references to the <tt>Bundle</tt> object should be released
	 * immediately.
	 * <p>The value of <tt>UNINSTALLED</tt> is 0x00000001.
	 */
    public static final int UNINSTALLED = 0x00000001;

    /**
	 * This bundle is installed but not yet resolved.
	 *
	 * <p>A bundle is in the <tt>INSTALLED</tt> state when it has been installed
	 * in the Framework but cannot run.
	 * <p>This state is visible if the bundle's code dependencies are not resolved.
	 * The Framework may attempt to resolve an <tt>INSTALLED</tt> bundle's
	 * code dependencies and move the bundle to the <tt>RESOLVED</tt> state.
	 * <p>The value of <tt>INSTALLED</tt> is 0x00000002.
	 */
    public static final int INSTALLED = 0x00000002;

    /**
	 * This bundle is resolved and is able to be started.
	 *
	 * <p>A bundle is in the <tt>RESOLVED</tt> state when the Framework has successfully
	 * resolved the bundle's dependencies. These dependencies include:
	 * <ul>
	 * <li>The bundle's class path from its {@link Constants#BUNDLE_CLASSPATH} Manifest header.
	 * <li>The bundle's package dependencies from
	 * its {@link Constants#EXPORT_PACKAGE}and {@link Constants#IMPORT_PACKAGE} Manifest headers.
	 * </ul>
	 * <p>Note that the bundle is not active yet. A bundle must be put in the
	 * <tt>RESOLVED</tt> state before it can be started. The Framework may attempt to
	 * resolve a bundle at any time.
	 * <p>The value of <tt>RESOLVED</tt> is 0x00000004.
	 */
    public static final int RESOLVED = 0x00000004;

    /**
	 * This bundle is in the process of starting.
	 *
	 * <p>A bundle is in the <tt>STARTING</tt> state when the {@link #start}method
	 * is active. A bundle will be in this state when the bundle's
	 * {@link BundleActivator#start}is called. If this method completes
	 * without exception, then the bundle has successfully started and will move to the
	 * <tt>ACTIVE</tt> state.
	 * <p>The value of <tt>STARTING</tt> is 0x00000008.
	 */
    public static final int STARTING = 0x00000008;

    /**
	 * This bundle is in the process of stopping.
	 *
	 * <p>A bundle is in the <tt>STOPPING</tt> state when the {@link #stop}method
	 * is active. A bundle will be in this state when the bundle's
	 * {@link BundleActivator#stop}method is called. When this method completes
	 * the bundle is stopped and will move to the <tt>RESOLVED</tt> state.
	 * <p>The value of <tt>STOPPING</tt> is 0x00000010.
	 */
    public static final int STOPPING = 0x00000010;

    /**
	 * This bundle is now running.
	 *
	 * <p>A bundle is in the <tt>ACTIVE</tt> state when it has been successfully started.
	 * <p>The value of <tt>ACTIVE</tt> is 0x00000020.
	 */
    public static final int ACTIVE    = 0x00000020;

    /**
	 * Returns this bundle's current state.
	 *
	 * <p>A bundle can be in only one state at any time.
	 *
	 * @return An element of <tt>UNINSTALLED</tt>, <tt>INSTALLED</tt>,
	 * <tt>RESOLVED</tt>, <tt>STARTING</tt>, <tt>STOPPING</tt>,
	 * <tt>ACTIVE</tt>.
	 */
    public abstract int getState();

    /**
	 * Starts this bundle.
	 *
	 * If the Framework implements the optional Start Level service and the
	 * current start level is less than this bundle's start level, then the
	 * Framework must persistently mark this bundle as started and delay the
	 * starting of this bundle until the Framework's current start level becomes
	 * equal or more than the bundle's start level.
	 * <p>Otherwise, the following steps are required to start 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>STARTING</tt> or <tt>STOPPING</tt>
	 * then this method will wait for this bundle to
	 * change state before continuing. If this does not occur
	 * in a reasonable time, a <tt>BundleException</tt> is thrown to indicate
	 * this bundle was unable to be started.
	 *
	 * <li>If this bundle's state is <tt>ACTIVE</tt> then this method returns immediately.
	 *
	 * <li>If this bundle's state is not <tt>RESOLVED</tt>,
	 * an attempt is made to resolve this bundle's package dependencies.
	 * If the Framework cannot resolve this bundle, a <tt>BundleException</tt> is thrown.
	 *
	 * <li>This bundle's state is set to <tt>STARTING</tt>.
	 *
	 * <li>The {@link BundleActivator#start}method of this
	 * bundle's <tt>BundleActivator</tt>, if one is specified, is called.
	 * If the <tt>BundleActivator</tt> is invalid or throws an exception, this bundle's state
	 * is set back to <tt>RESOLVED</tt>.
	 * <br>Any services registered by the bundle will be unregistered.
	 * <br>Any services used by the bundle will be released.
	 * <br>Any listeners registered by the bundle will be removed.
	 * <br>A <tt>BundleException</tt> is then thrown.
	 *
	 * <li> If this bundle's state is <tt>UNINSTALLED</tt>,
	 * because the bundle was uninstalled while the <tt>BundleActivator.start</tt>
	 * method was running, a <tt>BundleException</tt> is thrown.
	 *
	 * <li>Since it is recorded that this bundle has been started, when
	 * the Framework is restarted this bundle will be automatically started.
	 *
	 * <li>This bundle's state is set to <tt>ACTIVE</tt>.
	 *
	 * <li>A bundle event of type {@link BundleEvent#STARTED}is broadcast.
	 * </ol>
	 *
	 * <b>Preconditions</b>
	 * <ul>
	 * <li><tt>getState()</tt> in {<tt>INSTALLED</tt>}, {<tt>RESOLVED</tt>}.
	 * </ul>
	 * <b>Postconditions, no exceptions thrown</b>
	 * <ul>
	 * <li><tt>getState()</tt> in {<tt>ACTIVE</tt>}.
	 * <li><tt>BundleActivator.start()</tt> has been called and did not throw an exception.
	 * </ul>
	 * <b>Postconditions, when an exception is thrown</b>
	 * <ul>
	 * <li><tt>getState()</tt> not in {<tt>STARTING</tt>}, {<tt>ACTIVE</tt>}.
	 * </ul>
	 *
	 * @exception BundleException If this bundle couldn't be started.
	 * This could be because a code dependency could not be resolved or
	 * the specified <tt>BundleActivator</tt> could not be loaded or threw an exception.
	 * @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>AdminPermisson</tt>, and the Java Runtime Environment
	 * supports permissions.
	 */
    public abstract void start() throws BundleException;

    /**
	 * Stops this bundle.
	 *
	 * <p> The following steps are required to stop 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>STARTING</tt> or <tt>STOPPING</tt>
	 * then this method will wait for this bundle to
	 * change state before continuing. If this does not occur
	 * in a reasonable time, a <tt>BundleException</tt> is thrown to indicate
	 * this bundle was unable to be stopped.
	 *
	 * <li>If this bundle's state is not <tt>ACTIVE</tt> then this method returns immediately.
	 *
	 * <li> This bundle's state is set to <tt>STOPPING</tt>.
	 *
	 * <li>Since it is recorded that this bundle has been stopped,
	 * Framework is restarted this bundle will not be automatically started.
	 *
	 * <li>The {@link BundleActivator#stop}method of this
	 * bundle's <tt>BundleActivator</tt>, if one is specified, is called.
	 * If this method throws an exception, it will continue to stop this bundle.
	 * A <tt>BundleException</tt> will be thrown after completion of the
	 * remaining steps.
	 *
	 * <li>Any services registered by this bundle must be unregistered.
	 * <li>Any services used by this bundle must be released.
	 * <li>Any listeners registered by this bundle must be removed.
	 *
	 * <li> If this bundle's state is <tt>UNINSTALLED</tt>,
	 * because the bundle was uninstalled while the <tt>BundleActivator.stop</tt>
	 * method was running, a <tt>BundleException</tt> must be thrown.
	 *
	 * <li>This bundle's state is set to <tt>RESOLVED</tt>.
	 *
	 * <li>A bundle event of type {@link BundleEvent#STOPPED}is broadcast.
	 * </ol>
	 *
	 * <b>Preconditions</b>
	 * <ul>
	 * <li><tt>getState()</tt> in {<tt>ACTIVE</tt>}.
	 * </ul>
	 * <b>Postconditions, no exceptions thrown</b>
	 * <ul>
	 * <li><tt>getState()</tt> not in {<tt>ACTIVE</tt>, <tt>STOPPING</tt>}.
	 * <li><tt>BundleActivator.stop</tt> has been called and did not throw an exception.
	 * </ul>
	 * <b>Postconditions, when an exception is thrown</b>
	 * <ul>
	 * <li>None.
	 * </ul>
	 *
	 * @exception BundleException If this bundle's
	 * <tt>BundleActivator</tt> could not be loaded or threw an exception.
	 * @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.
	 */
    public abstract void stop() throws BundleException;

    /**
	 * Updates this bundle.
	 *
	 * <p>If this bundle's state is <tt>ACTIVE</tt>, it will be stopped
	 * before the update and started after the update successfully completes.
	 *
	 * <p>If the bundle being updated has exported any packages, these
	 * packages will not be updated. Instead, the previous package version will remain
	 * exported until the <tt>PackageAdmin.refreshPackages</tt> method has been
	 * has been called or the Framework is relaunched.
	 *
	 * <p> The following steps are required to update a bundle: