/* * $Header: /cvshome/repository/org/osgi/framework/BundleContext.java,v 1.21 2002/11/14 13:49:34 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.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><tt>BundleContext</tt> 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 <tt>ServiceReferences</tt> 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 <tt>File</tt> objects for files in a * persistent storage area provided for the bundle by the Framework. * </ul> * * <p>A <tt>BundleContext</tt> object will be created and provided * to this bundle when it is started using the {@link BundleActivator#start}method. * The same <tt>BundleContext</tt> object will be passed to this bundle when it is * stopped using the {@link BundleActivator#stop}method. * <tt>BundleContext</tt> is generally for the private use of this bundle and * is not meant to be shared with other bundles in the OSGi environment. <tt>BundleContext</tt> is used * when resolving <tt>ServiceListener</tt>s and <tt>EventListener</tt> objects. * * <p> The <tt>BundleContext</tt> object is only valid during an execution instance of * this bundle; that is, during the period from when this bundle is called by * <tt>BundleActivator.start</tt> until after this bundle is called and returns from * <tt>BundleActivator.stop</tt> (or if <tt>BundleActivator.start</tt> terminates with an exception). * If the <tt>BundleContext</tt> object is used subsequently, * an <tt>IllegalStateException</tt> must be thrown. * When this bundle is restarted, a new <tt>BundleContext</tt> object must be created. * * <p>The Framework is the only entity that can create <tt>BundleContext</tt> * objects and they are only valid within the Framework that created them. * * @version $Revision: 1.21 $ * @author Open Services Gateway Initiative */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	 * <tt>null</tt> 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}<tt>Manifest</tt> 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 <tt>null</tt> if the property is undefined.	 * @exception java.lang.SecurityException If the caller does not have	 * the appropriate <tt>PropertyPermission</tt> to read the property,	 * and the Java Runtime Environment supports permissions.	 */    public abstract String getProperty(String key);    /**	 * Returns the <tt>Bundle</tt> object for this context bundle.	 *	 * <p>The context bundle is defined as the bundle that was assigned	 * this <tt>BundleContext</tt> in its <tt>BundleActivator</tt>.	 *	 * @return The context bundle's <tt>Bundle</tt> object.	 * @exception java.lang.IllegalStateException If this context bundle has stopped.	 */    public abstract Bundle getBundle();    /**	 * Installs the bundle from the specified location string. A bundle is obtained	 * from <tt>location</tt> 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 <tt>Bundle</tt> 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 <tt>Bundle-NativeCode</tt>	 * dependencies are resolved. If this fails, a <tt>BundleException</tt> 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 <tt>BundleException</tt> 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 <tt>BundleException</tt> must be thrown.	 *	 * <li>The bundle's state is set to <tt>INSTALLED</tt>.	 *	 * <li>If the bundle has not declared an Import-Package Manifest header	 * (that is, the bundle does not depend on any packages from other OSGi bundles), the	 * bundle's state may be set to <tt>RESOLVED</tt>.	 *	 * <li>A bundle event of type {@link BundleEvent#INSTALLED}is broadcast.	 *	 * <li>The <tt>Bundle</tt> object for the newly installed bundle is returned.	 * </ol>	 *	 * <b>Postconditions, no exceptions thrown</b>	 * <ul>	 * <li><tt>getState()</tt> in {<tt>INSTALLED</tt>}, <tt>RESOLVED</tt>}.	 * <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 <tt>Bundle</tt> object of the installed bundle.	 * @exception BundleException If the installation failed.	 * @exception java.lang.SecurityException If the caller does not have	 * the appropriate <tt>AdminPermission</tt>, and the Java Runtime Environment supports permissions.	 */    public abstract Bundle installBundle(String location)    throws BundleException;    /**	 * Installs the bundle from the specified <tt>InputStream</tt> object.	 *	 * <p>This method performs all of the steps listed in <tt>BundleContext.installBundle(String location)</tt>,	 * except that the bundle's content will be read from the <tt>InputStream</tt> object.	 * The location identifier string specified will be used as the identity of the bundle.	 *	 * <p>This method must always close the <tt>InputStream</tt> object, even if an exception is thrown.	 * @param location The location identifier of the bundle to install.	 * @param in The <tt>InputStream</tt> object from which this bundle will be read.	 * @return The <tt>Bundle</tt> 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 <tt>AdminPermission</tt>, and the Java Runtime Environment supports permissions.	 * @see #installBundle(java.lang.String)	 */    public abstract Bundle installBundle(String location, InputStream in)    throws BundleException;    /**	 * Returns the bundle with the specified identifier.	 *	 * @param id The identifier of the bundle to retrieve.	 * @return A <tt>Bundle</tt> object, or <tt>null</tt> 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, as the Framework is a very dynamic	 * environment, bundles can be installed or uninstalled at anytime.	 *	 * @return An array of <tt>Bundle</tt> objects; one object per installed bundle.	 */    public abstract Bundle[] getBundles();