You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by ri...@apache.org on 2005/08/16 20:34:41 UTC
svn commit: r233031 [17/21] - in /incubator/oscar/trunk: ./ etc/ lib/ src/
src/org/ src/org/apache/ src/org/apache/osgi/ src/org/apache/osgi/bundle/
src/org/apache/osgi/bundle/bundlerepository/
src/org/apache/osgi/bundle/bundlerepository/kxmlsax/ src/o...
Added: incubator/oscar/trunk/src/org/osgi/framework/Bundle.java
URL: http://svn.apache.org/viewcvs/incubator/oscar/trunk/src/org/osgi/framework/Bundle.java?rev=233031&view=auto
==============================================================================
--- incubator/oscar/trunk/src/org/osgi/framework/Bundle.java (added)
+++ incubator/oscar/trunk/src/org/osgi/framework/Bundle.java Tue Aug 16 11:33:34 2005
@@ -0,0 +1,932 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/Bundle.java,v 1.27 2005/06/21 16:37:35 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2000, 2005). All Rights Reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this
+ * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
+ */
+
+package org.osgi.framework;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URL;
+import java.util.Dictionary;
+import java.util.Enumeration;
+
+/**
+ * An installed bundle in the Framework.
+ *
+ * <p>
+ * A <code>Bundle</code> object is the access point to define the lifecycle of
+ * an installed bundle. Each bundle installed in the OSGi environment must have
+ * an associated <code>Bundle</code> object.
+ *
+ * <p>
+ * A bundle must have a unique identity, a <code>long</code>, chosen by the
+ * Framework. This identity must not change during the lifecycle of a bundle,
+ * even when the bundle is updated. Uninstalling and then reinstalling the
+ * bundle must 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
+ * <code>STARTING</code>,<code>ACTIVE</code>, or <code>STOPPING</code>.
+ * An <code>UNINSTALLED</code> bundle can not be set to another state; it is a
+ * zombie and can only be reached because references are kept somewhere.
+ *
+ * <p>
+ * The Framework is the only entity that is allowed to create
+ * <code>Bundle</code> objects, and these objects are only valid within the
+ * Framework that created them.
+ *
+ * @version $Revision: 1.27 $
+ */
+public abstract interface Bundle {
+ /**
+ * This bundle is uninstalled and may not be used.
+ *
+ * <p>
+ * The <code>UNINSTALLED</code> state is only visible after a bundle is
+ * uninstalled; the bundle is in an unusable state but references to the
+ * <code>Bundle</code> object may still be available and used for
+ * introspection.
+ * <p>
+ * The value of <code>UNINSTALLED</code> is 0x00000001.
+ */
+ public static final int UNINSTALLED = 0x00000001;
+
+ /**
+ * This bundle is installed but not yet resolved.
+ *
+ * <p>
+ * A bundle is in the <code>INSTALLED</code> 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 <code>INSTALLED</code> bundle's
+ * code dependencies and move the bundle to the <code>RESOLVED</code>
+ * state.
+ * <p>
+ * The value of <code>INSTALLED</code> is 0x00000002.
+ */
+ public static final int INSTALLED = 0x00000002;
+
+ /**
+ * This bundle is resolved and is able to be started.
+ *
+ * <p>
+ * A bundle is in the <code>RESOLVED</code> 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.
+ * <li>The bundle's required bundle dependencies from its
+ * {@link Constants#REQUIRE_BUNDLE}Manifest header.
+ * <li>A fragment bundle's host dependency from its
+ * {@link Constants#FRAGMENT_HOST}Manifest header.
+ * </ul>
+ * <p>
+ * Note that the bundle is not active yet. A bundle must be put in the
+ * <code>RESOLVED</code> state before it can be started. The Framework may
+ * attempt to resolve a bundle at any time.
+ * <p>
+ * The value of <code>RESOLVED</code> is 0x00000004.
+ */
+ public static final int RESOLVED = 0x00000004;
+
+ /**
+ * This bundle is in the process of starting.
+ *
+ * <p>
+ * A bundle is in the <code>STARTING</code> state when the {@link #start}
+ * method is active. A bundle must 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 must move to the
+ * <code>ACTIVE</code> state.
+ * <p>
+ * The value of <code>STARTING</code> is 0x00000008.
+ */
+ public static final int STARTING = 0x00000008;
+
+ /**
+ * This bundle is in the process of stopping.
+ *
+ * <p>
+ * A bundle is in the <code>STOPPING</code> state when the {@link #stop}
+ * method is active. A bundle must be in this state when the bundle's
+ * {@link BundleActivator#stop}method is called. When this method completes
+ * the bundle is stopped and must move to the <code>RESOLVED</code> state.
+ * <p>
+ * The value of <code>STOPPING</code> is 0x00000010.
+ */
+ public static final int STOPPING = 0x00000010;
+
+ /**
+ * This bundle is now running.
+ *
+ * <p>
+ * A bundle is in the <code>ACTIVE</code> state when it has been
+ * successfully started.
+ * <p>
+ * The value of <code>ACTIVE</code> 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 <code>UNINSTALLED</code>,<code>INSTALLED</code>,
+ * <code>RESOLVED</code>,<code>STARTING</code>,
+ * <code>STOPPING</code>,<code>ACTIVE</code>.
+ */
+ public abstract int getState();
+
+ /**
+ * Starts this bundle.
+ *
+ * <p>
+ * 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 <code>UNINSTALLED</code> then an
+ * <code>IllegalStateException</code> is thrown.
+ *
+ * <li>If this bundle's state is <code>STARTING</code> or
+ * <code>STOPPING</code> then this method must wait for this bundle to
+ * change state before continuing. If this does not occur in a reasonable
+ * time, a <code>BundleException</code> is thrown to indicate this bundle
+ * was unable to be started.
+ *
+ * <li>If this bundle's state is <code>ACTIVE</code> then this method
+ * returns immediately.
+ *
+ * <li>Persistently record that this bundle has been started. When the
+ * Framework is restarted, this bundle must be automatically started.
+ *
+ * <li>If this bundle's state is not <code>RESOLVED</code>, an attempt
+ * is made to resolve this bundle's package dependencies. If the Framework
+ * cannot resolve this bundle, a <code>BundleException</code> is thrown.
+ *
+ * <li>This bundle's state is set to <code>STARTING</code>.
+ *
+ * <li>The {@link BundleActivator#start}method of this bundle's
+ * <code>BundleActivator</code>, if one is specified, is called. If the
+ * <code>BundleActivator</code> is invalid or throws an exception, this
+ * bundle's state is set back to <code>RESOLVED</code>.<br>
+ * Any services registered by the bundle must be unregistered. <br>
+ * Any services used by the bundle must be released. <br>
+ * Any listeners registered by the bundle must be removed. <br>
+ * A <code>BundleException</code> is then thrown.
+ *
+ * <li>If this bundle's state is <code>UNINSTALLED</code>, because the
+ * bundle was uninstalled while the <code>BundleActivator.start</code>
+ * method was running, a <code>BundleException</code> is thrown.
+ *
+ * <li>This bundle's state is set to <code>ACTIVE</code>.
+ *
+ * <li>A bundle event of type {@link BundleEvent#STARTED}is broadcast.
+ * </ol>
+ *
+ * <b>Preconditions </b>
+ * <ul>
+ * <li><code>getState()</code> in {<code>INSTALLED</code>}, {
+ * <code>RESOLVED</code>}.
+ * </ul>
+ * <b>Postconditions, no exceptions thrown </b>
+ * <ul>
+ * <li>Bundle persistent state is marked as active.
+ * <li><code>getState()</code> in {<code>ACTIVE</code>}.
+ * <li><code>BundleActivator.start()</code> has been called and did not
+ * throw an exception.
+ * </ul>
+ * <b>Postconditions, when an exception is thrown </b>
+ * <ul>
+ * <li>Depending on when the exception occurred, bundle persistent state is
+ * marked as active.
+ * <li><code>getState()</code> not in {<code>STARTING</code>}, {
+ * <code>ACTIVE</code>}.
+ * </ul>
+ *
+ * @exception BundleException If this bundle could not be started. This
+ * could be because a code dependency could not be resolved or
+ * the specified <code>BundleActivator</code> 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 <code>AdminPermission[bundle, EXECUTE]</code>,
+ * 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 <code>UNINSTALLED</code> then an
+ * <code>IllegalStateException</code> is thrown.
+ *
+ * <li>If this bundle's state is <code>STARTING</code> or
+ * <code>STOPPING</code> then this method must wait for this bundle to
+ * change state before continuing. If this does not occur in a reasonable
+ * time, a <code>BundleException</code> is thrown to indicate this bundle
+ * was unable to be stopped.
+ *
+ * <li>Persistently record that this bundle has been stopped. When the
+ * Framework is restarted, this bundle must not be automatically started.
+ *
+ * <li>If this bundle's state is not <code>ACTIVE</code> then this method
+ * returns immediately.
+ *
+ * <li>This bundle's state is set to <code>STOPPING</code>.
+ *
+ * <li>The {@link BundleActivator#stop}method of this bundle's
+ * <code>BundleActivator</code>, if one is specified, is called. If that
+ * method throws an exception, this method must continue to stop this
+ * bundle. A <code>BundleException</code> must 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 <code>UNINSTALLED</code>, because the
+ * bundle was uninstalled while the <code>BundleActivator.stop</code>
+ * method was running, a <code>BundleException</code> must be thrown.
+ *
+ * <li>This bundle's state is set to <code>RESOLVED</code>.
+ *
+ * <li>A bundle event of type {@link BundleEvent#STOPPED}is broadcast.
+ * </ol>
+ *
+ * <b>Preconditions </b>
+ * <ul>
+ * <li><code>getState()</code> in {<code>ACTIVE</code>}.
+ * </ul>
+ * <b>Postconditions, no exceptions thrown </b>
+ * <ul>
+ * <li>Bundle persistent state is marked as stopped.
+ * <li><code>getState()</code> not in {<code>ACTIVE</code>,
+ * <code>STOPPING</code>}.
+ * <li><code>BundleActivator.stop</code> has been called and did not
+ * throw an exception.
+ * </ul>
+ * <b>Postconditions, when an exception is thrown </b>
+ * <ul>
+ * <li>Bundle persistent state is marked as stopped.
+ * </ul>
+ *
+ * @exception BundleException If this bundle's <code>BundleActivator</code>
+ * 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 <code>AdminPermission[bundle, EXECUTE]</code>,
+ * and the Java Runtime Environment supports permissions.
+ */
+ public abstract void stop() throws BundleException;
+
+ /**
+ * Updates this bundle.
+ *
+ * <p>
+ * If this bundle's state is <code>ACTIVE</code>, it must be stopped
+ * before the update and started after the update successfully completes.
+ *
+ * <p>
+ * If the bundle being updated has exported any packages, these packages
+ * must not be updated. Instead, the previous package version must remain
+ * exported until the <code>PackageAdmin.refreshPackages</code> method has
+ * been has been called or the Framework is relaunched.
+ *
+ * <p>
+ * The following steps are required to update a bundle:
+ * <ol>
+ * <li>If this bundle's state is <code>UNINSTALLED</code> then an
+ * <code>IllegalStateException</code> is thrown.
+ *
+ * <li>If this bundle's state is <code>ACTIVE</code>,
+ * <code>STARTING</code> or <code>STOPPING</code>, the bundle is
+ * stopped as described in the <code>Bundle.stop</code> method. If
+ * <code>Bundle.stop</code> throws an exception, the exception is rethrown
+ * terminating the update.
+ *
+ * <li>The download location of the new version of this bundle is
+ * determined from either the bundle's
+ * {@link Constants#BUNDLE_UPDATELOCATION}Manifest header (if available) or
+ * the bundle's original location.
+ *
+ * <li>The location is interpreted in an implementation dependent manner,
+ * typically as a URL, and the new version of this bundle is obtained from
+ * this location.
+ *
+ * <li>The new version of this bundle is installed. If the Framework is
+ * unable to install the new version of this bundle, the original version of
+ * this bundle must be restored and a <code>BundleException</code> must be
+ * thrown after completion of the remaining steps.
+ *
+ * <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 do not all match, the
+ * original version of this bundle must be restored and a
+ * <code>BundleException</code> must be thrown after completion of the
+ * remaining steps.
+ *
+ * <li>This bundle's state is set to <code>INSTALLED</code>.
+ *
+ * <li>If the new version of this bundle was successfully installed, a
+ * bundle event of type {@link BundleEvent#UPDATED}is broadcast.
+ *
+ * <li>If this bundle's state was originally <code>ACTIVE</code>, the
+ * updated bundle is started as described in the <code>Bundle.start</code>
+ * method. If <code>Bundle.start</code> throws an exception, a Framework
+ * event of type {@link FrameworkEvent#ERROR}is broadcast containing the
+ * exception.
+ * </ol>
+ *
+ * <b>Preconditions </b>
+ * <ul>
+ * <li><code>getState()</code> not in {<code>UNINSTALLED</code>}.
+ * </ul>
+ * <b>Postconditions, no exceptions thrown </b>
+ * <ul>
+ * <li><code>getState()</code> in {<code>INSTALLED</code>,
+ * <code>RESOLVED</code>,<code>ACTIVE</code>}.
+ * <li>This bundle has been updated.
+ * </ul>
+ * <b>Postconditions, when an exception is thrown </b>
+ * <ul>
+ * <li><code>getState()</code> in {<code>INSTALLED</code>,
+ * <code>RESOLVED</code>,<code>ACTIVE</code>}.
+ * <li>Original bundle is still used; no update occurred.
+ * </ul>
+ *
+ * @exception BundleException If the update fails.
+ * @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 <code>AdminPermission[bundle, LIFECYCLE]</code> for both
+ * the current bundle and the updated bundle,
+ * and the Java Runtime Environment supports permissions.
+ * @see #stop()
+ * @see #start()
+ */
+ public abstract void update() throws BundleException;
+
+ /**
+ * Updates this bundle from an <code>InputStream</code>.
+ *
+ * <p>
+ * This method performs all the steps listed in <code>Bundle.update()</code>,
+ * except the bundle must be read from the supplied <code>InputStream</code>,
+ * rather than a <code>URL</code>.
+ * <p>
+ * This method must always close the <code>InputStream</code> when it is
+ * done, even if an exception is thrown.
+ *
+ * @param in The <code>InputStream</code> from which to read the new
+ * bundle.
+ * @exception BundleException If the provided stream cannot be read or the
+ * update fails.
+ * @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 <code>AdminPermission[bundle, LIFECYCLE]</code> for both
+ * the current bundle and the updated bundle,
+ * and the Java Runtime Environment supports permissions.
+ * @see #update()
+ */
+ public abstract void update(InputStream in) throws BundleException;
+
+ /**
+ * Uninstalls this bundle.
+ *
+ * <p>
+ * This method causes the Framework to notify other bundles that this bundle
+ * is being uninstalled, and then puts this bundle into the
+ * <code>UNINSTALLED</code> state. The Framework must remove any resources
+ * related to this bundle that it is able to remove.
+ *
+ * <p>
+ * If this bundle has exported any packages, the Framework must continue to
+ * make these packages available to their importing bundles until the
+ * <code>PackageAdmin.refreshPackages</code> method has been called or the
+ * Framework is relaunched.
+ *
+ * <p>
+ * The following steps are required to uninstall a bundle:
+ * <ol>
+ * <li>If this bundle's state is <code>UNINSTALLED</code> then an
+ * <code>IllegalStateException</code> is thrown.
+ *
+ * <li>If this bundle's state is <code>ACTIVE</code>,
+ * <code>STARTING</code> or <code>STOPPING</code>, this bundle is
+ * stopped as described in the <code>Bundle.stop</code> method. If
+ * <code>Bundle.stop</code> throws an exception, a Framework event of type
+ * {@link FrameworkEvent#ERROR}is broadcast containing the exception.
+ *
+ * <li>This bundle's state is set to <code>UNINSTALLED</code>.
+ *
+ * <li>A bundle event of type {@link BundleEvent#UNINSTALLED}is broadcast.
+ *
+ * <li>This bundle and any persistent storage area provided for this bundle
+ * by the Framework are removed.
+ * </ol>
+ *
+ * <b>Preconditions </b>
+ * <ul>
+ * <li><code>getState()</code> not in {<code>UNINSTALLED</code>}.
+ * </ul>
+ * <b>Postconditions, no exceptions thrown </b>
+ * <ul>
+ * <li><code>getState()</code> in {<code>UNINSTALLED</code>}.
+ * <li>This bundle has been uninstalled.
+ * </ul>
+ * <b>Postconditions, when an exception is thrown </b>
+ * <ul>
+ * <li><code>getState()</code> not in {<code>UNINSTALLED</code>}.
+ * <li>This Bundle has not been uninstalled.
+ * </ul>
+ *
+ * @exception BundleException If the uninstall failed. This can occur if
+ * another thread is attempting to change the bundle's state and
+ * does not complete in a timely manner.
+ * @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 <code>AdminPermission[bundle, LIFECYCLE]</code>,
+ * and the Java Runtime Environment supports permissions.
+ * @see #stop()
+ */
+ public abstract void uninstall() throws BundleException;
+
+ /**
+ * Returns this bundle's Manifest headers and values. This method returns
+ * all the Manifest headers and values from the main section of the bundle's
+ * Manifest file; that is, all lines prior to the first blank line.
+ *
+ * <p>
+ * Manifest header names are case-insensitive. The methods of the returned
+ * <code>Dictionary</code> object must operate on header names in a
+ * case-insensitive manner.
+ *
+ * If a Manifest header value starts with "%", it must be
+ * localized according to the default locale.
+ *
+ * <p>
+ * For example, the following Manifest headers and values are included if
+ * they are present in the Manifest file:
+ *
+ * <pre>
+ * Bundle-Name
+ * Bundle-Vendor
+ * Bundle-Version
+ * Bundle-Description
+ * Bundle-DocURL
+ * Bundle-ContactAddress
+ * </pre>
+ *
+ * <p>
+ * This method must continue to return Manifest header information while
+ * this bundle is in the <code>UNINSTALLED</code> state.
+ *
+ * @return A <code>Dictionary</code> object containing this bundle's
+ * Manifest headers and values.
+ *
+ * @exception java.lang.SecurityException If the caller does not have the appropriate
+ * <code>AdminPermission[bundle, METADATA]</code>, and the
+ * Java Runtime Environment supports permissions.
+ *
+ * @see Constants#BUNDLE_LOCALIZATION
+ */
+ public abstract Dictionary getHeaders();
+
+ /**
+ * Returns this bundle's identifier. The bundle is assigned a unique
+ * identifier by the Framework when it is installed in the OSGi environment.
+ *
+ * <p>
+ * A bundle's unique identifier has the following attributes:
+ * <ul>
+ * <li>Is unique and persistent.
+ * <li>Is a <code>long</code>.
+ * <li>Its value is not reused for another bundle, even after the bundle is
+ * uninstalled.
+ * <li>Does not change while the bundle remains installed.
+ * <li>Does not change when the bundle is updated.
+ * </ul>
+ *
+ * <p>
+ * This method must continue to return this bundle's unique identifier while
+ * this bundle is in the <code>UNINSTALLED</code> state.
+ *
+ * @return The unique identifier of this bundle.
+ */
+ public abstract long getBundleId();
+
+ /**
+ * Returns this bundle's location identifier.
+ *
+ * <p>
+ * The bundle location identifier is the location passed to
+ * <code>BundleContext.installBundle</code> when a bundle is installed.
+ * The bundle location identifier does not change while the bundle remains
+ * installed, even if the bundle is updated.
+ *
+ * <p>
+ * This method must continue to return this bundle's location identifier
+ * while this bundle is in the <code>UNINSTALLED</code> state.
+ *
+ * @return The string representation of this bundle's location identifier.
+ * @exception java.lang.SecurityException If the caller does not have the
+ * appropriate <code>AdminPermission[bundle, METADATA]</code>,
+ * and the Java Runtime Environment supports permissions.
+ */
+ public abstract String getLocation();
+
+ /**
+ * Returns this bundle's <code>ServiceReference</code> list for all
+ * services it has registered or <code>null</code> if this bundle has no
+ * registered services.
+ *
+ * <p>
+ * If the Java runtime supports permissions, a <code>ServiceReference</code>
+ * object to a service is included in the returned list only if the caller
+ * has the <code>ServicePermission</code> to get the service using at
+ * least one of the named classes the service was registered under.
+ *
+ * <p>
+ * The list is valid at the time of the call to this method, however, as the
+ * Framework is a very dynamic environment, services can be modified or
+ * unregistered at anytime.
+ *
+ * @return An array of <code>ServiceReference</code> objects or
+ * <code>null</code>.
+ * @exception java.lang.IllegalStateException If this bundle has been
+ * uninstalled.
+ * @see ServiceRegistration
+ * @see ServiceReference
+ * @see ServicePermission
+ */
+ public abstract ServiceReference[] getRegisteredServices();
+
+ /**
+ * Returns this bundle's <code>ServiceReference</code> list for all
+ * services it is using or returns <code>null</code> if this bundle is not
+ * using any services. A bundle is considered to be using a service if its
+ * use count for that service is greater than zero.
+ *
+ * <p>
+ * If the Java Runtime Environment supports permissions, a
+ * <code>ServiceReference</code> object to a service is included in the
+ * returned list only if the caller has the <code>ServicePermission</code>
+ * to get the service using at least one of the named classes the service
+ * was registered under.
+ * <p>
+ * The list is valid at the time of the call to this method, however, as the
+ * Framework is a very dynamic environment, services can be modified or
+ * unregistered at anytime.
+ *
+ * @return An array of <code>ServiceReference</code> objects or
+ * <code>null</code>.
+ * @exception java.lang.IllegalStateException If this bundle has been
+ * uninstalled.
+ * @see ServiceReference
+ * @see ServicePermission
+ */
+ public abstract ServiceReference[] getServicesInUse();
+
+ /**
+ * Determines if this bundle has the specified permissions.
+ *
+ * <p>
+ * If the Java Runtime Environment does not support permissions, this method
+ * always returns <code>true</code>.
+ * <p>
+ * <code>permission</code> is of type <code>Object</code> to avoid
+ * referencing the <code>java.security.Permission</code> class directly.
+ * This is to allow the Framework to be implemented in Java environments
+ * which do not support permissions.
+ *
+ * <p>
+ * If the Java Runtime Environment does support permissions, this bundle and
+ * all its resources including embedded JAR files, belong to the same
+ * <code>java.security.ProtectionDomain</code>; that is, they must share
+ * the same set of permissions.
+ *
+ * @param permission The permission to verify.
+ *
+ * @return <code>true</code> if this bundle has the specified permission
+ * or the permissions possessed by this bundle imply the specified
+ * permission; <code>false</code> if this bundle does not have the
+ * specified permission or <code>permission</code> is not an
+ * <code>instanceof</code> <code>java.security.Permission</code>.
+ *
+ * @exception java.lang.IllegalStateException If this bundle has been
+ * uninstalled.
+ */
+ public abstract boolean hasPermission(Object permission);
+
+ /**
+ * Find the specified resource from this bundle.
+ *
+ * This bundle's class loader is called to search for the named resource. If
+ * this bundle's state is <code>INSTALLED</code>, then only this bundle
+ * must be searched for the specified resource. Imported packages cannot be
+ * searched when a bundle has not been resolved. If this bundle is a
+ * fragment bundle then <code>null</code> is returned.
+ *
+ * @param name The name of the resource. See
+ * <code>java.lang.ClassLoader.getResource</code> for a description
+ * of the format of a resource name.
+ * @return a URL to the named resource, or <code>null</code> if the
+ * resource could not be found or if this bundle is a fragment
+ * bundle or if the caller does not have the appropriate
+ * <code>AdminPermission[bundle, RESOURCE]</code>, and the Java
+ * Runtime Environment supports permissions.
+ *
+ * @since 1.1
+ * @exception java.lang.IllegalStateException If this bundle has been
+ * uninstalled.
+ */
+ public abstract URL getResource(String name);
+
+ /**
+ * Returns this bundle's Manifest headers and values localized to the
+ * specifed locale.
+ *
+ * <p>
+ * This method performs the same function as
+ * <code>Bundle.getHeaders()</code> except the manifest header values are
+ * localized to the specified locale.
+ *
+ * If a Manifest header value starts with "%", it must be
+ * localized according to the specified locale. If the specified locale
+ * cannot be found, then the header values must be returned using the
+ * default locale.
+ *
+ * If <code>null</code> is specified as the locale string, the header
+ * values must be localized using the default locale. If the empty string
+ * ("") is specified as the locale string, the header values must
+ * not be localized and the raw (unlocalized) header values, including any
+ * leading "%", must be returned.
+ *
+ * <p>
+ * This method must continue to return Manifest header information while
+ * this bundle is in the <code>UNINSTALLED</code> state, however the
+ * header values must only be available in the raw and default locale
+ * values.
+ *
+ * @param locale The locale name into which the header values are to be
+ * localized. If the specified locale is <code>null</code> then the
+ * locale returned by <code>java.util.Locale.getDefault</code> is
+ * used. If the specified locale is the empty string, this method
+ * will return the raw (unlocalized) manifest headers including any
+ * leading "%".
+ * @return A <code>Dictionary</code> object containing this bundle's
+ * Manifest headers and values.
+ *
+ * @exception java.lang.SecurityException If the caller does not have the appropriate
+ * <code>AdminPermission[bundle, METADATA]</code>, and the
+ * Java Runtime Environment supports permissions.
+ *
+ * @see #getHeaders()
+ * @see Constants#BUNDLE_LOCALIZATION
+ * @since 1.3
+ */
+ public Dictionary getHeaders(String locale);
+
+ /**
+ * Returns the symbolic name of this bundle as specified by its
+ * <code>Bundle-SymbolicName</code> manifest header. The name must be
+ * unique, it is recommended to use a reverse domain name naming convention
+ * like that used for java packages. If the bundle does not have a specified
+ * symbolic name then <code>null</code> is returned.
+ *
+ * <p>
+ * This method must continue to return this bundle's symbolic name while
+ * this bundle is in the <code>UNINSTALLED</code> state.
+ *
+ * @return The symbolic name of this bundle.
+ * @since 1.3
+ */
+ public String getSymbolicName();
+
+ /**
+ *
+ * Loads the specified class using this bundle's classloader.
+ *
+ * <p>
+ * If the bundle is a fragment bundle then this method must throw a
+ * <code>ClassNotFoundException</code>.
+ *
+ * <p>
+ * If this bundle's state is <code>INSTALLED</code>, this method must
+ * attempt to resolve the bundle before attempting to load the class.
+ *
+ * <p>
+ * If the bundle cannot be resolved, a Framework event of type
+ * {@link FrameworkEvent#ERROR}is broadcast containing a
+ * <code>BundleException</code> with details of the reason the bundle
+ * could not be resolved. This method must then throw a
+ * <code>ClassNotFoundException</code>.
+ *
+ * <p>
+ * If this bundle's state is <code>UNINSTALLED</code>, then an
+ * <code>IllegalStateException</code> is thrown.
+ *
+ * @param name The name of the class to load.
+ * @return The Class object for the requested class.
+ * @exception java.lang.ClassNotFoundException If no such class can be found
+ * or if this bundle is a fragment bundle or if the caller does
+ * not have the appropriate <code>AdminPermission[bundle, CLASS]</code>,
+ * and the Java Runtime Environment supports permissions.
+ * @exception java.lang.IllegalStateException If this bundle has been
+ * uninstalled.
+ * @since 1.3
+ */
+ public Class loadClass(String name) throws ClassNotFoundException;
+
+ /**
+ * Find the specified resources from this bundle.
+ *
+ * This bundle's class loader is called to search for the named resource. If
+ * this bundle's state is <code>INSTALLED</code>, then only this bundle
+ * must be searched for the specified resource. Imported packages cannot be
+ * searched when a bundle has not been resolved. If this bundle is a
+ * fragment bundle then <code>null</code> is returned.
+ *
+ * @param name The name of the resource. See
+ * <code>java.lang.ClassLoader.getResources</code> for a
+ * description of the format of a resource name.
+ * @return an Enumeration of URLs to the named resources, or
+ * <code>null</code> if the resource could not be found or if this
+ * bundle is a fragment bundle or if the caller does not have the appropriate
+ * <code>AdminPermission[bundle, RESOURCE]</code>, and the Java
+ * Runtime Environment supports permissions.
+ *
+ * @since 1.3
+ * @exception java.lang.IllegalStateException If this bundle has been
+ * uninstalled.
+ * @throws java.io.IOException If there is an I/O error.
+ */
+ public Enumeration getResources(String name) throws IOException;
+
+ /**
+ * Returns an Enumeration of all the paths (<code>String</code>) objects) to
+ * entries within the bundle whose longest sub-path matches the supplied path
+ * argument. The bundle's classloader is not used to search for entries. Only
+ * the contents of the bundle is searched. A specified path of "/"
+ * indicates the root of the bundle.
+ *
+ * <p>
+ * Returned paths indicating subdirectory paths end with a "/".
+ * The returned paths are all relative to the root of the bundle.
+ *
+ * <p>
+ * This method returns <code>null</code> if no entries could be found that
+ * match the specified path or if the caller does not have the appropriate
+ * <code>AdminPermission[bundle, RESOURCE]</code> and the Java
+ * Runtime Environment supports permissions.
+ *
+ * @param path the path name to get the entry path for.
+ * @return An Enumeration of the entry paths (<code>String</code> objects)
+ * or <code>null</code> if an entry could not be found or if the
+ * caller does not have the appropriate <code>AdminPermission[bundle, RESOURCE]</code>
+ * and the Java Runtime Environment supports permissions.
+ * @exception java.lang.IllegalStateException If this bundle has been
+ * uninstalled.
+ * @since 1.3
+ */
+ public Enumeration getEntryPaths(String path);
+
+ /**
+ * Returns a URL to the specified entry in this bundle. The bundle's
+ * classloader is not used to search for the specified entry. Only the
+ * contents of the bundle is searched for the specified entry. A specified
+ * path of "/" indicates the root of the bundle.
+ *
+ * <p>
+ * This method returns a URL to the specified entry, or <code>null</code>
+ * if the entry could not be found or if the caller does not have the appropriate
+ * <code>AdminPermission[bundle, RESOURCE]</code> and the Java Runtime
+ * Environment supports permissions.
+ *
+ * @param name The name of the entry. See
+ * <code>java.lang.ClassLoader.getResource</code> for a description
+ * of the format of a resource name.
+ * @return A URL to the specified entry, or <code>null</code> if the entry
+ * could not be found or if the caller does not have the appropriate
+ * <code>AdminPermission[bundle, RESOURCE]</code> and the Java
+ * Runtime Environment supports permissions.
+ *
+ * @exception java.lang.IllegalStateException If this bundle has been
+ * uninstalled.
+ * @since 1.3
+ */
+ public URL getEntry(String name);
+
+ /**
+ * Returns the time when this bundle was last modified. A bundle is
+ * considered to be modified when it is installed, updated or uninstalled.
+ *
+ * <p>
+ * The time value is the number of milliseconds since January 1, 1970,
+ * 00:00:00 GMT.
+ *
+ * @return The time when this bundle was last modified.
+ * @since 1.3
+ */
+ public long getLastModified();
+
+ /**
+ * Returns entries in this bundle and its attached fragments. The bundle's
+ * classloader is not used to search for entries. Only the contents of the
+ * bundle and its attached fragments are searched for the specified
+ * entries.
+ *
+ * If this bundle's state is <code>INSTALLED</code>, this method must
+ * attempt to resolve the bundle before attempting to find entries.<p>
+ *
+ * This method is intended to be used to obtain configuration, setup,
+ * localization and other information from this bundle. This method takes
+ * into account that the "contents" of this bundle can be extended
+ * with fragments. This "bundle space" is not a namespace with
+ * unique members; the same entry name can be present multiple times. This
+ * method therefore returns an enumeration of URL objects. These URLs can
+ * come from different JARs but have the same path name. This method can
+ * either return only entries in the specified path or recurse into
+ * subdirectories returning entries in the directory tree beginning at the
+ * specified path. Fragments can be attached after this bundle is resolved,
+ * possibly changing the set of URLs returned by this method. If this bundle
+ * is not resolved, only the entries in the JAR file of this bundle are
+ * returned.
+ * <p>
+ * Examples:
+ * <pre>
+ * // List all XML files in the OSGI-INF directory and below
+ * Enumeration e = b.findEntries("OSGI-INF", "*.xml", true);
+ *
+ * // Find a specific localization file
+ * Enumeration e = b.findEntries("OSGI-INF/l10n",
+ * "bundle_nl_DU.properties", false);
+ * if (e.hasMoreElements())
+ * return (URL) e.nextElement();
+ * </pre>
+ *
+ * @param path The path name in which to look. A specified path of
+ * "/" indicates the root of the bundle. Path is relative
+ * to the root of the bundle and must not be null.
+ * @param filePattern The file name pattern for selecting entries in the
+ * specified path. The pattern is only matched against the last
+ * element of the entry path and it supports substring matching, as
+ * specified in the Filter specification, using the wildcard
+ * character ("*"). If null is specified, this is
+ * equivalent to "*" and matches all files.
+ * @param recurse If <code>true</code>, recurse into subdirectories.
+ * Otherwise only return entries from the given directory.
+ * @return An enumeration of URL objects for each matching entry, or
+ * <code>null</code> if an entry could not be found or if the
+ * caller does not have the appropriate
+ * <code>AdminPermission[bundle, RESOURCE]</code>, and the Java
+ * Runtime Environment supports permissions. The URLs are sorted
+ * such that entries from this bundle are returned first followed by
+ * the entries from attached fragments in ascending bundle id order.
+ * If this bundle is a fragment, then only matching entries in this
+ * fragment are returned.
+ * @since 1.3
+ */
+ public Enumeration findEntries(String path, String filePattern,
+ boolean recurse);
+}
\ No newline at end of file
Added: incubator/oscar/trunk/src/org/osgi/framework/BundleActivator.java
URL: http://svn.apache.org/viewcvs/incubator/oscar/trunk/src/org/osgi/framework/BundleActivator.java?rev=233031&view=auto
==============================================================================
--- incubator/oscar/trunk/src/org/osgi/framework/BundleActivator.java (added)
+++ incubator/oscar/trunk/src/org/osgi/framework/BundleActivator.java Tue Aug 16 11:33:34 2005
@@ -0,0 +1,82 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleActivator.java,v 1.8 2005/06/21 16:22:12 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2000, 2005). All Rights Reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this
+ * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
+ */
+
+package org.osgi.framework;
+
+/**
+ * Customizes the starting and stopping of a bundle.
+ * <p>
+ * <code>BundleActivator</code> is an interface that may be implemented when a
+ * bundle is started or stopped. The Framework can create instances of a
+ * bundle's <code>BundleActivator</code> as required. If an instance's
+ * <code>BundleActivator.start</code> method executes successfully, it is
+ * guaranteed that the same instance's <code>BundleActivator.stop</code> method
+ * will be called when the bundle is to be stopped.
+ *
+ * <p>
+ * <code>BundleActivator</code> is specified through the <code>Bundle-Activator</code>
+ * Manifest header. A bundle can only specify a single <code>BundleActivator</code>
+ * in the Manifest file. Fragment bundles must not have a <code>BundleActivator</code>.
+ * The form of the Manifest header is:
+ *
+ * <pre>
+ * Bundle-Activator: <i>class-name</i>
+ * </pre>
+ *
+ * where <code>class-name</code> is a fully qualified Java classname.
+ * <p>
+ * The specified <code>BundleActivator</code> class must have a public constructor
+ * that takes no parameters so that a <code>BundleActivator</code> object can be
+ * created by <code>Class.newInstance()</code>.
+ *
+ * @version $Revision: 1.8 $
+ */
+
+public abstract interface BundleActivator {
+ /**
+ * Called when this bundle is started so the Framework can perform the
+ * bundle-specific activities necessary to start this bundle. This method
+ * can be used to register services or to allocate any resources that this
+ * bundle needs.
+ *
+ * <p>
+ * This method must complete and return to its caller in a timely manner.
+ *
+ * @param context The execution context of the bundle being started.
+ * @exception java.lang.Exception If this method throws an exception, this
+ * bundle is marked as stopped and the Framework will remove this
+ * bundle's listeners, unregister all services registered by this
+ * bundle, and release all services used by this bundle.
+ * @see Bundle#start
+ */
+ public abstract void start(BundleContext context) throws Exception;
+
+ /**
+ * Called when this bundle is stopped so the Framework can perform the
+ * bundle-specific activities necessary to stop the bundle. In general, this
+ * method should undo the work that the <code>BundleActivator.start</code>
+ * method started. There should be no active threads that were started by
+ * this bundle when this bundle returns. A stopped bundle must
+ * not call any Framework objects.
+ *
+ * <p>
+ * This method must complete and return to its caller in a timely manner.
+ *
+ * @param context The execution context of the bundle being stopped.
+ * @exception java.lang.Exception If this method throws an exception, the
+ * bundle is still marked as stopped, and the Framework will
+ * remove the bundle's listeners, unregister all services
+ * registered by the bundle, and release all services used by the
+ * bundle.
+ * @see Bundle#stop
+ */
+ public abstract void stop(BundleContext context) throws Exception;
+}
+
Added: incubator/oscar/trunk/src/org/osgi/framework/BundleContext.java
URL: http://svn.apache.org/viewcvs/incubator/oscar/trunk/src/org/osgi/framework/BundleContext.java?rev=233031&view=auto
==============================================================================
--- incubator/oscar/trunk/src/org/osgi/framework/BundleContext.java (added)
+++ incubator/oscar/trunk/src/org/osgi/framework/BundleContext.java Tue Aug 16 11:33:34 2005
@@ -0,0 +1,790 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleContext.java,v 1.13 2005/06/21 16:22:12 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2000, 2005). All Rights Reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this
+ * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
+ */
+
+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>
+ * <code>BundleContext</code> 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 <code>ServiceReferences</code> 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 <code>File</code> objects for files in a persistent storage area
+ * provided for the bundle by the Framework.
+ * </ul>
+ *
+ * <p>
+ * A <code>BundleContext</code> object will be created and provided to the bundle
+ * associated with this context when it is started using the
+ * {@link BundleActivator#start} method. The same <code>BundleContext</code>
+ * object will be passed to the bundle associated with this context when it is
+ * stopped using the {@link BundleActivator#stop} method. A <code>BundleContext</code>
+ * object is generally for the private use of its associated bundle and is not
+ * meant to be shared with other bundles in the OSGi environment.
+ *
+ * <p>
+ * The <code>Bundle</code> object associated with a <code>BundleContext</code> object
+ * is called the <em>context bundle</em>.
+ *
+ * <p>
+ * The <code>BundleContext</code> object is only valid during the execution
+ * of its context bundle; that is, during the period from when the context
+ * bundle is in the <code>STARTING</code>, <code>STOPPING</code>, and
+ * <code>ACTIVE</code> bundle states. If the <code>BundleContext</code> object
+ * is used subsequently, an <code>IllegalStateException</code> must be thrown.
+ * The <code>BundleContext</code> object must never be reused after its
+ * context bundle is stopped.
+ *
+ * <p>
+ * The Framework is the only entity that can create <code>BundleContext</code>
+ * objects and they are only valid within the Framework that created them.
+ *
+ * @version $Revision: 1.13 $
+ */
+
+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 <code>null</code> 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} <code>Manifest</code> 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 <code>null</code> if the
+ * property is undefined.
+ * @exception java.lang.SecurityException If the caller does not have the
+ * appropriate <code>PropertyPermission</code> to read the
+ * property, and the Java Runtime Environment supports
+ * permissions.
+ */
+ public abstract String getProperty(String key);
+
+ /**
+ * Returns the <code>Bundle</code> object associated with this
+ * <code>BundleContext</code>. This bundle is called the context bundle.
+ *
+ * @return The <code>Bundle</code> object associated with this
+ * <code>BundleContext</code>.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract Bundle getBundle();
+
+ /**
+ * Installs a bundle from the specified location string. A bundle is
+ * obtained from <code>location</code> 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 <code>Bundle</code> 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 <code>Bundle-NativeCode</code> dependencies are resolved.
+ * If this fails, a <code>BundleException</code> 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 <code>BundleException</code> 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
+ * <code>BundleException</code> must be thrown.
+ *
+ * <li>The bundle's state is set to <code>INSTALLED</code>.
+ *
+ * <li>A bundle event of type {@link BundleEvent#INSTALLED} is broadcast.
+ *
+ * <li>The <code>Bundle</code> object for the newly or previously installed
+ * bundle is returned.
+ * </ol>
+ *
+ * <b>Postconditions, no exceptions thrown </b>
+ * <ul>
+ * <li><code>getState()</code> in {<code>INSTALLED</code>,<code>RESOLVED</code>}.
+ * <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 <code>Bundle</code> object of the installed bundle.
+ * @exception BundleException If the installation failed.
+ * @exception java.lang.SecurityException If the caller does not have the
+ * appropriate <code>AdminPermission</code>, and the Java Runtime
+ * Environment supports permissions.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract Bundle installBundle(String location)
+ throws BundleException;
+
+ /**
+ * Installs a bundle from the specified <code>InputStream</code> object.
+ *
+ * <p>
+ * This method performs all of the steps listed in
+ * <code>BundleContext.installBundle(String location)</code>, except that the
+ * bundle's content will be read from the <code>InputStream</code> object. The
+ * location identifier string specified will be used as the identity of the
+ * bundle.
+ *
+ * <p>
+ * This method must always close the <code>InputStream</code> object, even if
+ * an exception is thrown.
+ *
+ * @param location The location identifier of the bundle to install.
+ * @param input The <code>InputStream</code> object from which this bundle
+ * will be read.
+ * @return The <code>Bundle</code> 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 <code>AdminPermission</code>, and the Java Runtime
+ * Environment supports permissions.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ * @see #installBundle(java.lang.String)
+ */
+ public abstract Bundle installBundle(String location, InputStream input)
+ throws BundleException;
+
+ /**
+ * Returns the bundle with the specified identifier.
+ *
+ * @param id The identifier of the bundle to retrieve.
+ * @return A <code>Bundle</code> object or <code>null</code> 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, since the
+ * Framework is a very dynamic environment, bundles can be installed or
+ * uninstalled at anytime.
+ *
+ * @return An array of <code>Bundle</code> objects, one object per installed
+ * bundle.
+ */
+ public abstract Bundle[] getBundles();
+
+ /**
+ * Adds the specified <code>ServiceListener</code> object with the specified
+ * <code>filter</code> to the context bundle's list of listeners.
+ * See {@link Filter} for a description of the filter syntax.
+ * <code>ServiceListener</code> objects are notified when a service has a
+ * lifecycle state change.
+ *
+ * <p>
+ * If the context bundle's list of listeners already contains a listener
+ * <code>l</code> such that <code>(l==listener)</code>, then this method replaces
+ * that listener's filter (which may be <code>null</code>) with the specified
+ * one (which may be <code>null</code>).
+ *
+ * <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 <code>filter</code> is
+ * <code>null</code>, all services are considered to match the filter.
+ *
+ * <p>
+ * When using a <code>filter</code>, it is possible that the
+ * <code>ServiceEvent</code>s for the complete lifecycle of a service will
+ * not be delivered to the listener. For example, if the <code>filter</code>
+ * only matches when the property <code>x</code> has the value <code>1</code>,
+ * the listener will not be called if the service is registered with the
+ * property <code>x</code> not set to the value <code>1</code>. Subsequently,
+ * when the service is modified setting property <code>x</code> to the value
+ * <code>1</code>, the filter will match and the listener will be called with
+ * a <code>ServiceEvent</code> of type <code>MODIFIED</code>. Thus, the
+ * listener will not be called with a <code>ServiceEvent</code> of type
+ * <code>REGISTERED</code>.
+ *
+ * <p>
+ * If the Java Runtime Environment supports permissions, the
+ * <code>ServiceListener</code> object will be notified of a service event
+ * only if the bundle that is registering it has the
+ * <code>ServicePermission</code> to get the service using at least one of the
+ * named classes the service was registered under.
+ *
+ * @param listener The <code>ServiceListener</code> object to be added.
+ * @param filter The filter criteria.
+ *
+ * @exception InvalidSyntaxException If <code>filter</code> contains an
+ * invalid filter string that cannot be parsed.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @see ServiceEvent
+ * @see ServiceListener
+ * @see ServicePermission
+ */
+ public abstract void addServiceListener(ServiceListener listener,
+ String filter) throws InvalidSyntaxException;
+
+ /**
+ * Adds the specified <code>ServiceListener</code> object to the context
+ * bundle's list of listeners.
+ *
+ * <p>
+ * This method is the same as calling
+ * <code>BundleContext.addServiceListener(ServiceListener listener,
+ * String filter)</code>
+ * with <code>filter</code> set to <code>null</code>.
+ *
+ * @param listener The <code>ServiceListener</code> object to be added.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @see #addServiceListener(ServiceListener, String)
+ */
+ public abstract void addServiceListener(ServiceListener listener);
+
+ /**
+ * Removes the specified <code>ServiceListener</code> object from the context
+ * bundle's list of listeners.
+ *
+ * <p>
+ * If <code>listener</code> is not contained in this context bundle's list of
+ * listeners, this method does nothing.
+ *
+ * @param listener The <code>ServiceListener</code> to be removed.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract void removeServiceListener(ServiceListener listener);
+
+ /**
+ * Adds the specified <code>BundleListener</code> object to the context
+ * bundle's list of listeners if not already present. BundleListener
+ * objects are notified when a bundle has a lifecycle state change.
+ *
+ * <p>
+ * If the context bundle's list of listeners already contains a listener
+ * <code>l</code> such that <code>(l==listener)</code>, this method does
+ * nothing.
+ *
+ * @param listener The <code>BundleListener</code> to be added.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @see BundleEvent
+ * @see BundleListener
+ */
+ public abstract void addBundleListener(BundleListener listener);
+
+ /**
+ * Removes the specified <code>BundleListener</code> object from the context
+ * bundle's list of listeners.
+ *
+ * <p>
+ * If <code>listener</code> is not contained in the context bundle's list of
+ * listeners, this method does nothing.
+ *
+ * @param listener The <code>BundleListener</code> object to be removed.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract void removeBundleListener(BundleListener listener);
+
+ /**
+ * Adds the specified <code>FrameworkListener</code> object to the context
+ * bundle's list of listeners if not already present.
+ * FrameworkListeners are notified of general Framework events.
+ *
+ * <p>
+ * If the context bundle's list of listeners already contains a listener
+ * <code>l</code> such that <code>(l==listener)</code>, this method does
+ * nothing.
+ *
+ * @param listener The <code>FrameworkListener</code> object to be added.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @see FrameworkEvent
+ * @see FrameworkListener
+ */
+ public abstract void addFrameworkListener(FrameworkListener listener);
+
+ /**
+ * Removes the specified <code>FrameworkListener</code> object from the
+ * context bundle's list of listeners.
+ *
+ * <p>
+ * If <code>listener</code> is not contained in the context bundle's list of
+ * listeners, this method does nothing.
+ *
+ * @param listener The <code>FrameworkListener</code> object to be removed.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract void removeFrameworkListener(FrameworkListener listener);
+
+ /**
+ * Registers the specified service object with the specified properties
+ * under the specified class names into the Framework. A
+ * <code>ServiceRegistration</code> object is returned. The
+ * <code>ServiceRegistration</code> object is for the private use of the
+ * bundle registering the service and should not be shared with other
+ * bundles. The registering bundle is defined to be the context bundle.
+ * Other bundles can locate the service by using either the
+ * {@link #getServiceReferences} or {@link #getServiceReference} method.
+ *
+ * <p>
+ * A bundle can register a service object that implements the
+ * {@link ServiceFactory} interface to have more flexibility in providing
+ * service objects to other bundles.
+ *
+ * <p>
+ * The following steps are required to register a service:
+ * <ol>
+ * <li>If <code>service</code> is not a <code>ServiceFactory</code>, an
+ * <code>IllegalArgumentException</code> is thrown if <code>service</code> is
+ * not an <code>instanceof</code> all the classes named.
+ * <li>The Framework adds these service properties to the specified
+ * <code>Dictionary</code> (which may be <code>null</code>): a property named
+ * {@link Constants#SERVICE_ID} identifying the registration number of the
+ * service and a property named {@link Constants#OBJECTCLASS} containing
+ * all the specified classes. If any of these properties have already been
+ * specified by the registering bundle, their values will be overwritten by
+ * the Framework.
+ * <li>The service is added to the Framework service registry and may now
+ * be used by other bundles.
+ * <li>A service event of type {@link ServiceEvent#REGISTERED} is
+ * synchronously sent.
+ * <li>A <code>ServiceRegistration</code> object for this registration is
+ * returned.
+ * </ol>
+ *
+ * @param clazzes The class names under which the service can be located.
+ * The class names in this array will be stored in the service's
+ * properties under the key {@link Constants#OBJECTCLASS}.
+ * @param service The service object or a <code>ServiceFactory</code> object.
+ * @param properties The properties for this service. The keys in the
+ * properties object must all be <code>String</code> objects. See
+ * {@link Constants} for a list of standard service property keys.
+ * Changes should not be made to this object after calling this
+ * method. To update the service's properties the
+ * {@link ServiceRegistration#setProperties} method must be called.
+ * The set of properties may be <code>null</code> if the service has no
+ * properties.
+ *
+ * @return A <code>ServiceRegistration</code> object for use by the bundle
+ * registering the service to update the service's properties or to
+ * unregister the service.
+ *
+ * @exception java.lang.IllegalArgumentException If one of the following is
+ * true:
+ * <ul>
+ * <li><code>service</code> is <code>null</code>.
+ * <li><code>service</code> is not a <code>ServiceFactory</code>
+ * object and is not an instance of all the named classes in
+ * <code>clazzes</code>.
+ * <li><code>properties</code> contains case variants of the same
+ * key name.
+ * </ul>
+ *
+ * @exception java.lang.SecurityException If the caller does not have the
+ * <code>ServicePermission</code> to register the service for all
+ * the named classes and the Java Runtime Environment supports
+ * permissions.
+ *
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @see ServiceRegistration
+ * @see ServiceFactory
+ */
+ public abstract ServiceRegistration registerService(String[] clazzes,
+ Object service, Dictionary properties);
+
+ /**
+ * Registers the specified service object with the specified properties
+ * under the specified class name with the Framework.
+ *
+ * <p>
+ * This method is otherwise identical to
+ * {@link #registerService(java.lang.String[], java.lang.Object,
+ * java.util.Dictionary)} and is provided as a convenience when
+ * <code>service</code> will only be registered under a single class name.
+ * Note that even in this case the value of the service's
+ * {@link Constants#OBJECTCLASS} property will be an array of strings,
+ * rather than just a single string.
+ *
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ * @see #registerService(java.lang.String[], java.lang.Object,
+ * java.util.Dictionary)
+ */
+ public abstract ServiceRegistration registerService(String clazz,
+ Object service, Dictionary properties);
+
+ /**
+ * Returns an array of <code>ServiceReference</code> objects. The returned
+ * array of <code>ServiceReference</code> objects contains services that
+ * were registered under the specified class, match the specified filter
+ * criteria, and the packages for the class names under which the services
+ * were registered match the context bundle's packages as defined in
+ * {@link ServiceReference#isAssignableTo(Bundle, String)}.
+ *
+ * <p>
+ * The list is valid at the time of the call to this method, however since the
+ * Framework is a very dynamic environment, services can be modified or
+ * unregistered at anytime.
+ *
+ * <p>
+ * <code>filter</code> is used to select the registered service whose
+ * properties objects contain keys and values which satisfy the filter. See
+ * {@link Filter} for a description of the filter string syntax.
+ *
+ * <p>
+ * If <code>filter</code> is <code>null</code>, all registered services are
+ * considered to match the filter.
+ * If <code>filter</code> cannot be parsed, an {@link InvalidSyntaxException}
+ * will be thrown with a human readable message where the filter became
+ * unparsable.
+ *
+ * <p>
+ * The following steps are required to select a set of
+ * <code>ServiceReference</code> objects:
+ * <ol>
+ * <li>If the filter string is not <code>null</code>, the filter string is
+ * parsed and the set <code>ServiceReference</code> objects of registered
+ * services that satisfy the filter is produced. If the filter string is
+ * <code>null</code>, then all registered
+ * services are considered to satisfy the filter.
+ * <li>If the Java Runtime Environment supports permissions, the
+ * set of <code>ServiceReference</code> objects produced by the
+ * previous step is reduced by checking that the caller has
+ * the <code>ServicePermission</code> to get at least one
+ * of the class names under which the service was registered. If the caller
+ * does not have the correct permission for a particular
+ * <code>ServiceReference</code> object, then it is removed from the set.
+ * <li>If <code>clazz</code> is not <code>null</code>, the set is further
+ * reduced to those services that are an <code>instanceof</code> and were
+ * registered under the specified class. The complete list of classes of
+ * which a service is an instance and which were specified when the service
+ * was registered is available from the service's
+ * {@link Constants#OBJECTCLASS} property.
+ * <li>The set is reduced one final time by cycling through each
+ * <code>ServiceReference</code> object and calling
+ * {@link ServiceReference#isAssignableTo(Bundle, String)} with the
+ * context bundle and each class name under which the
+ * <code>ServiceReference</code> object was registered. For any
+ * given <code>ServiceReference</code> object, if any call to
+ * {@link ServiceReference#isAssignableTo(Bundle, String)} returns
+ * <code>false</code>, then it is removed from the set of
+ * <code>ServiceReference</code> objects.
+ * <li>An array of the remaining <code>ServiceReference</code> objects
+ * is returned.
+ * </ol>
+ *
+ * @param clazz The class name with which the service was registered or
+ * <code>null</code> for all services.
+ * @param filter The filter criteria.
+ * @return An array of <code>ServiceReference</code> objects or <code>null</code>
+ * if no services are registered which satisfy the search.
+ * @exception InvalidSyntaxException If <code>filter</code> contains an
+ * invalid filter string that cannot be parsed.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract ServiceReference[] getServiceReferences(String clazz,
+ String filter) throws InvalidSyntaxException;
+
+ /**
+ * Returns an array of <code>ServiceReference</code> objects. The returned
+ * array of <code>ServiceReference</code> objects contains services that
+ * were registered under the specified class and match the
+ * specified filter criteria.
+ *
+ * <p>
+ * The list is valid at the time of the call to this method, however since the
+ * Framework is a very dynamic environment, services can be modified or
+ * unregistered at anytime.
+ *
+ * <p>
+ * <code>filter</code> is used to select the registered service whose
+ * properties objects contain keys and values which satisfy the filter. See
+ * {@link Filter} for a description of the filter string syntax.
+ *
+ * <p>
+ * If <code>filter</code> is <code>null</code>, all registered services are
+ * considered to match the filter.
+ * If <code>filter</code> cannot be parsed, an {@link InvalidSyntaxException}
+ * will be thrown with a human readable message where the filter became
+ * unparsable.
+ *
+ * <p>
+ * The following steps are required to select a set of
+ * <code>ServiceReference</code> objects:
+ * <ol>
+ * <li>If the filter string is not <code>null</code>, the filter string is
+ * parsed and the set <code>ServiceReference</code> objects of registered
+ * services that satisfy the filter is produced. If the filter string is
+ * <code>null</code>, then all registered
+ * services are considered to satisfy the filter.
+ * <li>If the Java Runtime Environment supports permissions, the
+ * set of <code>ServiceReference</code> objects produced by the
+ * previous step is reduced by checking that the caller has
+ * the <code>ServicePermission</code> to get at least one
+ * of the class names under which the service was registered. If the caller
+ * does not have the correct permission for a particular
+ * <code>ServiceReference</code> object, then it is removed from the set.
+ * <li>If <code>clazz</code> is not <code>null</code>, the set is further
+ * reduced to those services that are an <code>instanceof</code> and were
+ * registered under the specified class. The complete list of classes of
+ * which a service is an instance and which were specified when the service
+ * was registered is available from the service's
+ * {@link Constants#OBJECTCLASS} property.
+ * <li>An array of the remaining <code>ServiceReference</code> objects
+ * is returned.
+ * </ol>
+ *
+ * @param clazz The class name with which the service was registered or
+ * <code>null</code> for all services.
+ * @param filter The filter criteria.
+ * @return An array of <code>ServiceReference</code> objects or <code>null</code>
+ * if no services are registered which satisfy the search.
+ * @exception InvalidSyntaxException If <code>filter</code> contains an
+ * invalid filter string that cannot be parsed.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract ServiceReference[] getAllServiceReferences(String clazz,
+ String filter) throws InvalidSyntaxException;
+
+ /**
+ * Returns a <code>ServiceReference</code> object for a service that
+ * implements and was registered under the specified class.
+ *
+ * <p>
+ * This <code>ServiceReference</code> object is valid at the time of the call
+ * to this method, however as the Framework is a very dynamic environment,
+ * services can be modified or unregistered at anytime.
+ *
+ * <p>
+ * This method is the same as calling
+ * {@link BundleContext#getServiceReferences(String, String)} with a
+ * <code>null</code> filter string. It is provided as a convenience for when
+ * the caller is interested in any service that implements the specified
+ * class.
+ * <p>
+ * If multiple such services exist, the service with the highest ranking (as
+ * specified in its {@link Constants#SERVICE_RANKING} property) is returned.
+ * <p>
+ * If there is a tie in ranking, the service with the lowest service ID (as
+ * specified in its {@link Constants#SERVICE_ID} property); that is, the
+ * service that was registered first is returned.
+ *
+ * @param clazz The class name with which the service was registered.
+ * @return A <code>ServiceReference</code> object, or <code>null</code> if no
+ * services are registered which implement the named class.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ * @see #getServiceReferences(String, String)
+ */
+ public abstract ServiceReference getServiceReference(String clazz);
+
+ /**
+ * Returns the specified service object for a service.
+ * <p>
+ * A bundle's use of a service is tracked by the bundle's use count of that
+ * service. Each time a service's service object is returned by
+ * {@link #getService(ServiceReference)} the context bundle's use count for
+ * that service is incremented by one. Each time the service is released by
+ * {@link #ungetService(ServiceReference)} the context bundle's use count
+ * for that service is decremented by one.
+ * <p>
+ * When a bundle's use count for a service drops to zero, the bundle should
+ * no longer use that service.
+ *
+ * <p>
+ * This method will always return <code>null</code> when the service
+ * associated with this <code>reference</code> has been unregistered.
+ *
+ * <p>
+ * The following steps are required to get the service object:
+ * <ol>
+ * <li>If the service has been unregistered, <code>null</code> is returned.
+ * <li>The context bundle's use count for this service is incremented by
+ * one.
+ * <li>If the context bundle's use count for the service is currently one
+ * and the service was registered with an object implementing the
+ * <code>ServiceFactory</code> interface, the
+ * {@link ServiceFactory#getService(Bundle, ServiceRegistration)} method
+ * is called to create a service object for the context bundle. This service
+ * object is cached by the Framework. While the context bundle's use count
+ * for the service is greater than zero, subsequent calls to get the
+ * services's service object for the context bundle will return the cached
+ * service object.
+ * <br>
+ * If the service object returned by the <code>ServiceFactory</code> object is
+ * not an <code>instanceof</code> all the classes named when the service was
+ * registered or the <code>ServiceFactory</code> object throws an exception,
+ * <code>null</code> is returned and a Framework event of type
+ * {@link FrameworkEvent#ERROR} is broadcast.
+ * <li>The service object for the service is returned.
+ * </ol>
+ *
+ * @param reference A reference to the service.
+ * @return A service object for the service associated with
+ * <code>reference</code> or <code>null</code> if the service is not
+ * registered or does not implement the classes under which it was
+ * registered in the case of a <code>ServiceFactory</code>.
+ * @exception java.lang.SecurityException If the caller does not have the
+ * <code>ServicePermission</code> to get the service using at least
+ * one of the named classes the service was registered under and
+ * the Java Runtime Environment supports permissions.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ * @see #ungetService(ServiceReference)
+ * @see ServiceFactory
+ */
+ public abstract Object getService(ServiceReference reference);
+
+ /**
+ * Releases the service object referenced by the specified
+ * <code>ServiceReference</code> object. If the context bundle's use count for
+ * the service is zero, this method returns <code>false</code>. Otherwise,
+ * the context bundle's use count for the service is decremented by one.
+ *
+ * <p>
+ * The service's service object should no longer be used and all references
+ * to it should be destroyed when a bundle's use count for the service drops
+ * to zero.
+ *
+ * <p>
+ * The following steps are required to unget the service object:
+ * <ol>
+ * <li>If the context bundle's use count for the service is zero or the
+ * service has been unregistered, <code>false</code> is returned.
+ * <li>The context bundle's use count for this service is decremented by
+ * one.
+ * <li>If the context bundle's use count for the service is currently zero
+ * and the service was registered with a <code>ServiceFactory</code> object,
+ * the {@link ServiceFactory#ungetService(Bundle, ServiceRegistration, Object)}
+ * method is called to release the service object for the context bundle.
+ * <li><code>true</code> is returned.
+ * </ol>
+ *
+ * @param reference A reference to the service to be released.
+ * @return <code>false</code> if the context bundle's use count for the
+ * service is zero or if the service has been unregistered;
+ * <code>true</code> otherwise.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ * @see #getService
+ * @see ServiceFactory
+ */
+ public abstract boolean ungetService(ServiceReference reference);
+
+ /**
+ * Creates a <code>File</code> object for a file in the persistent storage
+ * area provided for the bundle by the Framework. This method will return
+ * <code>null</code> if the platform does not have file system support.
+ *
+ * <p>
+ * A <code>File</code> object for the base directory of the persistent storage
+ * area provided for the context bundle by the Framework can be obtained by
+ * calling this method with an empty string as <code>filename</code>.
+ *
+ * <p>
+ * If the Java Runtime Environment supports permissions, the Framework will
+ * ensure that the bundle has the <code>java.io.FilePermission</code> with
+ * actions <code>read</code>,<code>write</code>,<code>delete</code> for all
+ * files (recursively) in the persistent storage area provided for the
+ * context bundle.
+ *
+ * @param filename A relative name to the file to be accessed.
+ * @return A <code>File</code> object that represents the requested file or
+ * <code>null</code> if the platform does not have file system
+ * support.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ */
+ public abstract File getDataFile(String filename);
+
+ /**
+ * Creates a <code>Filter</code> object. This <code>Filter</code> object may be
+ * used to match a <code>ServiceReference</code> object or a
+ * <code>Dictionary</code> object.
+ *
+ * <p>
+ * If the filter cannot be parsed, an {@link InvalidSyntaxException} will be
+ * thrown with a human readable message where the filter became unparsable.
+ *
+ * @param filter The filter string.
+ * @return A <code>Filter</code> object encapsulating the filter string.
+ * @exception InvalidSyntaxException If <code>filter</code> contains an
+ * invalid filter string that cannot be parsed.
+ * @exception NullPointerException If <code>filter</code> is null.
+ * @exception java.lang.IllegalStateException If this BundleContext is no
+ * longer valid.
+ *
+ * @since 1.1
+ * @see "Framework specification for a description of the filter string syntax."
+ */
+ public abstract Filter createFilter(String filter)
+ throws InvalidSyntaxException;
+}
+
Added: incubator/oscar/trunk/src/org/osgi/framework/BundleEvent.java
URL: http://svn.apache.org/viewcvs/incubator/oscar/trunk/src/org/osgi/framework/BundleEvent.java?rev=233031&view=auto
==============================================================================
--- incubator/oscar/trunk/src/org/osgi/framework/BundleEvent.java (added)
+++ incubator/oscar/trunk/src/org/osgi/framework/BundleEvent.java Tue Aug 16 11:33:34 2005
@@ -0,0 +1,146 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleEvent.java,v 1.10 2005/05/13 20:32:54 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2000, 2005). All Rights Reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this
+ * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
+ */
+
+package org.osgi.framework;
+
+import java.util.EventObject;
+
+/**
+ * A Framework event describing a bundle lifecycle change.
+ * <p>
+ * <code>BundleEvent</code> objects are delivered to <code>BundleListener</code>
+ * objects when a change occurs in a bundle's lifecycle. A type code is used to
+ * identify the event type for future extendability.
+ *
+ * <p>
+ * OSGi Alliance reserves the right to extend the set of types.
+ *
+ * @version $Revision: 1.10 $
+ */
+
+public class BundleEvent extends EventObject {
+ static final long serialVersionUID = 4080640865971756012L;
+ /**
+ * Bundle that had a change occur in its lifecycle.
+ */
+ private Bundle bundle;
+
+ /**
+ * Type of bundle lifecycle change.
+ */
+ private int type;
+
+ /**
+ * The bundle has been installed.
+ * <p>
+ * The value of <code>INSTALLED</code> is 0x00000001.
+ *
+ * @see BundleContext#installBundle(String)
+ */
+ public final static int INSTALLED = 0x00000001;
+
+ /**
+ * The bundle has been started.
+ * <p>
+ * The value of <code>STARTED</code> is 0x00000002.
+ *
+ * @see Bundle#start
+ */
+ public final static int STARTED = 0x00000002;
+
+ /**
+ * The bundle has been stopped.
+ * <p>
+ * The value of <code>STOPPED</code> is 0x00000004.
+ *
+ * @see Bundle#stop
+ */
+ public final static int STOPPED = 0x00000004;
+
+ /**
+ * The bundle has been updated.
+ * <p>
+ * The value of <code>UPDATED</code> is 0x00000008.
+ *
+ * @see Bundle#update()
+ */
+ public final static int UPDATED = 0x00000008;
+
+ /**
+ * The bundle has been uninstalled.
+ * <p>
+ * The value of <code>UNINSTALLED</code> is 0x00000010.
+ *
+ * @see Bundle#uninstall
+ */
+ public final static int UNINSTALLED = 0x00000010;
+
+ /**
+ * The bundle has been resolved.
+ * <p>
+ * The value of <code>RESOLVED</code> is 0x00000020.
+ *
+ * @see Bundle#RESOLVED
+ * @since 1.3
+ */
+ public final static int RESOLVED = 0x00000020;
+
+ /**
+ * The bundle has been unresolved.
+ * <p>
+ * The value of <code>UNRESOLVED</code> is 0x00000040.
+ *
+ * @see Bundle#INSTALLED
+ * @since 1.3
+ */
+ public final static int UNRESOLVED = 0x00000040;
+
+ /**
+ * Creates a bundle event of the specified type.
+ *
+ * @param type The event type.
+ * @param bundle The bundle which had a lifecycle change.
+ */
+
+ public BundleEvent(int type, Bundle bundle) {
+ super(bundle);
+ this.bundle = bundle;
+ this.type = type;
+ }
+
+ /**
+ * Returns the bundle which had a lifecycle change. This bundle is the
+ * source of the event.
+ *
+ * @return The bundle that had a change occur in its lifecycle.
+ */
+ public Bundle getBundle() {
+ return bundle;
+ }
+
+ /**
+ * Returns the type of lifecyle event. The type values are:
+ * <ul>
+ * <li>{@link #INSTALLED}
+ * <li>{@link #STARTED}
+ * <li>{@link #STOPPED}
+ * <li>{@link #UPDATED}
+ * <li>{@link #UNINSTALLED}
+ * <li>{@link #RESOLVED}
+ * <li>{@link #UNRESOLVED}
+ * </ul>
+ *
+ * @return The type of lifecycle event.
+ */
+
+ public int getType() {
+ return type;
+ }
+}
\ No newline at end of file
Added: incubator/oscar/trunk/src/org/osgi/framework/BundleException.java
URL: http://svn.apache.org/viewcvs/incubator/oscar/trunk/src/org/osgi/framework/BundleException.java?rev=233031&view=auto
==============================================================================
--- incubator/oscar/trunk/src/org/osgi/framework/BundleException.java (added)
+++ incubator/oscar/trunk/src/org/osgi/framework/BundleException.java Tue Aug 16 11:33:34 2005
@@ -0,0 +1,95 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleException.java,v 1.10 2005/05/13 20:32:55 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2000, 2005). All Rights Reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this
+ * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
+ */
+
+package org.osgi.framework;
+
+/**
+ * A Framework exception used to indicate that a bundle lifecycle problem
+ * occurred.
+ *
+ * <p>
+ * <code>BundleException</code> object is created by the Framework to denote an
+ * exception condition in the lifecycle of a bundle. <code>BundleException</code>s
+ * should not be created by bundle developers.
+ *
+ * <p>
+ * This exception is updated to conform to the general purpose exception
+ * chaining mechanism.
+ *
+ * @version $Revision: 1.10 $
+ */
+
+public class BundleException extends Exception {
+ static final long serialVersionUID = 3571095144220455665L;
+ /**
+ * Nested exception.
+ */
+ private Throwable cause;
+
+ /**
+ * Creates a <code>BundleException</code> that wraps another exception.
+ *
+ * @param msg The associated message.
+ * @param cause The cause of this exception.
+ */
+ public BundleException(String msg, Throwable cause) {
+ super(msg);
+ this.cause = cause;
+ }
+
+ /**
+ * Creates a <code>BundleException</code> object with the specified message.
+ *
+ * @param msg The message.
+ */
+ public BundleException(String msg) {
+ super(msg);
+ this.cause = null;
+ }
+
+ /**
+ * Returns any nested exceptions included in this exception.
+ *
+ * <p>
+ * This method predates the general purpose exception chaining mechanism.
+ * The {@link #getCause()} method is now the preferred means of obtaining
+ * this information.
+ *
+ * @return The nested exception; <code>null</code> if there is no nested
+ * exception.
+ */
+ public Throwable getNestedException() {
+ return cause;
+ }
+
+ /**
+ * Returns the cause of this exception or <code>null</code> if no cause was
+ * specified when this exception was created.
+ *
+ * @return The cause of this exception or <code>null</code> if no cause was
+ * specified.
+ * @since 1.3
+ */
+ public Throwable getCause() {
+ return cause;
+ }
+
+ /**
+ * The cause of this exception can only be set when constructed.
+ *
+ * @throws java.lang.IllegalStateException This method will always throw an
+ * <code>IllegalStateException</code> since the cause of this
+ * exception can only be set when constructed.
+ * @since 1.3
+ */
+ public Throwable initCause(Throwable cause) {
+ throw new IllegalStateException();
+ }
+}
\ No newline at end of file
Added: incubator/oscar/trunk/src/org/osgi/framework/BundleListener.java
URL: http://svn.apache.org/viewcvs/incubator/oscar/trunk/src/org/osgi/framework/BundleListener.java?rev=233031&view=auto
==============================================================================
--- incubator/oscar/trunk/src/org/osgi/framework/BundleListener.java (added)
+++ incubator/oscar/trunk/src/org/osgi/framework/BundleListener.java Tue Aug 16 11:33:34 2005
@@ -0,0 +1,38 @@
+/*
+ * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleListener.java,v 1.7 2005/05/13 20:32:55 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2000, 2005). All Rights Reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this
+ * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
+ */
+
+package org.osgi.framework;
+
+import java.util.EventListener;
+
+/**
+ * A <code>BundleEvent</code> listener.
+ *
+ * <p>
+ * <code>BundleListener</code> is a listener interface that may be implemented by
+ * a bundle developer.
+ * <p>
+ * A <code>BundleListener</code> object is registered with the Framework using the
+ * {@link BundleContext#addBundleListener} method. <code>BundleListener</code>s
+ * are called with a <code>BundleEvent</code> object when a bundle has been
+ * installed, resolved, started, stopped, updated, unresolved, or uninstalled.
+ *
+ * @version $Revision: 1.7 $
+ * @see BundleEvent
+ */
+
+public abstract interface BundleListener extends EventListener {
+ /**
+ * Receives notification that a bundle has had a lifecycle change.
+ *
+ * @param event The <code>BundleEvent</code>.
+ */
+ public abstract void bundleChanged(BundleEvent event);
+}