Bug 253243 [osgi] Keep API up to date with latest OSGi R4.2 specification

4 files changed, 72 insertions, 65 deletions

diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condpermadmin/BundleSignerCondition.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condpermadmin/BundleSignerCondition.java
index c041595a5..becd01169 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condpermadmin/BundleSignerCondition.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condpermadmin/BundleSignerCondition.java
@@ -50,7 +50,7 @@ import org.osgi.framework.FrameworkUtil;
  * RDNs).
  * 
  * @ThreadSafe
- * @version $Revision: 6063 $
+ * @version $Revision: 6124 $
  */
 public class BundleSignerCondition {
 	private static final String	CONDITION_TYPE	= "org.osgi.service.condpermadmin.BundleSignerCondition";
@@ -73,7 +73,8 @@ public class BundleSignerCondition {
 	 *        then the second argument is ignored.
 	 * @return A Condition which checks the signers of the specified bundle.
 	 */
-	public static Condition getCondition(Bundle bundle, ConditionInfo info) {
+	public static Condition getCondition(final Bundle bundle,
+			final ConditionInfo info) {
 		if (!CONDITION_TYPE.equals(info.getType()))
 			throw new IllegalArgumentException(
 					"ConditionInfo must be of type \"" + CONDITION_TYPE + "\"");
@@ -89,9 +90,10 @@ public class BundleSignerCondition {
 				.hasNext();) {
 			List/* <X509Certificate> */signerCerts = (List) iSigners.next();
 			List/* <String> */dnChain = new ArrayList(signerCerts.size());
-			for (Iterator iCerts = signerCerts.iterator(); iCerts.hasNext();)
+			for (Iterator iCerts = signerCerts.iterator(); iCerts.hasNext();) {
 				dnChain.add(((X509Certificate) iCerts.next()).getSubjectDN()
 						.getName());
+			}
 			if (FrameworkUtil.matchDistinguishedNameChain(args[0], dnChain)) {
 				match = true;
 				break;
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/CompositeBundle.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/CompositeBundle.java
index 072bbfc11..a2c13f556 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/CompositeBundle.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/CompositeBundle.java
@@ -29,7 +29,7 @@ import org.osgi.framework.launch.Framework;
  * use services from other bundles which are installed in the same framework as
  * the composite bundle. The packages imported and the services used by a
  * composite bundle are shared with the components of a composite bundle through
- * the surrogate bundle installed in the child framework. Also like a normal
+ * a surrogate bundle installed in the child framework. Also like a normal
  * bundle, a composite bundle may export packages and register services which
  * can be used by bundles installed in the same framework as the composite
  * bundle. The packages exported and the services registered by a composite
@@ -39,8 +39,9 @@ import org.osgi.framework.launch.Framework;
  * A framework has one composite bundle for each of its child frameworks. A
  * framework can have zero or more composite bundles installed. A child
  * framework must have one and only one surrogate bundle which represents the
- * composite bundle. In other words a parent framework can have many children
- * frameworks but a child framework can only have one parent.
+ * composite bundle in the parent framework. In other words, a parent framework
+ * can have many child frameworks but a child framework can have only one
+ * parent.
  * <p>
  * A composite bundle does the following as specified by the composite manifest
  * map:
@@ -60,9 +61,9 @@ import org.osgi.framework.launch.Framework;
  * A newly created child <code>Framework</code> will be in the
  * {@link Bundle#STARTING STARTING} state. This child <code>Framework</code> can
  * then be used to manage and control the child framework instance. The child
- * framework instance is persistent and uses a storage area in the composite
- * bundle's data area. The child framework's lifecycle is tied to its composite
- * bundle's lifecycle in the following ways:
+ * framework instance is persistent and uses a storage area associated with the
+ * installed composite bundle. The child framework's lifecycle is tied to its
+ * composite bundle's lifecycle in the following ways:
  * <p>
  * <ul>
  * <li>If the composite bundle is marked to be persistently started (see
@@ -73,7 +74,9 @@ import org.osgi.framework.launch.Framework;
  * persistently stopped or its start level is no longer met. Performing
  * operations which transiently stop a composite bundle do not cause the child
  * framework to stop (e.g. {@link Bundle#stop(int) stop(Bundle.STOP_TRANSIENT)},
- * {@link Bundle#update() update}, refreshPackage etc.).</li>
+ * {@link Bundle#update() update}, refreshPackages etc.).</li>
+ * <li>If the composite bundle is uninstalled, the child framework's persistent
+ * storage area is also uninstalled.</li>
  * </ul>
  * <p>
  * The child framework may be persistently started and stopped by persistently
@@ -82,41 +85,41 @@ import org.osgi.framework.launch.Framework;
  * bundle is not persistently started. This allows for the child framework to be
  * initialized and populated with a set of bundles before starting the composite
  * bundle. The set of bundles installed into the child framework are the
- * component bundles which compose the composite bundle.
+ * component bundles which comprise the composite bundle.
  * <p>
- * If the child framework is started while the composite bundle is not
- * persistently started then the child framework lifecycle is tied to its parent
- * framework lifecycle. When the parent <code>Framework</code> enters the
- * {@link Bundle#STOPPING STOPPING} state then all active child frameworks of
- * that parent are shutdown using the to the {@link Framework#stop()} method.
- * The parent <code>Framework</code> must not enter the {@link Bundle#RESOLVED}
- * state until all the child frameworks have completed their shutdown process.
- * After the parent framework has completed the shutdown process then all child
- * framework instances become invalid and must not be allowed to re-initialize
- * or re-start.
+ * The child framework's lifecycle is also tied to the lifecycle of its
+ * parent framework. When the parent <code>Framework</code> enters the
+ * {@link Bundle#STOPPING STOPPING} state, all active child frameworks of that
+ * parent are shutdown using the {@link Framework#stop()} method. The parent
+ * framework must not enter the {@link Bundle#RESOLVED} state until all the
+ * child frameworks have completed their shutdown process. Just as with other
+ * Bundles, references to child frameworks (or the associated composite and
+ * surrogate bundles) become invalid after the parent framework has completed
+ * the shutdown process, and must not be allowed to re-initialize or re-start
+ * the child framework.
  * 
  * @see SurrogateBundle
  * @ThreadSafe
- * @version $Revision: 1.1.2.2 $
+ * @version $Revision: 6156 $
  */
 public interface CompositeBundle extends Bundle {
 	/**
-	 * Returns the composite framework associated with this composite bundle.
+	 * Returns the child framework associated with this composite bundle.
 	 * 
-	 * @return the companion framework.
+	 * @return the child framework.
 	 */
 	Framework getCompositeFramework();
 
 	/**
 	 * Returns the surrogate bundle associated with this composite bundle. The
-	 * surrogate bundle is installed in the composite framework.
+	 * surrogate bundle is installed in the child framework.
 	 * 
 	 * @return the surrogate bundle.
 	 */
 	SurrogateBundle getSurrogateBundle();
 
 	/**
-	 * Updates this child composite bundle with the specified manifest.
+	 * Updates this composite bundle with the specified manifest.
 	 * 
 	 * @param compositeManifest the new composite manifest.
 	 * @throws BundleException If the update fails.
@@ -142,10 +145,8 @@ public interface CompositeBundle extends Bundle {
 	void update(InputStream input) throws BundleException;
 
 	/**
-	 * Uninstalls this composite bundle and its companion bundle.
-	 * <p>
-	 * If this composite bundle is a child composite then the companion child
-	 * framework is shutdown and its persistent storage area is deleted.
+	 * Uninstalls this composite bundle. The associated child framework
+	 * is shutdown, and its persistent storage area is deleted.
 	 */
 	void uninstall() throws BundleException;
 }
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/CompositeBundleFactory.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/CompositeBundleFactory.java
index 797327cb0..67a909a02 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/CompositeBundleFactory.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/CompositeBundleFactory.java
@@ -29,23 +29,23 @@ import org.osgi.framework.launch.Framework;
  * with the Framework.
  * 
  * @ThreadSafe
- * @version $Revision: 1.1.2.2 $
+ * @version $Revision: 6156 $
  */
 // TODO javadoc needs review
 public interface CompositeBundleFactory {
 	/**
 	 * Manifest header (named &quot;CompositeServiceFilter-Import&quot;)
-	 * identifying the service filters that are used by a child composite bundle
-	 * to select services that will be registered into a child framework from a
-	 * parent composite bundle.
+	 * identifying the service filters that are used by a composite bundle
+	 * to select services that will be registered into a child framework by its
+	 * associated surrogate bundle.
 	 */
 	public static final String	COMPOSITE_SERVICE_FILTER_IMPORT	= "CompositeServiceFilter-Import";
 
 	/**
 	 * Manifest header (named &quot;CompositeServiceFilter-Export&quot;)
-	 * identifying the service filters that are used by a parent composite
+	 * identifying the service filters that are used by a surrogate
 	 * bundle to select services that will be registered into a parent framework
-	 * from a child composite bundle.
+	 * by its associated composite bundle.
 	 */
 	public static final String	COMPOSITE_SERVICE_FILTER_EXPORT	= "CompositeServiceFilter-Export";
 
@@ -53,20 +53,21 @@ public interface CompositeBundleFactory {
 	 * Installs a <code>CompositeBundle</code>. The composite bundle has a new
 	 * child <code>Framework</code> associated with it and a surrogate bundle
 	 * which is installed in the child framework. Composite bundles share
-	 * packages and services between parent framework they are installed in and
-	 * the the child framework.
+	 * packages and services between the parent framework they are installed in and
+	 * the child framework.
 	 * <p>
 	 * The following steps are required to create a composite bundle:
 	 * <ol>
-	 * <li>If a bundle containing the same location string is already installed,
-	 * then if the Bundle object is a <code>CompositeBundle</code> then that
-	 * composite bundle is returned; otherwise a BundleException is thrown
-	 * indicating that an incompatible bundle is already installed at the
+	 * <li>If a bundle containing the same location string is already installed
+	 * and the Bundle object is a <code>CompositeBundle</code>, then that
+	 * composite bundle is returned; otherwise a <code>BundleException</code> 
+	 * is thrown indicating that an incompatible bundle is already installed at the
 	 * specified location.</li>
 	 * <li>The composite bundle's associated resources are allocated. The
 	 * associated resources minimally consist of a unique identifier and a
-	 * persistent storage area. If this step fails, a BundleException is thrown.
-	 * <li>The compositeManifest map is used to provide the headers for the
+	 * persistent storage area. If this step fails, a <code>BundleException</code> 
+	 * is thrown.</li>
+	 * <li>The <code>compositeManifest</code> map is used to provide the headers for the
 	 * composite bundle and its surrogate bundle.
 	 * <p>
 	 * If composite manifest map does not contain the following header(s) then a
@@ -75,7 +76,7 @@ public interface CompositeBundleFactory {
 	 * <li> {@link Constants#BUNDLE_SYMBOLICNAME Bundle-SymbolicName} the
 	 * symbolic name used for the composite bundle and its surrogate bundle.
 	 * </ul>
-	 * </p>
+	 * </p><p>
 	 * The composite manifest map may optionally contain the following
 	 * header(s):
 	 * <ul>
@@ -97,42 +98,44 @@ public interface CompositeBundleFactory {
 	 * the parent framework by the composite bundle.</li>
 	 * <li>{@link Constants#BUNDLE_MANIFESTVERSION Bundle-ManifestVersion} the
 	 * bundle manifest version. If this header is not specified then the default
-	 * is to use version 2. A BundleException is thrown if this header is
+	 * is to use version 2. A <code>BundleException</code> is thrown if this header is
 	 * specified and the version is less than 2.</li>
 	 * </ul>
+	 * </p><p>
 	 * The composite manifest map must not contain the following headers. If a
 	 * composite manifest map does contain one of the following headers then a
-	 * BundleException is thrown:
+	 * <code>BundleException</code> is thrown:
 	 * <ul>
 	 * <li> {@link Constants#BUNDLE_ACTIVATIONPOLICY Bundle-ActivationPolicy}</li>
 	 * <li> {@link Constants#BUNDLE_ACTIVATOR Bundle-Activator}</li>
 	 * <li> {@link Constants#BUNDLE_CLASSPATH Bundle-ClassPath}</li>
 	 * <li> {@link Constants#BUNDLE_LOCALIZATION Bundle-Localization}</li>
 	 * <li> {@link Constants#BUNDLE_NATIVECODE Bundle-NativeCode}</li>
-	 * <li> {@link Constants#DYNAMICIMPORT_PACKAGE DynamicImport-Package}</li>
 	 * <li> {@link Constants#FRAGMENT_HOST Fragment-Host}</li>
+	 * <li> {@link Constants#DYNAMICIMPORT_PACKAGE DynamicImport-Package}</li>
 	 * <li> {@link Constants#REQUIRE_BUNDLE Require-Bundle}</li>
 	 * </ul>
-	 * <li>A child framework is created which uses a storage area under the
-	 * composite bundle's associated persistent storage. Note that if the
-	 * framework configuration property {@link Constants#FRAMEWORK_STORAGE
-	 * org.osgi.framework.storage} is specified in the framework config then it
-	 * is ignored.</li>
+	 * </li>
+	 * <li>A child framework is created which uses a storage area associated with
+	 * the composite bundle's persistent storage. The framework configuration 
+	 * property {@link Constants#FRAMEWORK_STORAGE org.osgi.framework.storage}, 
+	 * if specified, is ignored.</li>
 	 * <li>The child framework is initialized (see {@link Framework#init()}).
-	 * <li>A surrogate bundle is installed into the child framework</li>
+	 * <li>A surrogate bundle is created and installed into the child framework.</li>
 	 * <li>The composite bundle's state is set to INSTALLED.</li>
 	 * <li>A bundle event of type {@link BundleEvent#INSTALLED} is fired for the
 	 * composite bundle.
-	 * <li>The <code>CompositeBundle</code> object for the newly composite
-	 * bundle is returned
+	 * <li>The <code>CompositeBundle</code> object for the new composite
+	 * bundle is returned.
 	 * </ol>
 	 * <p>
 	 * 
-	 * @param frameworkConfig the child framework configuration.
-	 * @param location the bundle location used for the child composite bundle
-	 *        and its companion bundle.
-	 * @param compositeManifest the manifest used to create the composite bundle
-	 * @return A new child composite bundle.
+	 * @param frameworkConfig A map containing configuration parameters used to 
+	 *        initialize and launch the child framework.
+	 * @param location The bundle location used for the composite and surrogate bundles.
+	 * @param compositeManifest A map containing the manifest used to create the composite
+	 *        and surrogate bundles
+	 * @return A new composite bundle in INSTALLED state.
 	 * @throws BundleException If the composite manifest is invalid or there is
 	 *         some other problem with installing the composite bundle.
 	 * @throws SecurityException If the caller does not have
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/SurrogateBundle.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/SurrogateBundle.java
index 5c95e7860..cf4ba113c 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/SurrogateBundle.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/framework/SurrogateBundle.java
@@ -22,7 +22,9 @@ import org.osgi.framework.BundleContext;
 import org.osgi.framework.BundleException;
 
 /**
- * A surrogate bundle represents a composite bundle within a child framework.  
+ * A surrogate bundle is installed in a child framework, and is the child-facing
+ * representation of the composite bundle in the parent framework.
+ * <p>  
  * A surrogate bundle does the following as specified by the composite manifest:
  * <ul>
  * <li>Exports packages to the child framework from the parent framework. These
@@ -30,7 +32,7 @@ import org.osgi.framework.BundleException;
  * framework.</li>
  * <li>Imports packages from the child framework. These packages are exported
  * by the composite bundle installed in the parent framework.</li>
- * <li>Registers services with the child framework from the parent framework.
+ * <li>Registers services from the parent framework with the child framework.
  * These services are acquired by the composite bundle installed in the 
  * parent framework.</li>
  * <li>Acquires services from the child framework.  These services are 
@@ -41,8 +43,7 @@ import org.osgi.framework.BundleException;
  */
 public interface SurrogateBundle extends Bundle {
 	/**
-	 * Returns the bundle context of the composite bundle which this
-	 * surrogate bundle represents.
+	 * Returns the bundle context of the associated composite bundle.
 	 * @return the bundle context of the composite bundle.  A value 
 	 * of <code>null</code> is returned if the composite bundle does 
 	 * not have a valid bundle context.