bundlecontext.java

OSGI 的 源码实现,采用JAVA书写

/*
 * $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();