bundlecontext.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.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.1.1.1 $
 * @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>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();

    /**
	 * Adds the specified <tt>ServiceListener</tt> object with the specified
	 * <tt>filter</tt> to this context bundle's list of listeners. <p>See
	 * {@link #getBundle}for a definition of context bundle, and
	 * {@link Filter}for a description of the filter syntax.
	 * <tt>ServiceListener</tt> objects are notified when a service has a lifecycle state
	 * change.
	 *
	 * <p>If this context bundle's list of listeners already contains a
	 * listener <tt>l</tt> such that <tt>(l==listener)</tt>, this method
	 * replaces that listener's filter (which may be <tt>null</tt>) with the
	 * specified one (which may be <tt>null</tt>).
	 *
	 * <p>The listener is called if the filter criteria is met.
	 * To filter based upon the class of the service, the filter
	 * should reference the {@link Constants#OBJECTCLASS}property.
	 * If <tt>filter</tt> is <tt>null</tt>, all services
	 * are considered to match the filter.
	 *
	 * <p>When using a <tt>filter</tt>, it is possible that the <tt>ServiceEvent</tt>s
	 * for the complete life cycle of a service will not be delivered to
	 * the listener.
	 * For example, if the <tt>filter</tt> only matches when the property <tt>x</tt>
	 * has the value <tt>1</tt>, the listener will not be called
	 * if the service is registered with the property <tt>x</tt> not set to the value
	 * <tt>1</tt>. Subsequently, when the service is modified setting
	 * property <tt>x</tt> to the value <tt>1</tt>, the filter will match
	 * and the listener will be called with a <tt>ServiceEvent</tt>
	 * of type <tt>MODIFIED</tt>. Thus, the listener will not be called with a
	 * <tt>ServiceEvent</tt> of type <tt>REGISTERED</tt>.
	 *
	 * <p>If the Java Runtime Environment supports permissions, the
	 * <tt>ServiceListener</tt> object will be notified of a service event only
	 * if the bundle that is registering it has the <tt>ServicePermission</tt>
	 * to get the service using at least one of the named classes the service was registered under.
	 *
	 * @param listener The <tt>ServiceListener</tt> object to be added.
	 * @param filter The filter criteria.
	 *
	 * @exception InvalidSyntaxException If <tt>filter</tt> contains
	 * an invalid filter string which cannot be parsed.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 *
	 * @see ServiceEvent
	 * @see ServiceListener
	 * @see ServicePermission
	 */
    public abstract void addServiceListener(ServiceListener listener,
                        String filter)
    throws InvalidSyntaxException;

    /**
	 * Adds the specified <tt>ServiceListener</tt> object to this context bundle's list of
	 * listeners.
	 *
	 * <p> This method is the same as calling <tt>BundleContext.addServiceListener(ServiceListener listener,
	 * String filter)</tt> with <tt>filter</tt> set to <tt>null</tt>.
	 *
	 * @param listener The <tt>ServiceListener</tt> object to be added.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 *
	 * @see #addServiceListener(ServiceListener, String)
	 */
    public abstract void addServiceListener(ServiceListener listener);

    /**
	 * Removes the specified <tt>ServiceListener</tt> object from this context bundle's list of listeners.
	 * See {@link #getBundle}for a definition of context bundle.
	 *
	 * <p>If <tt>listener</tt> is not contained in this context bundle's list
	 * of listeners, this method does nothing.
	 *
	 * @param listener The <tt>ServiceListener</tt> to be removed.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 */
    public abstract void removeServiceListener(ServiceListener listener);

    /**
	 * Adds the specified <tt>BundleListener</tt> object to this context bundle's
	 * list of listeners if not already present.
	 * See {@link #getBundle}for a definition of context bundle.
	 * BundleListener objects are notified when a bundle has a lifecycle state change.
	 *
	 * <p>If this context bundle's list of listeners already contains a
	 * listener <tt>l</tt> such that <tt>(l==listener)</tt>, this method does
	 * nothing.
	 *
	 * @param listener The <tt>BundleListener</tt> to be added.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 *
	 * @see BundleEvent
	 * @see BundleListener
	 */
    public abstract void addBundleListener(BundleListener listener);

    /**
	 * Removes the specified <tt>BundleListener</tt> object from this context bundle's list of listeners.
	 * See {@link #getBundle}for a definition of context bundle.
	 *
	 * <p> If <tt>listener</tt> is not contained in this context bundle's list
	 * of listeners, this method does nothing.
	 *
	 * @param listener The <tt>BundleListener</tt> object to be removed.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 */
    public abstract void removeBundleListener(BundleListener listener);