felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rickh...@apache.org
Subject svn commit: r782737 [2/8] - in /felix/trunk/org.osgi.core/src/main/java/org/osgi: framework/ framework/hooks/ framework/hooks/service/ framework/launch/ service/condpermadmin/ service/packageadmin/ service/permissionadmin/ service/startlevel/ service/url/
Date Mon, 08 Jun 2009 19:31:08 GMT
Modified: felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/Bundle.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/Bundle.java?rev=782737&r1=782736&r2=782737&view=diff
==============================================================================
--- felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/Bundle.java (original)
+++ felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/Bundle.java Mon Jun  8 19:31:06 2009
@@ -1,7 +1,5 @@
 /*
- * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/Bundle.java,v 1.54 2007/02/21 16:49:05 hargrave Exp $
- * 
- * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2009). All Rights Reserved.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,6 +21,7 @@
 import java.net.URL;
 import java.util.Dictionary;
 import java.util.Enumeration;
+import java.util.Map;
 
 /**
  * An installed bundle in the Framework.
@@ -65,7 +64,7 @@
  * Framework that created them.
  * 
  * @ThreadSafe
- * @version $Revision: 1.54 $
+ * @version $Revision: 6906 $
  */
 public interface Bundle {
 	/**
@@ -216,6 +215,23 @@
 	public static final int	STOP_TRANSIENT			= 0x00000001;
 
 	/**
+	 * Request that all certificates used to sign the bundle be returned.
+	 * 
+	 * @since 1.5
+	 * @see #getSignerCertificates(int)
+	 */
+	public final static int	SIGNERS_ALL				= 1;
+
+	/**
+	 * Request that only certificates used to sign the bundle that are trusted
+	 * by the framework be returned.
+	 * 
+	 * @since 1.5
+	 * @see #getSignerCertificates(int)
+	 */
+	public final static int	SIGNERS_TRUSTED			= 2;
+
+	/**
 	 * Returns this bundle's current state.
 	 * 
 	 * <p>
@@ -255,8 +271,8 @@
 	 * <li>If this bundle is in the process of being activated or deactivated
 	 * then this method must wait for activation or deactivation to complete
 	 * 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.
+	 * <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.
@@ -264,17 +280,17 @@
 	 * <li>If the {@link #START_TRANSIENT} option is not set then set this
 	 * bundle's autostart setting to <em>Started with declared activation</em>
 	 * if the {@link #START_ACTIVATION_POLICY} option is set or
-	 * <em>Started with eager activation</em> if not set. When the Framework
-	 * is restarted and this bundle's autostart setting is not <em>Stopped</em>,
+	 * <em>Started with eager activation</em> if not set. When the Framework is
+	 * restarted and this bundle's autostart setting is not <em>Stopped</em>,
 	 * 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. If the Framework cannot resolve this
-	 * bundle, a <code>BundleException</code> is thrown.
+	 * <li>If this bundle's state is not <code>RESOLVED</code>, an attempt is
+	 * made to resolve this bundle. If the Framework cannot resolve this bundle,
+	 * a <code>BundleException</code> is thrown.
 	 * 
 	 * <li>If the {@link #START_ACTIVATION_POLICY} option is set and this
-	 * bundle's declared activation policy is
-	 * {@link Constants#ACTIVATION_LAZY lazy} then:
+	 * bundle's declared activation policy is {@link Constants#ACTIVATION_LAZY
+	 * lazy} then:
 	 * <ul>
 	 * <li>If this bundle's state is <code>STARTING</code> then this method
 	 * returns immediately.
@@ -313,40 +329,40 @@
 	 * 
 	 * <b>Preconditions </b>
 	 * <ul>
-	 * <li><code>getState()</code> in {<code>INSTALLED</code>,
-	 * <code>RESOLVED</code>} or {<code>INSTALLED</code>,
-	 * <code>RESOLVED</code>, <code>STARTING</code>} if this bundle has a
-	 * lazy activation policy.
+	 * <li><code>getState()</code> in &#x007B; <code>INSTALLED</code>,
+	 * <code>RESOLVED</code> &#x007D; or &#x007B; <code>INSTALLED</code>,
+	 * <code>RESOLVED</code>, <code>STARTING</code> &#x007D; if this bundle has
+	 * a lazy activation policy.
 	 * </ul>
 	 * <b>Postconditions, no exceptions thrown </b>
 	 * <ul>
 	 * <li>Bundle autostart setting is modified unless the
 	 * {@link #START_TRANSIENT} option was set.
-	 * <li><code>getState()</code> in {<code>ACTIVE</code>} unless the
-	 * lazy activation policy was used.
+	 * <li><code>getState()</code> in &#x007B; <code>ACTIVE</code> &#x007D;
+	 * unless the lazy activation policy was used.
 	 * <li><code>BundleActivator.start()</code> has been called and did not
 	 * throw an exception unless the lazy activation policy was used.
 	 * </ul>
 	 * <b>Postconditions, when an exception is thrown </b>
 	 * <ul>
-	 * <li>Depending on when the exception occurred, bundle autostart setting
-	 * is modified unless the {@link #START_TRANSIENT} option was set.
-	 * <li><code>getState()</code> not in {<code>STARTING</code>,
-	 * <code>ACTIVE</code>}.
+	 * <li>Depending on when the exception occurred, bundle autostart setting is
+	 * modified unless the {@link #START_TRANSIENT} option was set.
+	 * <li><code>getState()</code> not in &#x007B; <code>STARTING</code>,
+	 * <code>ACTIVE</code> &#x007D;.
 	 * </ul>
 	 * 
 	 * @param options The options for starting this bundle. See
-	 *        {@link #START_TRANSIENT} and {@link #START_ACTIVATION_POLICY}.
-	 *        The Framework must ignore unrecognized options.
+	 *        {@link #START_TRANSIENT} and {@link #START_ACTIVATION_POLICY}. The
+	 *        Framework must ignore unrecognized options.
 	 * @throws 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 or this bundle is a fragment.
-	 * @throws java.lang.IllegalStateException If this bundle has been
-	 *         uninstalled or this bundle tries to change its own state.
-	 * @throws java.lang.SecurityException If the caller does not have the
-	 *         appropriate <code>AdminPermission[this,EXECUTE]</code>, and
-	 *         the Java Runtime Environment supports permissions.
+	 * @throws IllegalStateException If this bundle has been uninstalled or this
+	 *         bundle tries to change its own state.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         <code>AdminPermission[this,EXECUTE]</code>, and the Java Runtime
+	 *         Environment supports permissions.
 	 * @since 1.4
 	 */
 	public void start(int options) throws BundleException;
@@ -355,17 +371,17 @@
 	 * Starts this bundle with no options.
 	 * 
 	 * <p>
-	 * This method calls <code>start(0)</code>.
+	 * This method performs the same function as calling <code>start(0)</code>.
 	 * 
 	 * @throws 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 or this bundle is a fragment.
-	 * @throws java.lang.IllegalStateException If this bundle has been
-	 *         uninstalled or this bundle tries to change its own state.
-	 * @throws java.lang.SecurityException If the caller does not have the
-	 *         appropriate <code>AdminPermission[this,EXECUTE]</code>, and
-	 *         the Java Runtime Environment supports permissions.
+	 * @throws IllegalStateException If this bundle has been uninstalled or this
+	 *         bundle tries to change its own state.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         <code>AdminPermission[this,EXECUTE]</code>, and the Java Runtime
+	 *         Environment supports permissions.
 	 * @see #start(int)
 	 */
 	public void start() throws BundleException;
@@ -382,33 +398,34 @@
 	 * <li>If this bundle is in the process of being activated or deactivated
 	 * then this method must wait for activation or deactivation to complete
 	 * 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.
+	 * <code>BundleException</code> is thrown to indicate this bundle was unable
+	 * to be stopped.
 	 * <li>If the {@link #STOP_TRANSIENT} option is not set then then set this
 	 * bundle's persistent autostart setting to to <em>Stopped</em>. When the
 	 * Framework is restarted and this bundle's autostart setting is
 	 * <em>Stopped</em>, this bundle must not be automatically started.
 	 * 
-	 * <li>If this bundle's state is not <code>ACTIVE</code> then this method
-	 * returns immediately.
+	 * <li>If this bundle's state is not <code>STARTING</code> or
+	 * <code>ACTIVE</code> then this method returns immediately.
 	 * 
 	 * <li>This bundle's state is set to <code>STOPPING</code>.
 	 * 
 	 * <li>A bundle event of type {@link BundleEvent#STOPPING} is fired.
 	 * 
-	 * <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>If this bundle's state was <code>ACTIVE</code> prior to setting the
+	 * state to <code>STOPPING</code>, 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 and 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 this
-	 * bundle was uninstalled while the <code>BundleActivator.stop</code>
-	 * method was running, a <code>BundleException</code> must be thrown.
+	 * 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>.
 	 * 
@@ -417,16 +434,16 @@
 	 * 
 	 * <b>Preconditions </b>
 	 * <ul>
-	 * <li><code>getState()</code> in {<code>ACTIVE</code>}.
+	 * <li><code>getState()</code> in &#x007B; <code>ACTIVE</code> &#x007D;.
 	 * </ul>
 	 * <b>Postconditions, no exceptions thrown </b>
 	 * <ul>
 	 * <li>Bundle autostart setting is modified unless the
 	 * {@link #STOP_TRANSIENT} option was set.
-	 * <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.
+	 * <li><code>getState()</code> not in &#x007B; <code>ACTIVE</code>,
+	 * <code>STOPPING</code> &#x007D;.
+	 * <li><code>BundleActivator.stop</code> has been called and did not throw
+	 * an exception.
 	 * </ul>
 	 * <b>Postconditions, when an exception is thrown </b>
 	 * <ul>
@@ -439,11 +456,11 @@
 	 *        options.
 	 * @throws BundleException If this bundle's <code>BundleActivator</code>
 	 *         threw an exception or this bundle is a fragment.
-	 * @throws java.lang.IllegalStateException If this bundle has been
-	 *         uninstalled or this bundle tries to change its own state.
-	 * @throws java.lang.SecurityException If the caller does not have the
-	 *         appropriate <code>AdminPermission[this,EXECUTE]</code>, and
-	 *         the Java Runtime Environment supports permissions.
+	 * @throws IllegalStateException If this bundle has been uninstalled or this
+	 *         bundle tries to change its own state.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         <code>AdminPermission[this,EXECUTE]</code>, and the Java Runtime
+	 *         Environment supports permissions.
 	 * @since 1.4
 	 */
 	public void stop(int options) throws BundleException;
@@ -452,31 +469,40 @@
 	 * Stops this bundle with no options.
 	 * 
 	 * <p>
-	 * This method calls <code>stop(0)</code>.
+	 * This method performs the same function as calling <code>stop(0)</code>.
 	 * 
 	 * @throws BundleException If this bundle's <code>BundleActivator</code>
 	 *         threw an exception or this bundle is a fragment.
-	 * @throws java.lang.IllegalStateException If this bundle has been
-	 *         uninstalled or this bundle tries to change its own state.
-	 * @throws java.lang.SecurityException If the caller does not have the
-	 *         appropriate <code>AdminPermission[this,EXECUTE]</code>, and
-	 *         the Java Runtime Environment supports permissions.
+	 * @throws IllegalStateException If this bundle has been uninstalled or this
+	 *         bundle tries to change its own state.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         <code>AdminPermission[this,EXECUTE]</code>, and the Java Runtime
+	 *         Environment supports permissions.
 	 * @see #start(int)
 	 */
 	public 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.
+	 * Updates this bundle from an <code>InputStream</code>.
 	 * 
 	 * <p>
-	 * If this bundle 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.
+	 * If the specified <code>InputStream</code> is <code>null</code>, the
+	 * Framework must create the <code>InputStream</code> from which to read the
+	 * updated bundle by interpreting, in an implementation dependent manner,
+	 * this bundle's {@link Constants#BUNDLE_UPDATELOCATION
+	 * Bundle-UpdateLocation} Manifest header, if present, or this bundle's
+	 * original location.
+	 * 
+	 * <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 this bundle has exported any packages that are imported by another
+	 * bundle, 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:
@@ -484,36 +510,20 @@
 	 * <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, the exception is rethrown
-	 * terminating the update.
-	 * 
-	 * <li>The download location of the new version of this bundle is
-	 * determined from either this bundle's
-	 * {@link Constants#BUNDLE_UPDATELOCATION} Manifest header (if available) or
-	 * this 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 this 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
+	 * <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, the exception is rethrown terminating the update.
+	 * 
+	 * <li>The updated version of this bundle is read from the input stream and
+	 * installed. If the Framework is unable to install the updated 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>This bundle's state is set to <code>INSTALLED</code>.
 	 * 
-	 * <li>If the new version of this bundle was successfully installed, a
+	 * <li>If the updated version of this bundle was successfully installed, a
 	 * bundle event of type {@link BundleEvent#UPDATED} is fired.
 	 * 
 	 * <li>If this bundle's state was originally <code>ACTIVE</code>, the
@@ -525,57 +535,59 @@
 	 * 
 	 * <b>Preconditions </b>
 	 * <ul>
-	 * <li><code>getState()</code> not in {<code>UNINSTALLED</code>}.
+	 * <li><code>getState()</code> not in &#x007B; <code>UNINSTALLED</code>
+	 * &#x007D;.
 	 * </ul>
 	 * <b>Postconditions, no exceptions thrown </b>
 	 * <ul>
-	 * <li><code>getState()</code> in {<code>INSTALLED</code>,
-	 * <code>RESOLVED</code>,<code>ACTIVE</code>}.
+	 * <li><code>getState()</code> in &#x007B; <code>INSTALLED</code>,
+	 * <code>RESOLVED</code>, <code>ACTIVE</code> &#x007D;.
 	 * <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><code>getState()</code> in &#x007B; <code>INSTALLED</code>,
+	 * <code>RESOLVED</code>, <code>ACTIVE</code> &#x007D;.
 	 * <li>Original bundle is still used; no update occurred.
 	 * </ul>
 	 * 
-	 * @throws BundleException If the update fails.
-	 * @throws java.lang.IllegalStateException If this bundle has been
-	 *         uninstalled or this bundle tries to change its own state.
-	 * @throws java.lang.SecurityException If the caller does not have the
-	 *         appropriate <code>AdminPermission[this,LIFECYCLE]</code> for
-	 *         both the current bundle and the updated bundle, and the Java
-	 *         Runtime Environment supports permissions.
+	 * @param input The <code>InputStream</code> from which to read the new
+	 *        bundle or <code>null</code> to indicate the Framework must create
+	 *        the input stream from this bundle's
+	 *        {@link Constants#BUNDLE_UPDATELOCATION Bundle-UpdateLocation}
+	 *        Manifest header, if present, or this bundle's original location.
+	 *        The input stream must always be closed when this method completes,
+	 *        even if an exception is thrown.
+	 * @throws BundleException If the input stream cannot be read or the update
+	 *         fails.
+	 * @throws IllegalStateException If this bundle has been uninstalled or this
+	 *         bundle tries to change its own state.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         <code>AdminPermission[this,LIFECYCLE]</code> for both the current
+	 *         bundle and the updated bundle, and the Java Runtime Environment
+	 *         supports permissions.
 	 * @see #stop()
 	 * @see #start()
 	 */
-	public void update() throws BundleException;
+	public void update(InputStream input) throws BundleException;
 
 	/**
-	 * Updates this bundle from an <code>InputStream</code>.
+	 * Updates this bundle.
 	 * 
 	 * <p>
-	 * This method performs all the steps listed in <code>Bundle.update()</code>,
-	 * except the new version of this 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.
-	 * @throws BundleException If the provided stream cannot be read or the
-	 *         update fails.
-	 * @throws java.lang.IllegalStateException If this bundle has been
-	 *         uninstalled or this bundle tries to change its own state.
-	 * @throws java.lang.SecurityException If the caller does not have the
-	 *         appropriate <code>AdminPermission[this,LIFECYCLE]</code> for
-	 *         both the current bundle and the updated bundle, and the Java
-	 *         Runtime Environment supports permissions.
-	 * @see #update()
+	 * This method performs the same function as calling
+	 * {@link #update(InputStream)} with a <code>null</code> InputStream.
+	 * 
+	 * @throws BundleException If the update fails.
+	 * @throws IllegalStateException If this bundle has been uninstalled or this
+	 *         bundle tries to change its own state.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         <code>AdminPermission[this,LIFECYCLE]</code> for both the current
+	 *         bundle and the updated bundle, and the Java Runtime Environment
+	 *         supports permissions.
+	 * @see #update(InputStream)
 	 */
-	public void update(InputStream in) throws BundleException;
+	public void update() throws BundleException;
 
 	/**
 	 * Uninstalls this bundle.
@@ -598,11 +610,11 @@
 	 * <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 fired containing the exception.
+	 * <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
+	 * fired containing the exception.
 	 * 
 	 * <li>This bundle's state is set to <code>UNINSTALLED</code>.
 	 * 
@@ -614,27 +626,30 @@
 	 * 
 	 * <b>Preconditions </b>
 	 * <ul>
-	 * <li><code>getState()</code> not in {<code>UNINSTALLED</code>}.
+	 * <li><code>getState()</code> not in &#x007B; <code>UNINSTALLED</code>
+	 * &#x007D;.
 	 * </ul>
 	 * <b>Postconditions, no exceptions thrown </b>
 	 * <ul>
-	 * <li><code>getState()</code> in {<code>UNINSTALLED</code>}.
+	 * <li><code>getState()</code> in &#x007B; <code>UNINSTALLED</code>
+	 * &#x007D;.
 	 * <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><code>getState()</code> not in &#x007B; <code>UNINSTALLED</code>
+	 * &#x007D;.
 	 * <li>This Bundle has not been uninstalled.
 	 * </ul>
 	 * 
 	 * @throws BundleException If the uninstall failed. This can occur if
 	 *         another thread is attempting to change this bundle's state and
 	 *         does not complete in a timely manner.
-	 * @throws java.lang.IllegalStateException If this bundle has been
-	 *         uninstalled or this bundle tries to change its own state.
-	 * @throws java.lang.SecurityException If the caller does not have the
-	 *         appropriate <code>AdminPermission[this,LIFECYCLE]</code>, and
-	 *         the Java Runtime Environment supports permissions.
+	 * @throws IllegalStateException If this bundle has been uninstalled or this
+	 *         bundle tries to change its own state.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         <code>AdminPermission[this,LIFECYCLE]</code>, and the Java
+	 *         Runtime Environment supports permissions.
 	 * @see #stop()
 	 */
 	public void uninstall() throws BundleException;
@@ -650,7 +665,9 @@
 	 * case-insensitive manner.
 	 * 
 	 * If a Manifest header value starts with &quot;%&quot;, it must be
-	 * localized according to the default locale.
+	 * localized according to the default locale. If no localization is found
+	 * for a header value, the header value without the leading &quot;%&quot; is
+	 * returned.
 	 * 
 	 * <p>
 	 * For example, the following Manifest headers and values are included if
@@ -671,14 +688,12 @@
 	 * 
 	 * @return A <code>Dictionary</code> object containing this bundle's
 	 *         Manifest headers and values.
-	 * 
-	 * @throws java.lang.SecurityException If the caller does not have the
+	 * @throws SecurityException If the caller does not have the
 	 *         appropriate <code>AdminPermission[this,METADATA]</code>, and
 	 *         the Java Runtime Environment supports permissions.
-	 * 
 	 * @see Constants#BUNDLE_LOCALIZATION
 	 */
-	public Dictionary getHeaders();
+	public Dictionary/* <String,String> */getHeaders();
 
 	/**
 	 * Returns this bundle's unique identifier. This bundle is assigned a unique
@@ -718,7 +733,7 @@
 	 * while this bundle is in the <code>UNINSTALLED</code> state.
 	 * 
 	 * @return The string representation of this bundle's location identifier.
-	 * @throws java.lang.SecurityException If the caller does not have the
+	 * @throws SecurityException If the caller does not have the
 	 *         appropriate <code>AdminPermission[this,METADATA]</code>, and
 	 *         the Java Runtime Environment supports permissions.
 	 */
@@ -742,7 +757,7 @@
 	 * 
 	 * @return An array of <code>ServiceReference</code> objects or
 	 *         <code>null</code>.
-	 * @throws java.lang.IllegalStateException If this bundle has been
+	 * @throws IllegalStateException If this bundle has been
 	 *         uninstalled.
 	 * @see ServiceRegistration
 	 * @see ServiceReference
@@ -769,7 +784,7 @@
 	 * 
 	 * @return An array of <code>ServiceReference</code> objects or
 	 *         <code>null</code>.
-	 * @throws java.lang.IllegalStateException If this bundle has been
+	 * @throws IllegalStateException If this bundle has been
 	 *         uninstalled.
 	 * @see ServiceReference
 	 * @see ServicePermission
@@ -795,43 +810,43 @@
 	 * 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>.
-	 * 
-	 * @throws java.lang.IllegalStateException If this bundle has been
+	 * @throws IllegalStateException If this bundle has been
 	 *         uninstalled.
 	 */
 	public boolean hasPermission(Object permission);
 
 	/**
-	 * Find the specified resource from this bundle.
+	 * Find the specified resource from this bundle's class loader.
 	 * 
 	 * This bundle's class loader is called to search for the specified
-	 * resource. If this bundle's state is <code>INSTALLED</code>, this
-	 * method must attempt to resolve this bundle before attempting to get the
+	 * resource. If this bundle's state is <code>INSTALLED</code>, this method
+	 * must attempt to resolve this bundle before attempting to get the
 	 * specified resource. If this bundle cannot be resolved, then only this
 	 * bundle must be searched for the specified resource. Imported packages
 	 * cannot be searched when this bundle has not been resolved. If this bundle
 	 * is a fragment bundle then <code>null</code> is returned.
+	 * <p>
+	 * Note: Jar and zip files are not required to include directory entries.
+	 * URLs to directory entries will not be returned if the bundle contents do
+	 * not contain directory entries.
 	 * 
 	 * @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[this,RESOURCE]</code>, and the Java
-	 *         Runtime Environment supports permissions.
-	 * 
-	 * @since 1.1
-	 * @throws java.lang.IllegalStateException If this bundle has been
-	 *         uninstalled.
+	 *        <code>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[this,RESOURCE]</code>, and the Java Runtime
+	 *         Environment supports permissions.
+	 * @throws IllegalStateException If this bundle has been uninstalled.
 	 * @see #getEntry
 	 * @see #findEntries
+	 * @since 1.1
 	 */
 	public URL getResource(String name);
 
@@ -851,13 +866,13 @@
 	 * default locale. Localizations are searched for in the following order:
 	 * 
 	 * <pre>
-	 *   bn + "_" + Ls + "_" + Cs + "_" + Vs
-     *   bn + "_" + Ls + "_" + Cs
-     *   bn + "_" + Ls
-     *   bn + "_" + Ld + "_" + Cd + "_" + Vd
-     *   bn + "_" + Ld + "_" + Cd
-     *   bn + "_" + Ld
-	 *     bn
+	 *   bn + &quot;_&quot; + Ls + &quot;_&quot; + Cs + &quot;_&quot; + Vs
+	 *   bn + &quot;_&quot; + Ls + &quot;_&quot; + Cs
+	 *   bn + &quot;_&quot; + Ls
+	 *   bn + &quot;_&quot; + Ld + &quot;_&quot; + Cd + &quot;_&quot; + Vd
+	 *   bn + &quot;_&quot; + Ld + &quot;_&quot; + Cd
+	 *   bn + &quot;_&quot; + Ld
+	 *   bn
 	 * </pre>
 	 * 
 	 * Where <code>bn</code> is this bundle's localization basename,
@@ -870,7 +885,9 @@
 	 * values must be localized using the default locale. If the empty string
 	 * (&quot;&quot;) is specified as the locale string, the header values must
 	 * not be localized and the raw (unlocalized) header values, including any
-	 * leading &quot;%&quot;, must be returned.
+	 * leading &quot;%&quot;, must be returned. If no localization is found for
+	 * a header value, the header value without the leading &quot;%&quot; is
+	 * returned.
 	 * 
 	 * <p>
 	 * This method must continue to return Manifest header information while
@@ -886,35 +903,34 @@
 	 *        leading &quot;%&quot;.
 	 * @return A <code>Dictionary</code> object containing this bundle's
 	 *         Manifest headers and values.
-	 * 
-	 * @throws java.lang.SecurityException If the caller does not have the
+	 * @throws SecurityException If the caller does not have the
 	 *         appropriate <code>AdminPermission[this,METADATA]</code>, and
 	 *         the Java Runtime Environment supports permissions.
-	 * 
 	 * @see #getHeaders()
 	 * @see Constants#BUNDLE_LOCALIZATION
 	 * @since 1.3
 	 */
-	public Dictionary getHeaders(String locale);
+	public Dictionary/* <String,String> */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 this bundle does not have a
-	 * specified symbolic name then <code>null</code> is returned.
+	 * <code>Bundle-SymbolicName</code> manifest header. The bundle symbolic
+	 * name together with a version must identify a unique bundle. The bundle
+	 * symbolic name should be based on the reverse domain name naming
+	 * convention like that used for java packages.
 	 * 
 	 * <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.
+	 * @return The symbolic name of this bundle or <code>null</code> if this
+	 *         bundle does not have a symbolic name.
 	 * @since 1.3
 	 */
 	public String getSymbolicName();
 
 	/**
-	 * Loads the specified class using this bundle's classloader.
+	 * Loads the specified class using this bundle's class loader.
 	 * 
 	 * <p>
 	 * If this bundle is a fragment bundle then this method must throw a
@@ -937,47 +953,49 @@
 	 * 
 	 * @param name The name of the class to load.
 	 * @return The Class object for the requested class.
-	 * @throws java.lang.ClassNotFoundException If no such class can be found or
+	 * @throws 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[this,CLASS]</code>,
 	 *         and the Java Runtime Environment supports permissions.
-	 * @throws java.lang.IllegalStateException If this bundle has been
+	 * @throws IllegalStateException If this bundle has been
 	 *         uninstalled.
 	 * @since 1.3
 	 */
 	public Class loadClass(String name) throws ClassNotFoundException;
 
 	/**
-	 * Find the specified resources from this bundle.
+	 * Find the specified resources from this bundle's class loader.
 	 * 
 	 * This bundle's class loader is called to search for the specified
-	 * resources. If this bundle's state is <code>INSTALLED</code>, this
-	 * method must attempt to resolve this bundle before attempting to get the
+	 * resources. If this bundle's state is <code>INSTALLED</code>, this method
+	 * must attempt to resolve this bundle before attempting to get the
 	 * specified resources. If this bundle cannot be resolved, then only this
 	 * bundle must be searched for the specified resources. 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.
+	 * <p>
+	 * Note: Jar and zip files are not required to include directory entries.
+	 * URLs to directory entries will not be returned if the bundle contents do
+	 * not contain directory entries.
 	 * 
 	 * @param name The name of the resource. See
-	 *        <code>java.lang.ClassLoader.getResources</code> for a
-	 *        description of the format of a resource name.
+	 *        <code>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[this,RESOURCE]</code>, and
-	 *         the Java Runtime Environment supports permissions.
-	 * 
+	 *         appropriate <code>AdminPermission[this,RESOURCE]</code>, and the
+	 *         Java Runtime Environment supports permissions.
+	 * @throws IllegalStateException If this bundle has been uninstalled.
+	 * @throws IOException If there is an I/O error.
 	 * @since 1.3
-	 * @throws 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;
+	public Enumeration/* <URL> */getResources(String name) throws IOException;
 
 	/**
 	 * Returns an Enumeration of all the paths (<code>String</code> objects)
 	 * to entries within this bundle whose longest sub-path matches the
-	 * specified path. This bundle's classloader is not used to search for
+	 * specified path. This bundle's class loader is not used to search for
 	 * entries. Only the contents of this bundle are searched.
 	 * <p>
 	 * The specified path is always relative to the root of this bundle and may
@@ -987,6 +1005,10 @@
 	 * Returned paths indicating subdirectory paths end with a &quot;/&quot;.
 	 * The returned paths are all relative to the root of this bundle and must
 	 * not begin with &quot;/&quot;.
+	 * <p>
+	 * Note: Jar and zip files are not required to include directory entries.
+	 * Paths to directory entries will not be returned if the bundle contents do
+	 * not contain directory entries.
 	 * 
 	 * @param path The path name for which to return entry paths.
 	 * @return An Enumeration of the entry paths (<code>String</code>
@@ -994,28 +1016,31 @@
 	 *         the caller does not have the appropriate
 	 *         <code>AdminPermission[this,RESOURCE]</code> and the Java
 	 *         Runtime Environment supports permissions.
-	 * @throws java.lang.IllegalStateException If this bundle has been
+	 * @throws IllegalStateException If this bundle has been
 	 *         uninstalled.
 	 * @since 1.3
 	 */
-	public Enumeration getEntryPaths(String path);
+	public Enumeration/* <String> */getEntryPaths(String path);
 
 	/**
 	 * Returns a URL to the entry at the specified path in this bundle. This
-	 * bundle's classloader is not used to search for the entry. Only the
+	 * bundle's class loader is not used to search for the entry. Only the
 	 * contents of this bundle are searched for the entry.
 	 * <p>
 	 * The specified path is always relative to the root of this bundle and may
 	 * begin with &quot;/&quot;. A path value of &quot;/&quot; indicates the
 	 * root of this bundle.
+	 * <p>
+	 * Note: Jar and zip files are not required to include directory entries.
+	 * URLs to directory entries will not be returned if the bundle contents do
+	 * not contain directory entries.
 	 * 
 	 * @param path The path name of the entry.
 	 * @return A URL to the entry, or <code>null</code> if no entry could be
 	 *         found or if the caller does not have the appropriate
 	 *         <code>AdminPermission[this,RESOURCE]</code> and the Java
 	 *         Runtime Environment supports permissions.
-	 * 
-	 * @throws java.lang.IllegalStateException If this bundle has been
+	 * @throws IllegalStateException If this bundle has been
 	 *         uninstalled.
 	 * @since 1.3
 	 */
@@ -1036,7 +1061,7 @@
 
 	/**
 	 * Returns entries in this bundle and its attached fragments. This bundle's
-	 * classloader is not used to search for entries. Only the contents of this
+	 * class loader is not used to search for entries. Only the contents of this
 	 * bundle and its attached fragments are searched for the specified entries.
 	 * 
 	 * If this bundle's state is <code>INSTALLED</code>, this method must
@@ -1064,36 +1089,43 @@
 	 * Enumeration e = b.findEntries(&quot;OSGI-INF&quot;, &quot;*.xml&quot;, true);
 	 * 
 	 * // Find a specific localization file
-	 * Enumeration e = b.findEntries(&quot;OSGI-INF/l10n&quot;, 
-	 *                               &quot;bundle_nl_DU.properties&quot;, 
-	 *                               false);
+	 * Enumeration e = b
+	 * 		.findEntries(&quot;OSGI-INF/l10n&quot;, &quot;bundle_nl_DU.properties&quot;, false);
 	 * if (e.hasMoreElements())
 	 * 	return (URL) e.nextElement();
 	 * </pre>
 	 * 
+	 * <p>
+	 * Note: Jar and zip files are not required to include directory entries.
+	 * URLs to directory entries will not be returned if the bundle contents do
+	 * not contain directory entries.
+	 * 
 	 * @param path The path name in which to look. The path is always relative
 	 *        to the root of this bundle and may begin with &quot;/&quot;. A
 	 *        path value of &quot;/&quot; indicates the root of this bundle.
 	 * @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 (&quot;*&quot;). If null is specified, this is
-	 *        equivalent to &quot;*&quot; and matches all files.
+	 *        element of the entry path. If the entry is a directory then the
+	 *        trailing &quot;/&quot; is not used for pattern matching. Substring
+	 *        matching is supported, as specified in the Filter specification,
+	 *        using the wildcard character (&quot;*&quot;). If null is
+	 *        specified, this is equivalent to &quot;*&quot; and matches all
+	 *        files.
 	 * @param recurse If <code>true</code>, recurse into subdirectories.
 	 *        Otherwise only return entries from the specified path.
 	 * @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[this,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
+	 *         <code>null</code> if an entry could not be found or if the caller
+	 *         does not have the appropriate
+	 *         <code>AdminPermission[this,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.
+	 * @throws IllegalStateException If this bundle has been uninstalled.
 	 * @since 1.3
 	 */
-	public Enumeration findEntries(String path, String filePattern,
+	public Enumeration/* <URL> */findEntries(String path, String filePattern,
 			boolean recurse);
 
 	/**
@@ -1111,10 +1143,52 @@
 	 * @return A <code>BundleContext</code> for this bundle or
 	 *         <code>null</code> if this bundle has no valid
 	 *         <code>BundleContext</code>.
-	 * @throws java.lang.SecurityException If the caller does not have the
+	 * @throws SecurityException If the caller does not have the
 	 *         appropriate <code>AdminPermission[this,CONTEXT]</code>, and
 	 *         the Java Runtime Environment supports permissions.
 	 * @since 1.4
 	 */
 	public BundleContext getBundleContext();
+
+	/**
+	 * Return the certificates for the signers of this bundle and the
+	 * certificate chains for those signers.
+	 * 
+	 * @param signersType If {@link #SIGNERS_ALL} is specified, then information
+	 *        on all signers of this bundle is returned. If
+	 *        {@link #SIGNERS_TRUSTED} is specified, then only information on
+	 *        the signers of this bundle trusted by the framework is returned.
+	 * @return The <code>X509Certificate</code>s for the signers of this bundle
+	 *         and the <code>X509Certificate</code> chains for those signers.
+	 *         The keys of the <code>Map</code> are the
+	 *         <code>X509Certificate</code>s of the signers of this bundle. The
+	 *         value for a key is a <code>List</code> containing the
+	 *         <code>X509Certificate</code> chain for the signer. The first item
+	 *         in the <code>List</code> is the signer's
+	 *         <code>X509Certificate</code> which is then followed by the rest
+	 *         of the <code>X509Certificate</code> chain. The returned
+	 *         <code>Map</code> will be empty if there are no signers. The
+	 *         returned <code>Map</code> is the property of the caller who is
+	 *         free to modify it.
+	 * @throws IllegalArgumentException If the specified
+	 *         <code>signersType</code> is not {@link #SIGNERS_ALL} or
+	 *         {@link #SIGNERS_TRUSTED}.
+	 * @since 1.5
+	 */
+	public Map/* <X509Certificate, List<X509Certificate>> */getSignerCertificates(
+			int signersType);
+	
+	/**
+	 * Returns the version of this bundle as specified by its
+	 * <code>Bundle-Version</code> manifest header. If this bundle does not have a
+	 * specified version then {@link Version#emptyVersion} is returned.
+	 * 
+	 * <p>
+	 * This method must continue to return this bundle's version while
+	 * this bundle is in the <code>UNINSTALLED</code> state.
+	 * 
+	 * @return The version of this bundle.
+	 * @since 1.5
+	 */
+	public Version getVersion();
 }

Modified: felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleActivator.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleActivator.java?rev=782737&r1=782736&r2=782737&view=diff
==============================================================================
--- felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleActivator.java (original)
+++ felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleActivator.java Mon Jun  8 19:31:06 2009
@@ -1,7 +1,5 @@
 /*
- * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleActivator.java,v 1.14 2007/02/21 16:49:05 hargrave Exp $
- * 
- * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2009). All Rights Reserved.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -47,7 +45,7 @@
  * object can be created by <code>Class.newInstance()</code>.
  * 
  * @NotThreadSafe
- * @version $Revision: 1.14 $
+ * @version $Revision: 6361 $
  */
 
 public interface BundleActivator {
@@ -61,7 +59,7 @@
 	 * This method must complete and return to its caller in a timely manner.
 	 * 
 	 * @param context The execution context of the bundle being started.
-	 * @throws java.lang.Exception If this method throws an exception, this
+	 * @throws 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.
@@ -80,7 +78,7 @@
 	 * This method must complete and return to its caller in a timely manner.
 	 * 
 	 * @param context The execution context of the bundle being stopped.
-	 * @throws java.lang.Exception If this method throws an exception, the
+	 * @throws 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.

Modified: felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleContext.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleContext.java?rev=782737&r1=782736&r2=782737&view=diff
==============================================================================
--- felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleContext.java (original)
+++ felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleContext.java Mon Jun  8 19:31:06 2009
@@ -1,7 +1,5 @@
 /*
- * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleContext.java,v 1.22 2007/02/21 16:49:05 hargrave Exp $
- * 
- * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2009). All Rights Reserved.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -70,7 +68,7 @@
  * objects and they are only valid within the Framework that created them.
  * 
  * @ThreadSafe
- * @version $Revision: 1.22 $
+ * @version $Revision: 6781 $
  */
 
 public interface BundleContext {
@@ -80,36 +78,15 @@
 	 * 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.
+	 * All bundles must have permission to read properties whose names start
+	 * with &quot;org.osgi.&quot;.
 	 * 
 	 * @param key The name of the requested property.
-	 * @return The value of the requested property, or <code>null</code> if
-	 *         the property is undefined.
-	 * @throws 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.
+	 * @return The value of the requested property, or <code>null</code> if the
+	 *         property is undefined.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         <code>PropertyPermission</code> to read the property, and the
+	 *         Java Runtime Environment supports permissions.
 	 */
 	public String getProperty(String key);
 
@@ -119,53 +96,51 @@
 	 * 
 	 * @return The <code>Bundle</code> object associated with this
 	 *         <code>BundleContext</code>.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
 	 */
 	public 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.
+	 * Installs a bundle from the specified <code>InputStream</code> object.
+	 * 
+	 * <p>
+	 * If the specified <code>InputStream</code> is <code>null</code>, the
+	 * Framework must create the <code>InputStream</code> from which to read the
+	 * bundle by interpreting, in an implementation dependent manner, the
+	 * specified <code>location</code>.
+	 * 
 	 * <p>
-	 * Every installed bundle is uniquely identified by its location string,
-	 * typically in the form of a URL.
+	 * The specified <code>location</code> identifier will be used as the
+	 * identity of the bundle. Every installed bundle is uniquely identified by
+	 * its location identifier which is 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
+	 * <li>If a bundle containing the same location identifier 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 content is read from the input stream. If this fails, a
+	 * {@link BundleException} 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 none of the listed execution 
-	 * environments match an installed execution environment, 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 fired.
 	 * 
-	 * <li>The <code>Bundle</code> object for the newly or previously
-	 * installed bundle is returned.
+	 * <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><code>getState()</code> in &#x007B; <code>INSTALLED</code>,
+	 * <code>RESOLVED</code> &#x007D;.
 	 * <li>Bundle has a unique ID.
 	 * </ul>
 	 * <b>Postconditions, when an exception is thrown </b>
@@ -174,46 +149,40 @@
 	 * </ul>
 	 * 
 	 * @param location The location identifier of the bundle to install.
+	 * @param input The <code>InputStream</code> object from which this bundle
+	 *        will be read or <code>null</code> to indicate the Framework must
+	 *        create the input stream from the specified location identifier.
+	 *        The input stream must always be closed when this method completes,
+	 *        even if an exception is thrown.
 	 * @return The <code>Bundle</code> object of the installed bundle.
-	 * @throws BundleException If the installation failed.
-	 * @throws java.lang.SecurityException If the caller does not have the
-	 *         appropriate <code>AdminPermission[installed bundle,LIFECYCLE]</code>, and the
+	 * @throws BundleException If the input stream cannot be read or the
+	 *         installation failed.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         <code>AdminPermission[installed bundle,LIFECYCLE]</code>, and the
 	 *         Java Runtime Environment supports permissions.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
-	 *         longer valid.
+	 * @throws IllegalStateException If this BundleContext is no longer valid.
 	 */
-	public Bundle installBundle(String location)
+	public Bundle installBundle(String location, InputStream input)
 			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.
+	 * Installs a bundle from the specified <code>location</code> identifier.
 	 * 
 	 * <p>
-	 * This method must always close the <code>InputStream</code> object, even
-	 * if an exception is thrown.
+	 * This method performs the same function as calling
+	 * {@link #installBundle(String,InputStream)} with the specified
+	 * <code>location</code> identifier and a <code>null</code> InputStream.
 	 * 
 	 * @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.
-	 * @throws BundleException If the provided stream cannot be read or the
-	 *         installation failed.
-	 * @throws java.lang.SecurityException If the caller does not have the
-	 *         appropriate <code>AdminPermission[installed bundle,LIFECYCLE]</code>, and the
+	 * @throws BundleException If the installation failed.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         <code>AdminPermission[installed bundle,LIFECYCLE]</code>, and the
 	 *         Java Runtime Environment supports permissions.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
-	 *         longer valid.
-	 * @see #installBundle(java.lang.String)
+	 * @throws IllegalStateException If this BundleContext is no longer valid.
+	 * @see #installBundle(String, InputStream)
 	 */
-	public Bundle installBundle(String location, InputStream input)
-			throws BundleException;
+	public Bundle installBundle(String location) throws BundleException;
 
 	/**
 	 * Returns the bundle with the specified identifier.
@@ -279,18 +248,16 @@
 	 * 
 	 * @param listener The <code>ServiceListener</code> object to be added.
 	 * @param filter The filter criteria.
-	 * 
 	 * @throws InvalidSyntaxException If <code>filter</code> contains an
 	 *         invalid filter string that cannot be parsed.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
-	 * 
 	 * @see ServiceEvent
 	 * @see ServiceListener
 	 * @see ServicePermission
 	 */
-	public void addServiceListener(ServiceListener listener,
-			String filter) throws InvalidSyntaxException;
+	public void addServiceListener(ServiceListener listener, String filter)
+			throws InvalidSyntaxException;
 
 	/**
 	 * Adds the specified <code>ServiceListener</code> object to the context
@@ -303,9 +270,8 @@
 	 * with <code>filter</code> set to <code>null</code>.
 	 * 
 	 * @param listener The <code>ServiceListener</code> object to be added.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
-	 * 
 	 * @see #addServiceListener(ServiceListener, String)
 	 */
 	public void addServiceListener(ServiceListener listener);
@@ -319,7 +285,7 @@
 	 * of listeners, this method does nothing.
 	 * 
 	 * @param listener The <code>ServiceListener</code> to be removed.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
 	 */
 	public void removeServiceListener(ServiceListener listener);
@@ -335,13 +301,13 @@
 	 * does nothing.
 	 * 
 	 * @param listener The <code>BundleListener</code> to be added.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
-	 * @throws java.lang.SecurityException If listener is a
+	 * @throws SecurityException If listener is a
 	 *         <code>SynchronousBundleListener</code> and the caller does not
-	 *         have the appropriate <code>AdminPermission[context bundle,LISTENER]</code>,
-	 *         and the Java Runtime Environment supports permissions.
-	 * 
+	 *         have the appropriate
+	 *         <code>AdminPermission[context bundle,LISTENER]</code>, and the
+	 *         Java Runtime Environment supports permissions.
 	 * @see BundleEvent
 	 * @see BundleListener
 	 */
@@ -356,12 +322,13 @@
 	 * of listeners, this method does nothing.
 	 * 
 	 * @param listener The <code>BundleListener</code> object to be removed.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
-	 * @throws java.lang.SecurityException If listener is a
+	 * @throws SecurityException If listener is a
 	 *         <code>SynchronousBundleListener</code> and the caller does not
-	 *         have the appropriate <code>AdminPermission[context bundle,LISTENER]</code>,
-	 *         and the Java Runtime Environment supports permissions.
+	 *         have the appropriate
+	 *         <code>AdminPermission[context bundle,LISTENER]</code>, and the
+	 *         Java Runtime Environment supports permissions.
 	 */
 	public void removeBundleListener(BundleListener listener);
 
@@ -376,9 +343,8 @@
 	 * does nothing.
 	 * 
 	 * @param listener The <code>FrameworkListener</code> object to be added.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
-	 * 
 	 * @see FrameworkEvent
 	 * @see FrameworkListener
 	 */
@@ -394,7 +360,7 @@
 	 * 
 	 * @param listener The <code>FrameworkListener</code> object to be
 	 *        removed.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
 	 */
 	public void removeFrameworkListener(FrameworkListener listener);
@@ -417,21 +383,21 @@
 	 * <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
-	 * fired.
+	 * <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 specified class names.
+	 * <li>The Framework adds the following service properties to the service
+	 * properties from the specified <code>Dictionary</code> (which may be
+	 * <code>null</code>): <br/>
+	 * A property named {@link Constants#SERVICE_ID} identifying the
+	 * registration number of the service <br/>
+	 * A property named {@link Constants#OBJECTCLASS} containing all the
+	 * specified classes. <br/>
+	 * Properties with these names in the specified <code>Dictionary</code> will
+	 * be ignored.
+	 * <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 fired.
 	 * <li>A <code>ServiceRegistration</code> object for this registration is
 	 * returned.
 	 * </ol>
@@ -447,32 +413,24 @@
 	 *        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.
-	 * 
+	 *        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.
-	 * 
-	 * @throws java.lang.IllegalArgumentException If one of the following is
-	 *         true:
+	 * @throws 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.
+	 *         <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>
-	 * 
-	 * @throws java.lang.SecurityException If the caller does not have the
+	 * @throws 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.
-	 * 
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
-	 *         longer valid.
-	 * 
+	 * @throws IllegalStateException If this BundleContext is no longer valid.
 	 * @see ServiceRegistration
 	 * @see ServiceFactory
 	 */
@@ -485,161 +443,129 @@
 	 * 
 	 * <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.
+	 * {@link #registerService(String[], Object, 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 string, rather
+	 * than just a single string.
 	 * 
 	 * @param clazz The class name under which the service can be located.
 	 * @param service The service object or a <code>ServiceFactory</code>
 	 *        object.
-	 * @param properties The properties for this service. 
-	 * 
+	 * @param properties The properties for this service.
 	 * @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.
-	 *         
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
-	 *         longer valid.
-	 * @see #registerService(java.lang.String[], java.lang.Object,
-	 *      java.util.Dictionary)
+	 * @throws IllegalStateException If this BundleContext is no longer valid.
+	 * @see #registerService(String[], Object, Dictionary)
 	 */
-	public ServiceRegistration registerService(String clazz,
-			Object service, Dictionary properties);
+	public 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
+	 * expression, 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 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.
+	 * unregistered at any time.
 	 * 
 	 * <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.
+	 * The specified <code>filter</code> expression is used to select the
+	 * registered services whose service properties contain keys and values
+	 * which satisfy the filter expression. See {@link Filter} for a description
+	 * of the filter syntax. If the specified <code>filter</code> is
+	 * <code>null</code>, all registered services are considered to match the
+	 * filter. If the specified <code>filter</code> expression cannot be parsed,
+	 * an {@link InvalidSyntaxException} will be thrown with a human readable
+	 * message where the filter became unparsable.
 	 * 
 	 * <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
+	 * The result is an array of <code>ServiceReference</code> objects for all
+	 * services that meet all of the following conditions:
+	 * <ul>
+	 * <li>If the specified class name, <code>clazz</code>, is not
+	 * <code>null</code>, the service must have been registered with the
+	 * specified class name. The complete list of class names with which a
+	 * service was registered is available from the service's
+	 * {@link Constants#OBJECTCLASS objectClass} property.
+	 * <li>If the specified <code>filter</code> is not <code>null</code>, the
+	 * filter expression must match the service.
+	 * <li>If the Java Runtime Environment supports permissions, the caller must
+	 * have <code>ServicePermission</code> with the <code>GET</code> action for
+	 * at least one of the class names under which the service was registered.
+	 * <li>For each class name with which the service was registered, 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>
+	 * bundle and the class name on the service's <code>ServiceReference</code>
+	 * object must return <code>true</code>
+	 * </ul>
 	 * 
 	 * @param clazz The class name with which the service was registered or
 	 *        <code>null</code> for all services.
-	 * @param filter The filter criteria.
+	 * @param filter The filter expression or <code>null</code> for all
+	 *        services.
 	 * @return An array of <code>ServiceReference</code> objects or
-	 *         <code>null</code> if no services are registered which satisfy
-	 *         the search.
-	 * @throws InvalidSyntaxException If <code>filter</code> contains an
-	 *         invalid filter string that cannot be parsed.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
-	 *         longer valid.
+	 *         <code>null</code> if no services are registered which satisfy the
+	 *         search.
+	 * @throws InvalidSyntaxException If the specified <code>filter</code>
+	 *         contains an invalid filter expression that cannot be parsed.
+	 * @throws IllegalStateException If this BundleContext is no longer valid.
 	 */
-	public ServiceReference[] getServiceReferences(String clazz,
-			String filter) throws InvalidSyntaxException;
+	public 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.
+	 * expression.
 	 * 
 	 * <p>
-	 * The list is valid at the time of the call to this method, however since
+	 * 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.
+	 * unregistered at any time.
 	 * 
 	 * <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.
+	 * The specified <code>filter</code> expression is used to select the
+	 * registered services whose service properties contain keys and values
+	 * which satisfy the filter expression. See {@link Filter} for a description
+	 * of the filter syntax. If the specified <code>filter</code> is
+	 * <code>null</code>, all registered services are considered to match the
+	 * filter. If the specified <code>filter</code> expression 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>
+	 * The result is an array of <code>ServiceReference</code> objects for all
+	 * services that meet all of the following conditions:
+	 * <ul>
+	 * <li>If the specified class name, <code>clazz</code>, is not
+	 * <code>null</code>, the service must have been registered with the
+	 * specified class name. The complete list of class names with which a
+	 * service was registered is available from the service's
+	 * {@link Constants#OBJECTCLASS objectClass} property.
+	 * <li>If the specified <code>filter</code> is not <code>null</code>, the
+	 * filter expression must match the service.
+	 * <li>If the Java Runtime Environment supports permissions, the caller must
+	 * have <code>ServicePermission</code> with the <code>GET</code> action for
+	 * at least one of the class names under which the service was registered.
+	 * </ul>
 	 * 
 	 * @param clazz The class name with which the service was registered or
 	 *        <code>null</code> for all services.
-	 * @param filter The filter criteria.
+	 * @param filter The filter expression or <code>null</code> for all
+	 *        services.
 	 * @return An array of <code>ServiceReference</code> objects or
-	 *         <code>null</code> if no services are registered which satisfy
-	 *         the search.
-	 * @throws InvalidSyntaxException If <code>filter</code> contains an
-	 *         invalid filter string that cannot be parsed.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
-	 *         longer valid.
+	 *         <code>null</code> if no services are registered which satisfy the
+	 *         search.
+	 * @throws InvalidSyntaxException If the specified <code>filter</code>
+	 *         contains an invalid filter expression that cannot be parsed.
+	 * @throws IllegalStateException If this BundleContext is no longer valid.
 	 * @since 1.3
 	 */
 	public ServiceReference[] getAllServiceReferences(String clazz,
@@ -650,14 +576,14 @@
 	 * 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.
+	 * The returned <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 any time.
 	 * 
 	 * <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
+	 * <code>null</code> filter expression. It is provided as a convenience for
 	 * when the caller is interested in any service that implements the
 	 * specified class.
 	 * <p>
@@ -669,16 +595,16 @@
 	 * 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.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
-	 *         longer valid.
+	 * @return A <code>ServiceReference</code> object, or <code>null</code> if
+	 *         no services are registered which implement the named class.
+	 * @throws IllegalStateException If this BundleContext is no longer valid.
 	 * @see #getServiceReferences(String, String)
 	 */
 	public ServiceReference getServiceReference(String clazz);
 
 	/**
-	 * Returns the specified service object for a service.
+	 * Returns the service object referenced by the specified
+	 * <code>ServiceReference</code> object.
 	 * <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
@@ -697,8 +623,7 @@
 	 * <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>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
@@ -710,25 +635,31 @@
 	 * 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 fired.
+	 * 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} containing a {@link ServiceException}
+	 * describing the error is fired.
 	 * <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>.
-	 * @throws 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.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 *         <code>reference</code> or <code>null</code> if the service is not
+	 *         registered, the service object returned by a
+	 *         <code>ServiceFactory</code> does not implement the classes under
+	 *         which it was registered or the <code>ServiceFactory</code> threw
+	 *         an exception.
+	 * @throws 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.
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
+	 * @throws IllegalArgumentException If the specified
+	 *         <code>ServiceReference</code> was not created by the same
+	 *         framework instance as this <code>BundleContext</code>.
 	 * @see #ungetService(ServiceReference)
 	 * @see ServiceFactory
 	 */
@@ -754,8 +685,8 @@
 	 * <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
+	 * 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.
@@ -765,8 +696,11 @@
 	 * @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.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
+	 * @throws IllegalArgumentException If the specified
+	 *         <code>ServiceReference</code> was not created by the same
+	 *         framework instance as this <code>BundleContext</code>.
 	 * @see #getService
 	 * @see ServiceFactory
 	 */
@@ -794,14 +728,14 @@
 	 * @return A <code>File</code> object that represents the requested file
 	 *         or <code>null</code> if the platform does not have file system
 	 *         support.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
+	 * @throws IllegalStateException If this BundleContext is no
 	 *         longer valid.
 	 */
 	public 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
+	 * 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>
@@ -810,16 +744,13 @@
 	 * 
 	 * @param filter The filter string.
 	 * @return A <code>Filter</code> object encapsulating the filter string.
-	 * @throws InvalidSyntaxException If <code>filter</code> contains an
-	 *         invalid filter string that cannot be parsed.
+	 * @throws InvalidSyntaxException If <code>filter</code> contains an invalid
+	 *         filter string that cannot be parsed.
 	 * @throws NullPointerException If <code>filter</code> is null.
-	 * @throws java.lang.IllegalStateException If this BundleContext is no
-	 *         longer valid.
-	 * 
-	 * @since 1.1
+	 * @throws IllegalStateException If this BundleContext is no longer valid.
 	 * @see "Framework specification for a description of the filter string syntax."
 	 * @see FrameworkUtil#createFilter(String)
+	 * @since 1.1
 	 */
-	public Filter createFilter(String filter)
-			throws InvalidSyntaxException;
+	public Filter createFilter(String filter) throws InvalidSyntaxException;
 }

Modified: felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleEvent.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleEvent.java?rev=782737&r1=782736&r2=782737&view=diff
==============================================================================
--- felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleEvent.java (original)
+++ felix/trunk/org.osgi.core/src/main/java/org/osgi/framework/BundleEvent.java Mon Jun  8 19:31:06 2009
@@ -1,7 +1,5 @@
 /*
- * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleEvent.java,v 1.19 2007/02/20 00:14:12 hargrave Exp $
- * 
- * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2009). All Rights Reserved.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -34,7 +32,7 @@
  * @Immutable
  * @see BundleListener
  * @see SynchronousBundleListener
- * @version $Revision: 1.19 $
+ * @version $Revision: 6542 $
  */
 
 public class BundleEvent extends EventObject {
@@ -51,8 +49,6 @@
 
 	/**
 	 * The bundle has been installed.
-	 * <p>
-	 * The value of <code>INSTALLED</code> is 0x00000001.
 	 * 
 	 * @see BundleContext#installBundle(String)
 	 */
@@ -64,8 +60,6 @@
 	 * The bundle's
 	 * {@link BundleActivator#start(BundleContext) BundleActivator start} method
 	 * has been executed if the bundle has a bundle activator class.
-	 * <p>
-	 * The value of <code>STARTED</code> is 0x00000002.
 	 * 
 	 * @see Bundle#start()
 	 */
@@ -77,8 +71,6 @@
 	 * The bundle's
 	 * {@link BundleActivator#stop(BundleContext) BundleActivator stop} method
 	 * has been executed if the bundle has a bundle activator class.
-	 * <p>
-	 * The value of <code>STOPPED</code> is 0x00000004.
 	 * 
 	 * @see Bundle#stop()
 	 */
@@ -86,8 +78,6 @@
 
 	/**
 	 * The bundle has been updated.
-	 * <p>
-	 * The value of <code>UPDATED</code> is 0x00000008.
 	 * 
 	 * @see Bundle#update()
 	 */
@@ -95,8 +85,6 @@
 
 	/**
 	 * The bundle has been uninstalled.
-	 * <p>
-	 * The value of <code>UNINSTALLED</code> is 0x00000010.
 	 * 
 	 * @see Bundle#uninstall
 	 */
@@ -104,8 +92,6 @@
 
 	/**
 	 * The bundle has been resolved.
-	 * <p>
-	 * The value of <code>RESOLVED</code> is 0x00000020.
 	 * 
 	 * @see Bundle#RESOLVED
 	 * @since 1.3
@@ -114,8 +100,6 @@
 
 	/**
 	 * The bundle has been unresolved.
-	 * <p>
-	 * The value of <code>UNRESOLVED</code> is 0x00000040.
 	 * 
 	 * @see Bundle#INSTALLED
 	 * @since 1.3
@@ -130,8 +114,6 @@
 	 * is about to be called if the bundle has a bundle activator class. This
 	 * event is only delivered to {@link SynchronousBundleListener}s. It is not
 	 * delivered to <code>BundleListener</code>s.
-	 * <p>
-	 * The value of <code>STARTING</code> is 0x00000080.
 	 * 
 	 * @see Bundle#start()
 	 * @since 1.3
@@ -146,8 +128,6 @@
 	 * is about to be called if the bundle has a bundle activator class. This
 	 * event is only delivered to {@link SynchronousBundleListener}s. It is not
 	 * delivered to <code>BundleListener</code>s.
-	 * <p>
-	 * The value of <code>STOPPING</code> is 0x00000100.
 	 * 
 	 * @see Bundle#stop()
 	 * @since 1.3
@@ -163,8 +143,6 @@
 	 * <code>BundleContext</code>. This event is only delivered to
 	 * {@link SynchronousBundleListener}s. It is not delivered to
 	 * <code>BundleListener</code>s.
-	 * <p>
-	 * The value of <code>LAZY_ACTIVATION</code> is 0x00000200.
 	 * 
 	 * @since 1.4
 	 */



Mime
View raw message