/* * $Header: /cvshome/repository/org/osgi/framework/Bundle.java,v 1.19 2002/11/14 13:48:30 pkriens Exp $ * * 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.net.URL;import java.util.Dictionary;/** * 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.19 $ * @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.	 *