Update OSGi R8 API to the latest

Change-Id: Ifb5c360e8c198a8def8065501136e1ef89598e4b
Signed-off-by: Thomas Watson <tjwatson@us.ibm.com>

9 files changed, 187 insertions, 151 deletions

diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkEvent.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkEvent.java
index 41528f8de..bcff0614c 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkEvent.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkEvent.java
@@ -173,9 +173,9 @@ public class FrameworkEvent extends EventObject {
 	 * The Framework has stopped and the framework requires a new class loader
 	 * to restart.
 	 * <p>
-	 * This event is fired when the Framework has been stopped because of a stop
-	 * operation on the system bundle and the framework requires a new class
-	 * loader to be used to restart. For example, if a framework extension
+	 * This event is fired when the Framework has been stopped because of a
+	 * refresh operation on the system bundle and the framework requires a new
+	 * class loader to be used to restart. For example, if a framework extension
 	 * bundle has been refreshed. The source of this event is the System Bundle.
 	 * 
 	 * @since 1.9
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java
index d6df33668..9e455f9d4 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java
@@ -21,138 +21,156 @@ import java.io.InputStream;
 import java.util.Map;
 import java.util.Optional;
 
+import org.osgi.annotation.versioning.ConsumerType;
 import org.osgi.framework.Bundle;
 import org.osgi.framework.launch.Framework;
 import org.osgi.framework.namespace.IdentityNamespace;
 import org.osgi.framework.wiring.BundleRevisions;
 
 /**
- * A connect content provides a {@link Framework framework} access to the
- * content of a connect {@link ConnectModule module}. A framework may
- * {@link #open() open} and {@link #close() close} the content for a connect
- * module multiple times while the connect content is in use by the framework
- * instance. The framework must close the connect content once the connect
- * content is no longer used as the content of a current bundle revision or an
- * in use bundle revision.
+ * A {@code ConnectContent} provides a {@link Framework} instance access to the
+ * content of a {@link ConnectModule}.
  * <p>
- * An entry in a connect content is identified by a path name that is a
- * '{@code /}'-separated path. A connect content may treat directories as
- * entries. A directory entry path name will end with a slash ('/'). A directory
- * entry may be located using a path name that drops the trailing slash.
+ * A framework may {@link #open() open} and {@link #close() close} the content
+ * for a {@link ConnectModule} multiple times while the {@code ConnectContent}
+ * is in use by the framework. The framework must close the
+ * {@code ConnectContent} once the {@code ConnectContent} is no longer used as
+ * the content of a current bundle revision or an in use bundle revision.
+ * <p>
+ * An entry in a {@code ConnectContent} is identified by a path name that is a
+ * solidus (<code>'/' \u002F</code>) separated path. A {@code ConnectContent}
+ * may treat directories as entries. A directory entry path name will end with a
+ * solidus. A directory entry may be located using a path name that omits the
+ * trailing solidus.
  * 
  * @see BundleRevisions
  * @ThreadSafe
  * @author $Id$
  */
+@ConsumerType
 public interface ConnectContent {
 	/**
 	 * The {@code osgi.identity}
 	 * {@link IdentityNamespace#CAPABILITY_TAGS_ATTRIBUTE tags} attribute value
 	 * used by the framework to tag connect bundle revisions.
 	 */
-	public static final String TAG_OSGI_CONNECT = "osgi.connect";
+	String TAG_OSGI_CONNECT = "osgi.connect";
 
 	/**
-	 * Returns this connect content Manifest headers and values. The
-	 * {@link Optional#empty() empty} value is returned if the framework should
-	 * handle parsing the Manifest of the content itself.
+	 * Returns the Manifest headers and values of this {@code ConnectContent}.
 	 * 
-	 * @return This connect content Manifest headers and values.
-	 * @throws IllegalStateException if the connect content has been closed
+	 * @return An {@code Optional} containing the Manifest headers and values
+	 *         for this {@code ConnectContent}, or an empty {@code Optional} if
+	 *         the framework should handle parsing the Manifest of the content
+	 *         itself.
+	 * @throws IllegalStateException If this {@code ConnectContent} has been
+	 *             closed.
 	 */
 	Optional<Map<String,String>> getHeaders();
 
 	/**
-	 * Returns an iterable with all the entry names available in this
-	 * ConnectContent
+	 * Returns the entry names available in this {@code ConnectContent}.
 	 * 
-	 * @return the entry names
-	 * @throws IOException if an error occurs reading the ConnectContent
-	 * @throws IllegalStateException if the connect content has been closed
+	 * @return An {@code Iterable} which can supply the available entry names.
+	 * @throws IOException If an error occurs reading this
+	 *             {@code ConnectContent}.
+	 * @throws IllegalStateException If this {@code ConnectContent} has been
+	 *             closed.
 	 */
 	Iterable<String> getEntries() throws IOException;
 
 	/**
-	 * Returns the connect entry for the specified path name in this content.
+	 * Returns the {@link ConnectEntry} for the specified path name in this
+	 * content.
+	 * <p>
 	 * The {@link Optional#empty() empty} value is returned if an entry with the
 	 * specified path name does not exist. The path must not start with a
 	 * &quot;/&quot; and is relative to the root of this content. A connect
 	 * entry for a directory will have a path name that ends with a slash ('/').
 	 * 
-	 * @param path the path name of the entry
-	 * @return the connect entry, or {@link Optional#empty() empty} if not
-	 *         found.
-	 * @throws IllegalStateException if the connect content has been closed
+	 * @param path The path name of the entry.
+	 * @return An {@code Optional} containing the {@link ConnectEntry} for the
+	 *         specified path, or an empty {@code Optional} if no entry for
+	 *         specified path can be found.
+	 * @throws IllegalStateException If this {@code ConnectContent} has been
+	 *             closed.
 	 */
 	Optional<ConnectEntry> getEntry(String path);
 
 	/**
-	 * Returns a class loader for this connect content. The
-	 * {@link Optional#empty() empty} value is returned if the framework should
-	 * handle creating a class loader for the bundle revision associated with
-	 * this connect content.
+	 * Returns a class loader for this {@code ConnectContent}.
 	 * <p>
 	 * This method is called by the framework for {@link Bundle#RESOLVED
 	 * resolved} bundles only and will be called at most once while a bundle is
-	 * resolved. If a bundle associated with a connect module is refreshed and
-	 * resolved again the framework will ask the content for the class loader
-	 * again. This allows for a connect content to reuse or create a new class
-	 * loader each time the bundle revision is resolved.
+	 * resolved. If a bundle associated with a {@link ConnectModule} is
+	 * refreshed and resolved again, the framework will ask the
+	 * {@code ConnectContent} for the class loader again. This allows for a
+	 * {@code ConnectContent} to reuse or create a new class loader each time
+	 * the bundle revision is resolved.
 	 * 
-	 * @return a class loader for the content.
+	 * @return An {@code Optional} containing the class loader for this
+	 *         {@code ConnectContent}, or an empty {@code Optional} if framework
+	 *         should handle creating a class loader for the bundle revision
+	 *         associated with this {@code ConnectContent}.
+	 * @throws IllegalStateException If this {@code ConnectContent} has been
+	 *             closed.
 	 */
 	Optional<ClassLoader> getClassLoader();
 
 	/**
-	 * Opens this connect content. The framework will open the content when it
-	 * needs to access the content for a bundle revision associated with the
-	 * connect content. The framework may lazily postpone to open the content
-	 * until right before requests to access the bundle revision content are
-	 * made.
+	 * Opens this {@code ConnectContent}.
+	 * <p>
+	 * The framework will open the content when it needs to access the content
+	 * for a bundle revision associated with this {@code ConnectContent}. The
+	 * framework may defer calling this method until requests to access the
+	 * bundle revision content are made.
 	 * 
-	 * @throws IOException if an error occurred opening the content
+	 * @throws IOException If an error occurred opening this
+	 *             {@code ConnectContent}.
 	 */
 	void open() throws IOException;
 
 	/**
-	 * Closes this connect content.
+	 * Closes this {@code ConnectContent}.
 	 * 
-	 * @throws IOException if an error occurred closing the connect content
+	 * @throws IOException If an error occurred closing this
+	 *             {@code ConnectContent}.
 	 */
 	void close() throws IOException;
 
 	/**
-	 * Represents the entry of a connect content
+	 * Represents the entry of a {@code ConnectContent}.
 	 */
+	@ConsumerType
 	public interface ConnectEntry {
 		/**
-		 * Returns the path name of the entry
+		 * Returns the path name of this entry.
 		 * 
-		 * @return the path name of the entry
+		 * @return The path name of this entry.
 		 */
 		String getName();
 
 		/**
-		 * Returns the size of the entry. The value {@code -1} is returned if
-		 * the content length is not known.
+		 * Returns the content length of this entry.
 		 * 
-		 * @return the size of the entry, or {@code -1} if the content length is
-		 *         not known.
+		 * @return The content length of the entry, or {@code -1} if the content
+		 *         length is not known.
 		 */
 		public long getContentLength();
 
 		/**
-		 * Returns the last modification time of the entry
+		 * Returns the last modification time of this entry.
 		 * 
-		 * @return the last modification time of the entry
+		 * @return The last modification time of this entry measured in
+		 *         milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
 		 */
 		public long getLastModified();
 
 		/**
-		 * Returns the content of the entry as a byte array.
+		 * Returns the content of this entry.
 		 * 
-		 * @return the content bytes
-		 * @throws IOException if an error occurs reading the content
+		 * @return The content of this entry.
+		 * @throws IOException If an error occurs reading the content.
 		 */
 		default byte[] getBytes() throws IOException {
 			long longLength = getContentLength();
@@ -190,10 +208,10 @@ public interface ConnectContent {
 		}
 
 		/**
-		 * Returns the content of the entry as an input stream.
+		 * Returns an input stream for the content of this entry.
 		 * 
-		 * @return the content input stream
-		 * @throws IOException if an error occurs reading the content
+		 * @return An input stream for the content of this entry.
+		 * @throws IOException If an error occurs reading the content.
 		 */
 		InputStream getInputStream() throws IOException;
 	}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java
index 9bb703015..fee4e8875 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java
@@ -24,7 +24,7 @@ import org.osgi.framework.launch.Framework;
 /**
  * A factory for creating {@link Framework} instances.
  * <p>
- * If a framework supports {@link ModuleConnector} then the implementation jar
+ * If a framework supports {@link ModuleConnector}, then the implementation jar
  * must contain the following resource:
  * 
  * <pre>
@@ -73,7 +73,6 @@ public interface ConnectFrameworkFactory {
 	 *             {@code AllPermission}, and the Java Runtime Environment
 	 *             supports permissions.
 	 * @see ModuleConnector
-	 * @since 1.3
 	 */
 	Framework newFramework(Map<String,String> configuration,
 			ModuleConnector moduleConnector);
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectModule.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectModule.java
index 2661cc8c1..d81245bff 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectModule.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectModule.java
@@ -17,28 +17,30 @@ package org.osgi.framework.connect;
 
 import java.io.IOException;
 
+import org.osgi.annotation.versioning.ConsumerType;
 import org.osgi.framework.launch.Framework;
 import org.osgi.framework.wiring.BundleRevision;
 
 /**
- * A connect module instance is used by a {@link Framework framework} when a
- * bundle location is connected to connect module. The connected bundle must use
- * the connect module to load content for the bundle revisions installed in the
- * framework for the connected bundle.
+ * A {@code ConnectModule} is used by a {@link Framework} instance to access the
+ * content of the connected bundle.
  * 
  * @ThreadSafe
  * @author $Id$
  */
+@ConsumerType
 public interface ConnectModule {
 	/**
-	 * Returns the current content of this connect module. The framework will
-	 * call this method when it needs to access the content for the current
-	 * {@link BundleRevision bundle revision} that is connected to this connect
-	 * module. The framework may lazily postpone to open the content until right
-	 * before requests to access the bundle revision content are made.
+	 * Returns the current content of this connect module.
+	 * <p>
+	 * The framework must call this method when it needs to access the content
+	 * for the current {@link BundleRevision bundle revision} of this
+	 * {@code ConnectModule}. The framework may defer opening the returned
+	 * {@link ConnectContent} until requests to access the bundle revision
+	 * content are made.
 	 * 
-	 * @return the current content of this connect module
-	 * @throws IOException if an error occurred getting the content
+	 * @return The current {@link ConnectContent} of this {@code ConnectModule}.
+	 * @throws IOException If an error occurred getting the content.
 	 * @see ModuleConnector#connect(String)
 	 */
 	ConnectContent getContent() throws IOException;
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java
index d418a6bcc..f7b54ab0f 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2019). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2019, 2020). 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.
@@ -18,24 +18,29 @@ package org.osgi.framework.connect;
 
 import java.util.Optional;
 
+import org.osgi.annotation.versioning.ConsumerType;
 import org.osgi.framework.Bundle;
 import org.osgi.framework.FrameworkUtil;
 
 /**
- * A helper for the {@link FrameworkUtil} class. This helper provides
- * alternative implementations for methods on {@link FrameworkUtil}.
+ * A helper for the {@link FrameworkUtil} class.
+ * <p>
+ * This helper provides alternative implementations for methods on
+ * {@link FrameworkUtil}.
  */
+@ConsumerType
 public interface FrameworkUtilHelper {
 	/**
-	 * Return a {@code Bundle} associated with the specified class.
+	 * Returns the {@link Bundle} associated with the specified class.
 	 * <p>
 	 * This helper method is called by {@link FrameworkUtil#getBundle(Class)} if
-	 * the standard implementation of {@code FrameworkUtil} cannot find the
-	 * bundle.
+	 * the standard implementation of {@link FrameworkUtil} is unable to find
+	 * the bundle.
 	 * 
-	 * @param classFromBundle A class associated with a bundle
-	 * @return An Optional containing a {@code Bundle} for the specified class
-	 *         or an empty Optional if the specified class is not from a bundle.
+	 * @param classFromBundle A class associated with a bundle.
+	 * @return An {@code Optional} containing the {@link Bundle} for the
+	 *         specified class, or an empty {@code Optional} if the specified
+	 *         class is not from a bundle.
 	 */
 	default Optional<Bundle> getBundle(Class< ? > classFromBundle) {
 		return Optional.empty();
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ModuleConnector.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ModuleConnector.java
index da93a235c..5ee358acf 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ModuleConnector.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ModuleConnector.java
@@ -19,77 +19,87 @@ import java.io.File;
 import java.util.Map;
 import java.util.Optional;
 
+import org.osgi.annotation.versioning.ConsumerType;
 import org.osgi.framework.BundleActivator;
+import org.osgi.framework.BundleContext;
 import org.osgi.framework.BundleException;
 import org.osgi.framework.Constants;
+import org.osgi.framework.FrameworkListener;
 import org.osgi.framework.launch.Framework;
 
 /**
- * A <code>ModuleConnector</code> provides connections to instances of
+ * A {@code ModuleConnector} provides connections to instances of
  * {@link ConnectModule} that are used by a {@link Framework} instance to
  * connect installed bundles locations with content provided by the
- * <code>ModuleConnector</code>. This allows a <code>ModuleConnector</code> to
- * provide content and classes for a connected bundle installed in the
- * <code>Framework</code>. A <code>ModuleConnector</code> is provided when
- * {@link ConnectFrameworkFactory#newFramework(java.util.Map, ModuleConnector)
- * creating} a framework instance. Because a <code>ModuleConnector</code>
- * instance can participate in the initialization of the <code>Framework</code>
- * and the life cycle of a <code>Framework</code> instance the
- * <code>ModuleConnector</code> instance should only be used with a single
- * <code>Framework</code> instance at a time.
+ * {@code ModuleConnector}.
+ * <p>
+ * This allows a {@code ModuleConnector} to provide content and classes for a
+ * connected bundle installed in the {@code Framework}. A
+ * {@code ModuleConnector} is provided when
+ * {@link ConnectFrameworkFactory#newFramework(Map, ModuleConnector) creating} a
+ * framework instance. Because a {@code ModuleConnector} instance can
+ * participate in the initialization of the {@code Framework} and the life cycle
+ * of a {@code Framework} instance the {@code ModuleConnector} instance should
+ * only be used with a single {@code Framework} instance at a time.
  * 
  * @ThreadSafe
  * @author $Id$
  */
+@ConsumerType
 public interface ModuleConnector {
 
 	/**
-	 * Initializes this module connector with the
+	 * Initializes this {@code ModuleConnector} with the
 	 * {@link Constants#FRAMEWORK_STORAGE framework persistent storage} file and
-	 * framework properties configured for a {@link Framework} instance. This
-	 * method is called once by a {@link Framework} instance and is called
+	 * framework properties configured for a {@link Framework} instance.
+	 * <p>
+	 * This method is called once by a {@link Framework} instance and is called
 	 * before any other methods on this module connector are called.
 	 * 
-	 * @param configuration The framework properties used configure the new
-	 *            framework instance. An unmodifiable map of framework
-	 *            configuration properties that were used to create a new
-	 *            framework instance.
-	 * @param storage the persistent storage area used by the {@link Framework}
+	 * @param storage The persistent storage area used by the {@link Framework}
 	 *            or {@code null} if the platform does not have file system
 	 *            support.
+	 * @param configuration An unmodifiable map of framework configuration
+	 *            properties that were used to configure the new framework
+	 *            instance.
 	 */
 	void initialize(File storage, Map<String,String> configuration);
 
 	/**
-	 * Connects a bundle location with a {@link ConnectModule}. If an
-	 * {@link Optional#empty() empty} optional is returned then the framework
-	 * must handle reading the content of the bundle itself. If a value is
-	 * {@link Optional#isPresent() present} in the returned optional then the
-	 * <code>ConnectModule</code> {@link Optional#get() value} from the optional
-	 * must be used to connect the bundle to the returned {@link ConnectModule}.
-	 * The returned connect module is used by the framework to access the
-	 * content of the bundle.
+	 * Connects a bundle location with a {@link ConnectModule}.
+	 * <p>
+	 * When the result is empty, then the framework must handle reading the
+	 * content of the bundle itself. Otherwise, the returned
+	 * {@link ConnectModule} must be used by the framework to access the content
+	 * of the bundle.
 	 * 
-	 * @param location the bundle location used to install a bundle
-	 * @return the connect module for the specified bundle location
-	 * @throws BundleException if the location cannot be handled
+	 * @param location The bundle location used to install a bundle.
+	 * @return An {@code Optional} containing the {@link ConnectModule} for the
+	 *         specified bundle location, or an empty {@code Optional} if the
+	 *         framework must handle reading the content of the bundle itself.
+	 * @throws BundleException If the location cannot be handled.
 	 */
 	Optional<ConnectModule> connect(String location) throws BundleException;
 
 	/**
-	 * Creates a new activator for this module connector. A new activator is
-	 * created by the framework each time the framework is
-	 * {@link Framework#init() initialized}. An activator allows the module
-	 * connector to participate in the framework life cycle. When the framework
-	 * is {@link Framework#init() initialized} the activator
-	 * {@link BundleActivator#start(org.osgi.framework.BundleContext) start}
-	 * method is called. When the framework is {@link Framework#stop() stopped}
-	 * the activator
-	 * {@link BundleActivator#stop(org.osgi.framework.BundleContext) stop}
-	 * method is called
+	 * Creates a new activator for this {@code ModuleConnector}.
+	 * <p>
+	 * This method is called by the framework during framework
+	 * {@link Framework#init(FrameworkListener...) initialization}. Returning an
+	 * activator allows this {@code ModuleConnector} to participate in the
+	 * framework life cycle. If an activator is returned:
+	 * <ul>
+	 * <li>The framework will call the activator's
+	 * {@link BundleActivator#start(BundleContext) start} method prior to
+	 * activating any extension bundles.</li>
+	 * <li>The framework will call the activator's
+	 * {@link BundleActivator#stop(BundleContext) stop} method after
+	 * deactivating any extension bundles.</li>
+	 * </ul>
 	 * 
-	 * @return a new activator for this module connector or
-	 *         {@link Optional#empty() empty} if no activator is available
+	 * @return An {@code Optional} containing a new {@link BundleActivator} for
+	 *         this {@code ModuleConnector}, or an empty {@code Optional} if no
+	 *         {@link BundleActivator} is necessary.
 	 */
 	Optional<BundleActivator> newBundleActivator();
 }
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/package-info.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/package-info.java
index a196dc76c..b7344ca62 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/package-info.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/package-info.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2010, 2019). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2019, 2020). 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.
@@ -31,4 +31,3 @@
 package org.osgi.framework.connect;
 
 import org.osgi.annotation.versioning.Version;
-
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java
index 2c9536186..bf960bdc3 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java
@@ -118,31 +118,33 @@ public interface Framework extends Bundle {
 	 * A Framework Event is returned to indicate why this Framework has stopped.
 	 * 
 	 * @param timeout Maximum number of milliseconds to wait until this
-	 *        Framework has completely stopped. A value of zero will wait
-	 *        indefinitely.
+	 *            Framework has completely stopped. A value of zero will wait
+	 *            indefinitely.
 	 * @return A Framework Event indicating the reason this method returned. The
 	 *         following {@code FrameworkEvent} types may be returned by this
 	 *         method.
 	 *         <ul>
 	 *         <li>{@link FrameworkEvent#STOPPED STOPPED} - This Framework has
-	 *         been stopped. </li>
-	 * 
+	 *         been stopped.</li>
 	 *         <li>{@link FrameworkEvent#STOPPED_UPDATE STOPPED_UPDATE} - This
 	 *         Framework has been updated which has shutdown and will now
 	 *         restart.</li>
-	 * 
+	 *         <li>{@link FrameworkEvent#STOPPED_SYSTEM_REFRESHED
+	 *         STOPPED_SYSTEM_REFRESHED} - The Framework has been stopped
+	 *         because of a refresh operation on the system bundle. A new class
+	 *         loader must be used to restart the Framework.</li>
 	 *         <li>{@link FrameworkEvent#ERROR ERROR} - The Framework
 	 *         encountered an error while shutting down or an error has occurred
-	 *         which forced the framework to shutdown. </li>
-	 * 
-	 *         <li> {@link FrameworkEvent#WAIT_TIMEDOUT WAIT_TIMEDOUT} - This
+	 *         which forced the framework to shutdown.</li>
+	 *         <li>{@link FrameworkEvent#WAIT_TIMEDOUT WAIT_TIMEDOUT} - This
 	 *         method has timed out and returned before this Framework has
 	 *         stopped.</li>
 	 *         </ul>
 	 * @throws InterruptedException If another thread interrupted the current
-	 *         thread before or while the current thread was waiting for this
-	 *         Framework to completely stop. The <i>interrupted status</i> of
-	 *         the current thread is cleared when this exception is thrown.
+	 *             thread before or while the current thread was waiting for
+	 *             this Framework to completely stop. The <i>interrupted
+	 *             status</i> of the current thread is cleared when this
+	 *             exception is thrown.
 	 * @throws IllegalArgumentException If the value of timeout is negative.
 	 */
 	FrameworkEvent waitForStop(long timeout) throws InterruptedException;
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condition/Condition.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condition/Condition.java
index 34980301c..f196a94f7 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condition/Condition.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condition/Condition.java
@@ -19,19 +19,18 @@ package org.osgi.service.condition;
 import org.osgi.annotation.versioning.ConsumerType;
 
 /**
- * OSGi due to its modular nature provides <code>Requirements</code> and
- * <code>Capabilities</code> to declare what a Bundle needs in order to run
- * properly. This is honored by the resolver and enforced by the Framework at
- * runtime. The dynamic nature however can provide some impediments at runtime.
- * That there is a Bundle that might provide a certain service or capability
- * does not mean, that it will be available when and a component expects it be.
- * <p>
- * Conditions are to the Service Layer what Requirements and Capabilities are to
- * the module Layer
+ * In dynamic systems, such as OSGi, one of the more challenging problems can be
+ * to define when a System or part of it is ready to do work. The answer can
+ * change depending on the individual perspective. The developer of a Webserver
+ * might say, the System is ready when the server starts listening to port 80.
+ * An Application developer however would define the system as ready, when the
+ * database connection is up and all Servlets are registered. Taking the
+ * Application developers view, the Server should start Listening on Port 80
+ * when the System is ready and not beforehand.
  * <p>
  * The <code>Condition</code> interface is designed to address this issue. Its
- * task is to provide a marker that can be tracked if a some Condition is meet
- * and for example a Requirement is meet at Runtime.
+ * task is to provide a marker that can be tracked. It acts as a defined signal
+ * to other services.
  * <p>
  * A Condition must be registered with the {@link Condition#CONDITION_ID} as
  * property.
@@ -41,9 +40,11 @@ import org.osgi.annotation.versioning.ConsumerType;
  */
 @ConsumerType
 public interface Condition {
+
 	/**
-	 * Service property identifying a condition's unique identifier. The type of
-	 * this service property is {@code String+}
+	 * Service property identifying a condition's unique identifier. As a
+	 * Condition can potentially describe more then one state, the type of this
+	 * service property is {@code String+}
 	 */
 	public static final String		CONDITION_ID		= "osgi.condition.id";