svn commit: r1328415 [1/2] - in /aries/trunk/subsystem: ./ subsystem-api/src/main/java/org/osgi/service/repository/ subsystem-api/src/main/java/org/osgi/service/resolver/ subsystem-api/src/main/java/org/osgi/service/subsystem/

[jw...@apache.org]

Author: jwross
Date: Fri Apr 20 15:41:40 2012
New Revision: 1328415

URL: http://svn.apache.org/viewvc?rev=1328415&view=rev
Log:
ARIES-825: Updated subsystem-api with latest repository, resolver, and subsystem APIs from OSGi.

Modified:
    aries/trunk/subsystem/pom.xml
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/Repository.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/RepositoryContent.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/package-info.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/HostedCapability.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/ResolutionException.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/ResolveContext.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/Resolver.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/package-info.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/subsystem/Subsystem.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/subsystem/SubsystemConstants.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/subsystem/SubsystemException.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/subsystem/SubsystemPermission.java
    aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/subsystem/package-info.java

Modified: aries/trunk/subsystem/pom.xml
URL: http://svn.apache.org/viewvc/aries/trunk/subsystem/pom.xml?rev=1328415&r1=1328414&r2=1328415&view=diff
==============================================================================
--- aries/trunk/subsystem/pom.xml (original)
+++ aries/trunk/subsystem/pom.xml Fri Apr 20 15:41:40 2012
@@ -168,18 +168,18 @@
                             <force>false</force>
                             <artifactItems>
                                 <artifactItem>
-                                    <groupId>org.eclipse</groupId>
-                                    <artifactId>org.eclipse.osgi</artifactId>
+                                    <groupId>org.eclipse.equinox</groupId>
+                                    <artifactId>org.eclipse.equinox.coordinator</artifactId>
                                     <version>3.8.0-SNAPSHOT</version>
                                     <packaging>jar</packaging>
-                                    <downloadUrl>http://www.eclipse.org/downloads/download.php?file=/equinox/drops/S-3.8M6-201203141800/org.eclipse.osgi_3.8.0.v20120312-2035.jar&amp;url=http://download.eclipse.org/equinox/drops/S-3.8M6-201203141800/org.eclipse.osgi_3.8.0.v20120312-2035.jar&amp;mirror_id=1</downloadUrl>
+                                    <downloadUrl>http://www.eclipse.org/downloads/download.php?file=/equinox/drops/S-3.8M6-201203141800/org.eclipse.equinox.coordinator_1.1.0.v20120219-1616.jar&amp;url=http://download.eclipse.org/equinox/drops/S-3.8M6-201203141800/org.eclipse.equinox.coordinator_1.1.0.v20120219-1616.jar&amp;mirror_id=1</downloadUrl>
                                 </artifactItem>
                                 <artifactItem>
                                     <groupId>org.eclipse.equinox</groupId>
-                                    <artifactId>org.eclipse.equinox.coordinator</artifactId>
+                                    <artifactId>org.eclipse.equinox.event</artifactId>
                                     <version>3.8.0-SNAPSHOT</version>
                                     <packaging>jar</packaging>
-                                    <downloadUrl>http://www.eclipse.org/downloads/download.php?file=/equinox/drops/S-3.8M6-201203141800/org.eclipse.equinox.coordinator_1.1.0.v20120219-1616.jar&amp;url=http://download.eclipse.org/equinox/drops/S-3.8M6-201203141800/org.eclipse.equinox.coordinator_1.1.0.v20120219-1616.jar&amp;mirror_id=1</downloadUrl>
+                                    <downloadUrl>http://www.eclipse.org/downloads/download.php?file=/equinox/drops/S-3.8M5-201201251800/org.eclipse.equinox.event_1.2.100.v20111010-1614.jar&amp;url=http://download.eclipse.org/equinox/drops/S-3.8M5-201201251800/org.eclipse.equinox.event_1.2.100.v20111010-1614.jar&amp;mirror_id=1</downloadUrl>
                                 </artifactItem>
                                 <artifactItem>
                                     <groupId>org.eclipse.equinox</groupId>
@@ -189,18 +189,18 @@
                                     <downloadUrl>http://www.eclipse.org/downloads/download.php?file=/equinox/drops/S-3.8M6-201203141800/org.eclipse.equinox.region_1.1.0.v20120227-1635.jar&amp;url=http://download.eclipse.org/equinox/drops/S-3.8M6-201203141800/org.eclipse.equinox.region_1.1.0.v20120227-1635.jar&amp;mirror_id=1</downloadUrl>
                                 </artifactItem>
                                 <artifactItem>
-                                    <groupId>org.eclipse.osgi</groupId>
-                                    <artifactId>org.eclipse.osgi.services</artifactId>
+                                    <groupId>org.eclipse</groupId>
+                                    <artifactId>org.eclipse.osgi</artifactId>
                                     <version>3.8.0-SNAPSHOT</version>
                                     <packaging>jar</packaging>
-                                    <downloadUrl>http://www.eclipse.org/downloads/download.php?file=/equinox/drops/S-3.8M5-201201251800/org.eclipse.osgi.services_3.3.0.v20111117-1210.jar&amp;url=http://download.eclipse.org/equinox/drops/S-3.8M5-201201251800/org.eclipse.osgi.services_3.3.0.v20111117-1210.jar&amp;mirror_id=1</downloadUrl>
+                                    <downloadUrl>http://www.eclipse.org/downloads/download.php?file=/equinox/drops/S-3.8M6-201203141800/org.eclipse.osgi_3.8.0.v20120312-2035.jar&amp;url=http://download.eclipse.org/equinox/drops/S-3.8M6-201203141800/org.eclipse.osgi_3.8.0.v20120312-2035.jar&amp;mirror_id=1</downloadUrl>
                                 </artifactItem>
                                 <artifactItem>
-                                    <groupId>org.eclipse.equinox</groupId>
-                                    <artifactId>org.eclipse.equinox.event</artifactId>
+                                    <groupId>org.eclipse.osgi</groupId>
+                                    <artifactId>org.eclipse.osgi.services</artifactId>
                                     <version>3.8.0-SNAPSHOT</version>
                                     <packaging>jar</packaging>
-                                    <downloadUrl>http://www.eclipse.org/downloads/download.php?file=/equinox/drops/S-3.8M5-201201251800/org.eclipse.equinox.event_1.2.100.v20111010-1614.jar&amp;url=http://download.eclipse.org/equinox/drops/S-3.8M5-201201251800/org.eclipse.equinox.event_1.2.100.v20111010-1614.jar&amp;mirror_id=1</downloadUrl>
+                                    <downloadUrl>http://www.eclipse.org/downloads/download.php?file=/equinox/drops/S-3.8M5-201201251800/org.eclipse.osgi.services_3.3.0.v20111117-1210.jar&amp;url=http://download.eclipse.org/equinox/drops/S-3.8M5-201201251800/org.eclipse.osgi.services_3.3.0.v20111117-1210.jar&amp;mirror_id=1</downloadUrl>
                                 </artifactItem>
                             </artifactItems>
                         </configuration>

Modified: aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/Repository.java
URL: http://svn.apache.org/viewvc/aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/Repository.java?rev=1328415&r1=1328414&r2=1328415&view=diff
==============================================================================
--- aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/Repository.java (original)
+++ aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/Repository.java Fri Apr 20 15:41:40 2012
@@ -22,7 +22,6 @@ package org.osgi.service.repository;
 
 import java.util.Collection;
 import java.util.Map;
-
 import org.osgi.resource.Capability;
 import org.osgi.resource.Requirement;
 import org.osgi.resource.Resource;
@@ -39,11 +38,16 @@ import org.osgi.resource.Resource;
  * properties.
  * 
  * @ThreadSafe
- * @version $Id: 556d89153e612c5188c74e62004fdcacdd62949e $
+ * @noimplement
+ * @version $Id: 7c1e9f0758f6dc1530645699c62843182c84dc1e $
  */
 public interface Repository {
 	/**
-	 * Service property to provide an optional URL related to this repository
+	 * Service property to provide URLs related to this repository.
+	 * 
+	 * <p>
+	 * The value of this property must be of type {@code String},
+	 * {@code String[]}, or {@code Collection<String>}.
 	 */
 	String	URL	= "repository.url";
 
@@ -59,6 +63,5 @@ public interface Repository {
 	 *         an empty collection. The returned map is the property of the
 	 *         caller and can be modified by the caller.
 	 */
-	Map<Requirement, Collection<Capability>> findProviders(
-			Collection< ? extends Requirement> requirements);
+	Map<Requirement, Collection<Capability>> findProviders(Collection<? extends Requirement> requirements);
 }

Modified: aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/RepositoryContent.java
URL: http://svn.apache.org/viewvc/aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/RepositoryContent.java?rev=1328415&r1=1328414&r2=1328415&view=diff
==============================================================================
--- aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/RepositoryContent.java (original)
+++ aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/RepositoryContent.java Fri Apr 20 15:41:40 2012
@@ -17,7 +17,6 @@
 package org.osgi.service.repository;
 
 import java.io.InputStream;
-
 import org.osgi.resource.Resource;
 
 /**
@@ -29,7 +28,8 @@ import org.osgi.resource.Resource;
  * {@code InputStream} to the default content of the resource.
  * 
  * @ThreadSafe
- * @version $Id: ec32a007f35510827791c7e5af99f3c5d579ce87 $
+ * @noimplement
+ * @version $Id: 65c9ca60467654e7147a2fddc86acef58a634042 $
  */
 public interface RepositoryContent {
 

Modified: aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/package-info.java
URL: http://svn.apache.org/viewvc/aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/package-info.java?rev=1328415&r1=1328414&r2=1328415&view=diff
==============================================================================
--- aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/package-info.java (original)
+++ aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/repository/package-info.java Fri Apr 20 15:41:40 2012
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2010, 2011). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2010, 2012). 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.
@@ -15,7 +15,7 @@
  */
 
 /**
- * Repository Package Version 1.0.
+ * Repository Service Package Version 1.0.
  * 
  * <p>
  * Bundles wishing to use this package must list the package in the
@@ -32,7 +32,8 @@
  * <p>
  * {@code  Import-Package: org.osgi.service.repository; version="[1.0,1.1)"}
  * 
- * @version $Id: 124471567e9a3f769ead5e9a593cf8581f307a02 $
+ * @version $Id: 2f90fa85cba8d54a6431ff843f2dac5eb7beb7dc $
  */
 
 package org.osgi.service.repository;
+

Modified: aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/HostedCapability.java
URL: http://svn.apache.org/viewvc/aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/HostedCapability.java?rev=1328415&r1=1328414&r2=1328415&view=diff
==============================================================================
--- aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/HostedCapability.java (original)
+++ aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/HostedCapability.java Fri Apr 20 15:41:40 2012
@@ -25,15 +25,15 @@ import org.osgi.resource.Resource;
  * <p>
  * A HostedCapability is a Capability where the {@link #getResource()} method
  * returns a Resource that hosts this Capability instead of declaring it. This
- * is necessary for cases where the declared Resource of a Capability does not
+ * is necessary for cases where the declaring Resource of a Capability does not
  * match the runtime state. For example, this is the case for fragments attached
- * to a host. Most of the fragments declared capabilities and requirements
- * become hosted by the host resource. Since a fragment can attach to multiple
- * hosts, a single capability can actually be hosted multiple times.
+ * to a host. Most fragment declared capabilities and requirements become hosted
+ * by the host resource. Since a fragment can attach to multiple hosts, a single
+ * capability can actually be hosted multiple times.
  * 
- * @Threadsafe
+ * @ThreadSafe
  * @noimplement
- * @version $Id: 01fa0dde20b8999c01ad2e6c01f36ce45f8ee7af $
+ * @version $Id: db698baa07e2ee8b5467871239adb5f0806dc183 $
  */
 public interface HostedCapability extends Capability {
 

Modified: aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/ResolutionException.java
URL: http://svn.apache.org/viewvc/aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/ResolutionException.java?rev=1328415&r1=1328414&r2=1328415&view=diff
==============================================================================
--- aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/ResolutionException.java (original)
+++ aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/ResolutionException.java Fri Apr 20 15:41:40 2012
@@ -19,7 +19,6 @@ package org.osgi.service.resolver;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
-
 import org.osgi.resource.Requirement;
 
 /**
@@ -35,7 +34,7 @@ import org.osgi.resource.Requirement;
  * Resolver implementations may extend this class to provide extra state
  * information about the reason for the resolution failure.
  * 
- * @version $Id: 6cbd1a0da0f9c464570bfb370ef8dca07470202e $
+ * @version $Id: 42e5773e3b7e240673874329e5d9e705d0b698c5 $
  */
 public class ResolutionException extends Exception {
 
@@ -53,17 +52,12 @@ public class ResolutionException extends
 	 *        mandatory resources or {@code null} if no unresolved requirements
 	 *        information is provided.
 	 */
-	public ResolutionException(String message, Throwable cause,
-			Collection<Requirement> unresolvedRequirements) {
+	public ResolutionException(String message, Throwable cause, Collection<Requirement> unresolvedRequirements) {
 		super(message, cause);
-		if ((unresolvedRequirements == null)
-				|| unresolvedRequirements.isEmpty()) {
+		if ((unresolvedRequirements == null) || unresolvedRequirements.isEmpty()) {
 			this.unresolvedRequirements = emptyCollection();
-		}
-		else {
-			this.unresolvedRequirements = Collections
-					.unmodifiableCollection(new ArrayList<Requirement>(
-							unresolvedRequirements));
+		} else {
+			this.unresolvedRequirements = Collections.unmodifiableCollection(new ArrayList<Requirement>(unresolvedRequirements));
 		}
 	}
 

Modified: aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/ResolveContext.java
URL: http://svn.apache.org/viewvc/aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/ResolveContext.java?rev=1328415&r1=1328414&r2=1328415&view=diff
==============================================================================
--- aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/ResolveContext.java (original)
+++ aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/ResolveContext.java Fri Apr 20 15:41:40 2012
@@ -20,11 +20,9 @@ import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
-
 import org.osgi.resource.Capability;
 import org.osgi.resource.Requirement;
 import org.osgi.resource.Resource;
-import org.osgi.resource.Wire;
 import org.osgi.resource.Wiring;
 
 /**
@@ -37,22 +35,18 @@ import org.osgi.resource.Wiring;
  * <ul>
  * <li>Specify the mandatory and optional resources to resolve. The mandatory
  * and optional resources must be consistent and correct. For example, they must
- * not violate singleton policy of the caller.</li>
+ * not violate the singleton policy of the implementer.</li>
  * <li>Provide {@link Capability capabilities} that the Resolver can use to
  * satisfy {@link Requirement requirements} via the
  * {@link #findProviders(Requirement)} method</li>
  * <li>Constrain solutions via the {@link #getWirings()} method. A wiring
- * consists of a map of existing {@link Resource resources} to {@link Wire
- * wires}.</li>
- * <li>Filter transitive requirements that are brought in as part of a resolve
- * operation via the {@link #isEffective(Requirement)}.</li>
+ * consists of a map of existing {@link Resource resources} to {@link Wiring
+ * wiring}.</li>
+ * <li>Filter requirements that are part of a resolve operation via the
+ * {@link #isEffective(Requirement)}.</li>
  * </ul>
  * 
  * <p>
- * A resolve context may be used to provide capabilities via local
- * {@link Resource resources} and/or remote repositories.
- * 
- * <p>
  * A resolver may call the methods on the resolve context any number of times
  * during a resolve operation using any thread. Implementors should ensure that
  * this class is properly thread safe.
@@ -64,7 +58,7 @@ import org.osgi.resource.Wiring;
  * return a consistent set of capabilities, wires and effective requirements.
  * 
  * @ThreadSafe
- * @version $Id: 08c822c21a46fbcdf01852b8206eb05d1c566bf1 $
+ * @version $Id: f92eae32ab6fadb25e13d226458d6af50e8dcbba $
  */
 public abstract class ResolveContext {
 	/**
@@ -153,8 +147,7 @@ public abstract class ResolveContext {
 	 * @return The index in the list of the inserted HostedCapability.
 	 * 
 	 */
-	public abstract int insertHostedCapability(List<Capability> capabilities,
-			HostedCapability hostedCapability);
+	public abstract int insertHostedCapability(List<Capability> capabilities, HostedCapability hostedCapability);
 
 	/**
 	 * Test if a given requirement should be wired in the resolve operation. If
@@ -173,13 +166,19 @@ public abstract class ResolveContext {
 	public abstract boolean isEffective(Requirement requirement);
 
 	/**
-	 * Returns an unmodifiable map of existing wirings for resources.
+	 * Returns the wirings for existing resolved resources.
+	 * 
+	 * <p>
+	 * For example, if this resolve context is for an OSGi framework, then the
+	 * result would contain all the currently resolved bundles with each
+	 * bundle's current wiring.
 	 * 
 	 * <p>
 	 * Multiple calls to this method for this resolve context must return the
 	 * same result.
 	 * 
-	 * @return The existing wirings in this resolve context.
+	 * @return The wirings for existing resolved resources. The returned map is
+	 *         unmodifiable.
 	 */
 	public abstract Map<Resource, Wiring> getWirings();
 }

Modified: aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/Resolver.java
URL: http://svn.apache.org/viewvc/aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/Resolver.java?rev=1328415&r1=1328414&r2=1328415&view=diff
==============================================================================
--- aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/Resolver.java (original)
+++ aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/Resolver.java Fri Apr 20 15:41:40 2012
@@ -22,7 +22,6 @@ package org.osgi.service.resolver;
 
 import java.util.List;
 import java.util.Map;
-
 import org.osgi.resource.Resource;
 import org.osgi.resource.Wire;
 
@@ -32,7 +31,7 @@ import org.osgi.resource.Wire;
  * 
  * @ThreadSafe
  * @noimplement
- * @version $Id: 871a5f8f97eba146fc1b8657e84a41b571533fbb $
+ * @version $Id: dfb89b8d09af62ecf62321b80d7e2310512f27a1 $
  */
 public interface Resolver {
 	/**
@@ -69,6 +68,5 @@ public interface Resolver {
 	 *         and can be modified by the caller.
 	 * @throws ResolutionException If the resolution cannot be satisfied.
 	 */
-	Map<Resource, List<Wire>> resolve(ResolveContext context)
-			throws ResolutionException;
+	Map<Resource, List<Wire>> resolve(ResolveContext context) throws ResolutionException;
 }

Modified: aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/package-info.java
URL: http://svn.apache.org/viewvc/aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/package-info.java?rev=1328415&r1=1328414&r2=1328415&view=diff
==============================================================================
--- aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/package-info.java (original)
+++ aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/resolver/package-info.java Fri Apr 20 15:41:40 2012
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2010, 2011). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2010, 2012). 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.
@@ -15,7 +15,7 @@
  */
 
 /**
- * Resolver Package Version 1.0.
+ * Resolver Service Package Version 1.0.
  * 
  * <p>
  * Bundles wishing to use this package must list the package in the
@@ -32,7 +32,8 @@
  * <p>
  * {@code  Import-Package: org.osgi.service.resolver; version="[1.0,1.1)"}
  * 
- * @version $Id: d59eb041c07b894a395e45b82a24f058aadbec32 $
+ * @version $Id: db1706d83ca104187f77cb1feb7cf52b92b3740d $
  */
 
 package org.osgi.service.resolver;
+

Modified: aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/subsystem/Subsystem.java
URL: http://svn.apache.org/viewvc/aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/subsystem/Subsystem.java?rev=1328415&r1=1328414&r2=1328415&view=diff
==============================================================================
--- aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/subsystem/Subsystem.java (original)
+++ aries/trunk/subsystem/subsystem-api/src/main/java/org/osgi/service/subsystem/Subsystem.java Fri Apr 20 15:41:40 2012
@@ -13,26 +13,26 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.osgi.service.subsystem;
 
 import java.io.InputStream;
 import java.util.Collection;
 import java.util.Locale;
 import java.util.Map;
-
 import org.osgi.framework.BundleContext;
 import org.osgi.framework.Version;
-import org.osgi.framework.hooks.resolver.ResolverHook;
 import org.osgi.framework.namespace.IdentityNamespace;
 import org.osgi.resource.Resource;
 
 /**
  * A subsystem is a collection of resources constituting a logical, possibly
  * isolated, unit of functionality.
- * <p/>
- * A subsystem may be scoped or unscoped. Scoped subsystems are isolated by
- * implicit or explicit sharing policies. Unscoped subsystems are not isolated
- * and, therefore, have no sharing policy. There are three standard
+ * 
+ * <p>
+ * A subsystem may be <i>scoped</i> or <i>unscoped</i>. Scoped subsystems are
+ * isolated by implicit or explicit sharing policies. Unscoped subsystems are
+ * not isolated and, therefore, have no sharing policy. There are three standard
  * {@link SubsystemConstants#SUBSYSTEM_TYPE types} of subsystems.
  * <ul>
  * <li>{@link SubsystemConstants#SUBSYSTEM_TYPE_APPLICATION Application} - An
@@ -52,15 +52,19 @@ import org.osgi.resource.Resource;
  * region is a bundle whose context may be {@link #getBundleContext() retrieved}
  * from any subsystem within that region. This context may be used to monitor
  * activity occurring within the region.
- * <p/>
+ * 
+ * <p>
  * A subsystem may have {@link #getChildren() children} and, unless it's the
  * root subsystem, must have at least one {@link #getParents() parent}.
  * Subsystems become children of the subsystem in which they are installed.
  * Unscoped subsystems have more than one parent if they are installed in more
  * than one subsystem within the same region. The subsystem graph may be thought
- * of as is an acyclic digraph with one and only one source vertex, which is the
- * root subsystem. The edges have the child as the head and parent as the tail.
- * <p/>
+ * of as an <a
+ * href="http://en.wikipedia.org/wiki/Directed_acyclic_graph">acyclic
+ * digraph</a> with one and only one source vertex, which is the root subsystem.
+ * The edges have the child as the head and parent as the tail.
+ * 
+ * <p>
  * A subsystem has several identifiers.
  * <ul>
  * <li>{@link #getLocation() Location} - An identifier specified by the client
@@ -78,48 +82,15 @@ import org.osgi.resource.Resource;
  * A subsystem has a well-defined {@link State life cycle}. Which stage a
  * subsystem is in may be obtained from the subsystem's {@link #getState()
  * state} and is dependent on which life cycle operation is currently active or
- * was last invoked. The following table summarizes the relationship between
- * life cycle operations and states.
- * <p/>
- * <table border="1">
- * <tr align="center">
- * <th>Operation</th>
- * <th>From State</th>
- * <th>To State</th>
- * </tr>
- * <tr align="center">
- * <td>{@link #install(String, InputStream) Install}</td>
- * <td></td>
- * <td>{@link State#INSTALLING INSTALLING}, {@link State#INSTALL_FAILED
- * INSTALL_FAILED}, {@link State#INSTALLED INSTALLED}</td>
- * </tr>
- * <tr align="center">
- * <td>{@link #start() Start}</td>
- * <td>{@link State#INSTALLED INSTALLED}, {@link State#RESOLVED RESOLVED}</td>
- * <td>{@link State#INSTALLED INSTALLED}, {@link State#RESOLVING RESOLVING},
- * {@link State#RESOLVED RESOLVED}, {@link State#STARTING STARTING},
- * {@link State#ACTIVE ACTIVE}</td>
- * </tr>
- * <tr align="center">
- * <td>{@link #stop() Stop}</td>
- * <td>{@link State#ACTIVE ACTIVE}</td>
- * <td>{@link State#RESOLVED RESOLVED}, {@link State#STOPPING STOPPING}</td>
- * </tr>
- * <tr align="center">
- * <td>{@link #uninstall() Uninstall}</td>
- * <td>{@link State#INSTALLED INSTALLED}, {@link State#RESOLVED RESOLVED},
- * {@link State#ACTIVE ACTIVE}</td>
- * <td>{@link State#UNINSTALLING UNINSTALLING}, {@link State#UNINSTALLED
- * UNINSTALLED}</td>
- * </tr>
- * </table>
- * <p/>
- * A subsystem archive is a ZIP file having an ESA extension and containing
- * metadata describing the subsystem. The form of the metadata may be a
- * subsystem or deployment manifest, as well as any content resource files. The
- * manifests are optional and will be computed if not present. The subsystem
+ * was last invoked.
+ * 
+ * <p>
+ * A subsystem archive is a ZIP file having an {@code .esa} extension and
+ * containing metadata describing the subsystem. The form of the metadata may be
+ * a subsystem or deployment manifest, as well as any content resource files.
+ * The manifests are optional and will be computed if not present. The subsystem
  * manifest headers may be {@link #getSubsystemHeaders(Locale) retrieved} in raw
- * or localized formats. There are five standard
+ * or localized forms. There are five standard
  * {@link IdentityNamespace#CAPABILITY_TYPE_ATTRIBUTE types} of resources that
  * may be included in a subsystem.
  * <ul>
@@ -127,290 +98,300 @@ import org.osgi.resource.Resource;
  * fragment.</li>
  * <li>{@link IdentityNamespace#TYPE_FRAGMENT Fragment} - A fragment bundle.</li>
  * <li>{@link SubsystemConstants#SUBSYSTEM_TYPE_APPLICATION Application
- * Subsystem} - An application subsystem defined by this specification.</li>
+ * Subsystem} - An application subsystem.</li>
  * <li>{@link SubsystemConstants#SUBSYSTEM_TYPE_COMPOSITE Composite Subsystem} -
- * A composite subsystem defined by this specification.</li>
+ * A composite subsystem.</li>
  * <li>{@link SubsystemConstants#SUBSYSTEM_TYPE_FEATURE Feature Subsystem} - A
- * feature subsystem defined by this specification.</li>
+ * feature subsystem.</li>
  * </ul>
  * Resources contained by a subsystem are called {@link #getConstituents()
  * constituents}. There are several ways a resource may become a constituent of
- * a subsystem, at least some of which are listed below.
- * <p/>
+ * a subsystem:
  * <ul>
- * <li>A resource was listed as part of the subsystem's content.</li>
+ * <li>A resource is listed as part of the subsystem's content.</li>
  * <li>A subsystem resource is a child of the subsystem.</li>
  * <li>The subsystem has a provision policy of accept dependencies.</li>
- * <li>A bundle resource was installed using the region bundle context.</li>
- * <li>A bundle resource was installed using the bundle context of another
+ * <li>A bundle resource is installed using the region bundle context.</li>
+ * <li>A bundle resource is installed using the bundle context of another
  * resource contained by the subsystem.</li>
  * </ul>
+ * 
+ * <p>
  * In addition to invoking one of the install methods, a subsystem instance may
- * be obtained through the service registry. Every installed subsystem has a
+ * be obtained through the service registry. Each installed subsystem has a
  * corresponding service registration. A subsystem service has the following
  * properties.
- * <p/>
+ * 
  * <ul>
- * <li>{@link SubsystemConstants#SUBSYSTEM_ID_PROPERTY ID} - Matches the ID of
- * the subsystem.</li>
+ * <li>{@link SubsystemConstants#SUBSYSTEM_ID_PROPERTY ID} - The ID of the
+ * subsystem.</li>
  * <li>{@link SubsystemConstants#SUBSYSTEM_SYMBOLICNAME_PROPERTY Symbolic Name}
- * - Matches the symbolic name of the subsystem.</li>
- * <li>{@link SubsystemConstants#SUBSYSTEM_VERSION_PROPERTY Version} - Matches
- * the version of the subsystem.</li>
- * <li>{@link SubsystemConstants#SUBSYSTEM_TYPE_PROPERTY Type} - Matches the
- * type of the subsystem.</li>
- * <li>{@link SubsystemConstants#SUBSYSTEM_STATE_PROPERTY State} - Matches the
- * state of the subsystem.</li>
+ * - The symbolic name of the subsystem.</li>
+ * <li>{@link SubsystemConstants#SUBSYSTEM_VERSION_PROPERTY Version} - The
+ * version of the subsystem.</li>
+ * <li>{@link SubsystemConstants#SUBSYSTEM_TYPE_PROPERTY Type} - The type of the
+ * subsystem.</li>
+ * <li>{@link SubsystemConstants#SUBSYSTEM_STATE_PROPERTY State} - The state of
+ * the subsystem.</li>
  * </ul>
+ * 
+ * <p>
  * Because a subsystem must be used to install other subsystems, a root
- * subsystem is provided as a starting point and has the following
- * characteristics. The root subsystem may only be obtained as a service.
- * <p/>
+ * subsystem is provided as a starting point. The root subsystem may only be
+ * obtained as a service and has the following characteristics.
+ * 
  * <ul>
  * <li>The ID is {@code 0}.</li>
- * <li>The symbolic name is {@code org.osgi.service.subsystem.root}.</li>
+ * <li>The symbolic name is
+ * {@link SubsystemConstants#ROOT_SUBSYSTEM_SYMBOLICNAME
+ * org.osgi.service.subsystem.root}.</li>
  * <li>The version matches this specification's version.</li>
  * <li>It has no parents.</li>
- * <li>All existing bundles, including the system and subsystems implementation
- * bundles, become constituents.</li>
- * <li>The type is {@code osgi.subsystem.application} with no imports.</li>
- * <li>The provision policy is {@code acceptDependencies}.</li>
+ * <li>All existing bundles, including the system and subsystem implementation
+ * bundles, are constituents.</li>
+ * <li>The type is {@link SubsystemConstants#SUBSYSTEM_TYPE_APPLICATION
+ * osgi.subsystem.application} with no imports.</li>
+ * <li>The provision policy is
+ * {@link SubsystemConstants#PROVISION_POLICY_ACCEPT_DEPENDENCIES
+ * acceptDependencies}.</li>
  * </ul>
  * 
  * @ThreadSafe
  * @noimplement
+ * @version $Id: 73028a6997272cbac7e90ae00eb0f28afd14c8ee $
  */
 public interface Subsystem {
 	/**
 	 * An enumeration of the possible states of a subsystem.
-	 * <p/>
+	 * 
+	 * <p>
 	 * These states are a reflection of what constituent resources are permitted
-	 * to do, not an aggregation of resource states. 
+	 * to do and not an aggregation of constituent resource states.
 	 */
 	public static enum State {
 		/**
 		 * The subsystem is in the process of installing.
-		 * <p/>
-		 * A subsystem is in the INSTALLING state when the {@link Subsystem#
-		 * install(String, InputStream) install} method of its parent is active,
-		 * and attempts are being made to install its content resources. If the
-		 * install method completes without exception, then the subsystem has
-		 * successfully installed and must move to the INSTALLED state.
-		 * Otherwise, the subsystem has failed to install and must move to the
-		 * INSTALL_FAILED state.
+		 * <p>
+		 * A subsystem is in the {@code INSTALLING} state when the
+		 * {@link Subsystem#install(String, InputStream) install} method of its
+		 * parent is active, and attempts are being made to install its content
+		 * resources. If the install method completes without exception, then
+		 * the subsystem has successfully installed and must move to the
+		 * {@link #INSTALLED} state. Otherwise, the subsystem has failed to
+		 * install and must move to the {@link #INSTALL_FAILED} state.
 		 */
 		INSTALLING,
 		/**
 		 * The subsystem is installed but not yet resolved.
-		 * <p/>
-		 * A subsystem is in the INSTALLED state when it has been installed in
-		 * a parent subsystem but is not or cannot be resolved. This state is
-		 * visible if the dependencies of the subsystem's content resources
-		 * cannot be resolved.
+		 * <p>
+		 * A subsystem is in the {@code INSTALLED} state when it has been
+		 * installed in a parent subsystem but is not or cannot be resolved.
+		 * This state is visible if the dependencies of the subsystem's content
+		 * resources cannot be resolved.
 		 */
 		INSTALLED,
 		/**
 		 * The subsystem failed to install.
-		 * <p/>
-		 * A subsystem is in the INSTALL_FAILED state when an unrecoverable
-		 * error occurred during installation. The subsystem is in an unusable
-		 * state but references to the subsystem object may still be available
-		 * and used for introspection.
+		 * <p>
+		 * A subsystem is in the {@code INSTALL_FAILED} state when an
+		 * unrecoverable error occurred during installation. The subsystem is in
+		 * an unusable state but references to the subsystem object may still be
+		 * available and used for introspection.
 		 */
 		INSTALL_FAILED,
 		/**
 		 * The subsystem is in the process of resolving.
-		 * <p/>
-		 * A subsystem is in the RESOLVING state when the {@link Subsystem#
-		 * start() start} method is active, and attempts are being made to
-		 * resolve its content resources. If the resolve method completes
-		 * without exception, then the subsystem has successfully resolved and
-		 * must move to the RESOLVED state. Otherwise, the subsystem has failed
-		 * to resolve and must move to the INSTALLED state.
+		 * <p>
+		 * A subsystem is in the {@code RESOLVING} state when the
+		 * {@link Subsystem#start() start} method is active, and attempts are
+		 * being made to resolve its content resources. If the resolve method
+		 * completes without exception, then the subsystem has successfully
+		 * resolved and must move to the {@link #RESOLVED} state. Otherwise, the
+		 * subsystem has failed to resolve and must move to the INSTALLED state.
 		 */
 		RESOLVING,
 		/**
 		 * The subsystem is resolved and able to be started.
-		 * <p/>
-		 * A subsystem is in the RESOLVED state when all of its content
+		 * <p>
+		 * A subsystem is in the {@code RESOLVED} state when all of its content
 		 * resources are resolved. Note that the subsystem is not active yet.
 		 */
 		RESOLVED,
 		/**
 		 * The subsystem is in the process of starting.
-		 * <p/>
-		 * A subsystem is in the STARTING state when its {@link Subsystem#
-		 * start() start} method is active, and attempts are being made to start
-		 * its content and dependencies. If the start method completes
-		 * without exception, then the subsystem has successfully started and
-		 * must move to the ACTIVE state. Otherwise, the subsystem has failed to
-		 * start and must move to the RESOLVED state.
+		 * <p>
+		 * A subsystem is in the {@code STARTING} state when its
+		 * {@link Subsystem#start() start} method is active, and attempts are
+		 * being made to start its content and dependencies. If the start method
+		 * completes without exception, then the subsystem has successfully
+		 * started and must move to the {@link #ACTIVE} state. Otherwise, the
+		 * subsystem has failed to start and must move to the {@link #RESOLVED}
+		 * state.
 		 */
 		STARTING,
 		/**
 		 * The subsystem is now running.
-		 * <p/>
-		 * A subsystem is in the ACTIVE state when its content and dependencies
-		 * have been successfully started and activated.
+		 * <p>
+		 * A subsystem is in the {@code ACTIVE} state when its content and
+		 * dependencies have been successfully started.
 		 */
 		ACTIVE,
 		/**
 		 * The subsystem is in the process of stopping.
-		 * <p/>
-		 * A subsystem is in the STOPPING state when its {@link Subsystem#stop()
-		 * stop} method is active, and attempts are being made to stop its
-		 * content and dependencies. When the stop method completes, the
-		 * subsystem is stopped and must move to the RESOLVED state.
+		 * <p>
+		 * A subsystem is in the {@code STOPPING} state when its
+		 * {@link Subsystem#stop() stop} method is active, and attempts are
+		 * being made to stop its content and dependencies. When the stop method
+		 * completes, the subsystem is stopped and must move to the
+		 * {@link #RESOLVED} state.
 		 */
 		STOPPING,
 		/**
 		 * The subsystem is in the process of uninstalling.
-		 * <p/>
-		 * A subsystem is in the UNINSTALLING state when its {@link Subsystem#
-		 * uninstall() uninstall} method is active, and attempts are being made
-		 * to uninstall its constituent and dependencies. When the
-		 * uninstall method completes, the subsystem is uninstalled and must
-		 * move to the UNINSTALLED state.
+		 * <p>
+		 * A subsystem is in the {@code UNINSTALLING} state when its
+		 * {@link Subsystem#uninstall() uninstall} method is active, and
+		 * attempts are being made to uninstall its constituent and
+		 * dependencies. When the uninstall method completes, the subsystem is
+		 * uninstalled and must move to the {@link #UNINSTALLED} state.
 		 */
 		UNINSTALLING,
 		/**
 		 * The subsystem is uninstalled and may not be used.
-		 * <p/>
-		 * The UNINSTALLED state is only visible after a subsystem's constituent
-		 * and dependencies are uninstalled. The subsystem is in an
+		 * <p>
+		 * The {@code UNINSTALLED} state is only visible after a subsystem's
+		 * constituent and dependencies are uninstalled. The subsystem is in an
 		 * unusable state but references to the subsystem object may still be
 		 * available and used for introspection.
 		 */
 		UNINSTALLED
 	}
-	
+
 	/**
 	 * Returns the bundle context of the region within which this subsystem
 	 * resides.
-	 * <p/>
+	 * <p>
 	 * The bundle context offers the same perspective of any resource contained
 	 * by a subsystem within the region. It may be used, for example, to monitor
 	 * events internal to the region as well as external events visible to the
 	 * region. All subsystems within the same region have the same bundle
 	 * context. If this subsystem is in a state where the bundle context would
-	 * be invalid, null is returned.
+	 * be invalid, {@code null} is returned.
 	 * 
 	 * @return The bundle context of the region within which this subsystem
-	 *         resides or null if this subsystem's state is in {{@link
-	 *         State#INSTALL_FAILED INSTALL_FAILED}, {@link State#UNINSTALLED
-	 *         UNINSTALLED}}.
-	 * @throws SecurityException If the caller does not have the appropriate 
+	 *         resides or {@code null} if this subsystem's state is in
+	 *         {@link State#INSTALL_FAILED INSTALL_FAILED},
+	 *         {@link State#UNINSTALLED UNINSTALLED}.
+	 * @throws SecurityException If the caller does not have the appropriate
 	 *         {@link SubsystemPermission}[this,CONTEXT], and the runtime
 	 *         supports permissions.
 	 */
 	public BundleContext getBundleContext();
-	
+
 	/**
 	 * Returns the child subsystems of this subsystem.
-	 * <p/>
-	 * The returned collection is an immutable snapshot of all subsystems that
-	 * are installed in this subsystem. The collection will be empty if no
-	 * subsystems are installed in this subsystem.
 	 * 
-	 * @return The child subsystems of this subsystem.
+	 * @return The child subsystems of this subsystem. The returned collection
+	 *         is an unmodifiable snapshot of all subsystems that are installed
+	 *         in this subsystem. The collection will be empty if no subsystems
+	 *         are installed in this subsystem.
 	 * @throws IllegalStateException If this subsystem's state is in
-	 *         {{@link State#INSTALL_FAILED INSTALL_FAILED}, {@link
-	 *         State#UNINSTALLED UNINSTALLED}}.
+	 *         {@link State#INSTALL_FAILED INSTALL_FAILED},
+	 *         {@link State#UNINSTALLED UNINSTALLED}.
 	 */
 	public Collection<Subsystem> getChildren();
-	
+
 	/**
 	 * Returns the headers for this subsystem's subsystem manifest.
-	 * <p/>
-	 * The returned map is unmodifiable. Each map key is a header name, and each
-	 * map value is the corresponding header value. Because header names are
-	 * case-insensitive, the methods of the map must treat them in a
-	 * case-insensitive manner. If the header name is not found, null is
-	 * returned. Both original and derived headers will be included.
-	 * <p/>
-	 * The header values are translated according to the specified locale. If
-	 * the specified locale is null or not supported, the raw values are
-	 * returned. If the translation for a particular header is not found, the
-	 * raw value is returned.
-	 * <p/>
+	 * <p>
+	 * Each key in the map is a header name and the value of the key is the
+	 * corresponding header value. Because header names are case-insensitive,
+	 * the methods of the map must treat the keys in a case-insensitive manner.
+	 * If the header name is not found, {@code null} is returned. Both original
+	 * and derived headers will be included in the map.
+	 * <p>
 	 * This method must continue to return the headers while this subsystem is
-	 * in the {@link State#INSTALL_FAILED INSTALL_FAILED} or {@link
-	 * State#UNINSTALLED UNINSTALLED} states.
+	 * in the {@link State#INSTALL_FAILED INSTALL_FAILED} or
+	 * {@link State#UNINSTALLED UNINSTALLED} states.
 	 * 
-	 * @param locale The locale for which translations are desired.
-	 * @return The headers for this subsystem's subsystem manifest.
-	 * @throws SecurityException If the caller does not have the appropriate 
+	 * @param locale The locale for which translations are desired. The header
+	 *        values are translated according to the specified locale. If the
+	 *        specified locale is {@code null} or not supported, the raw values
+	 *        are returned. If the translation for a particular header is not
+	 *        found, the raw value is returned.
+	 * @return The headers for this subsystem's subsystem manifest. The returned
+	 *         map is unmodifiable.
+	 * @throws SecurityException If the caller does not have the appropriate
 	 *         {@link SubsystemPermission}[this,METADATA], and the runtime
 	 *         supports permissions.
 	 */
 	public Map<String, String> getSubsystemHeaders(Locale locale);
-	
+
 	/**
 	 * Returns the location identifier of this subsystem.
-	 * <p/>
+	 * <p>
 	 * The location identifier is the {@code location} that was passed to the
-	 * {@link #install(String, InputStream) install} method of the {@link
-	 * #getParents() parent} subsystem. It is unique within the framework.
-	 * <p/>
+	 * {@link #install(String, InputStream) install} method of the
+	 * {@link #getParents() parent} subsystem. It is unique within the
+	 * framework.
+	 * <p>
 	 * This method must continue to return this subsystem's headers while this
-	 * subsystem is in the {@link State#INSTALL_FAILED INSTALL_FAILED} or {@link
-	 * State#UNINSTALLED UNINSTALLED} states.
+	 * subsystem is in the {@link State#INSTALL_FAILED INSTALL_FAILED} or
+	 * {@link State#UNINSTALLED UNINSTALLED} states.
 	 * 
 	 * @return The location identifier of this subsystem.
-	 * @throws SecurityException If the caller does not have the appropriate 
+	 * @throws SecurityException If the caller does not have the appropriate
 	 *         {@link SubsystemPermission}[this,METADATA], and the runtime
 	 *         supports permissions.
 	 */
 	public String getLocation();
-	
+
 	/**
 	 * Returns the parent subsystems of this subsystem.
-	 * <p/>
-	 * The returned collection is an immutable snapshot of all subsystems in
-	 * which this subsystem is installed. The collection will be empty for the
-	 * root subsystem; otherwise, it will contain at least one parent. Scoped
-	 * subsystems always have only one parent. Unscoped subsystems may have
-	 * multiple parents.
-	 * 
-	 * @return The parent subsystems of this subsystem.
-	 * @throws IllegalStateException If this subsystem's state is in {{@link
-	 *         State#INSTALL_FAILED INSTALL_FAILED}, {@link State#UNINSTALLED
-	 *         UNINSTALLED}}.
+	 * 
+	 * @return The parent subsystems of this subsystem. The returned collection
+	 *         is an unmodifiable snapshot of all subsystems in which this
+	 *         subsystem is installed. The collection will be empty for the root
+	 *         subsystem; otherwise, it must contain at least one parent. Scoped
+	 *         subsystems always have only one parent. Unscoped subsystems may
+	 *         have multiple parents.
+	 * @throws IllegalStateException If this subsystem's state is in
+	 *         {@link State#INSTALL_FAILED INSTALL_FAILED},
+	 *         {@link State#UNINSTALLED UNINSTALLED}.
 	 */
 	public Collection<Subsystem> getParents();
-	
+
 	/**
 	 * Returns the constituent resources of this subsystem.
-	 * <p/>
-	 * The returned collection is an immutable snapshot of the constituent
-	 * resources of this subsystem. If this subsystem has no constituents,
-	 * the collection will be empty.
-	 * 
-	 * @return The constituent resources of this subsystem.
-	 * @throws IllegalStateException If this subsystem's state is in {{@link
-	 *         State#INSTALL_FAILED INSTALL_FAILED}, {@link State#UNINSTALLED
-	 *         UNINSTALLED}}.
+	 * 
+	 * @return The constituent resources of this subsystem. The returned
+	 *         collection is an unmodifiable snapshot of the constituent
+	 *         resources of this subsystem. If this subsystem has no
+	 *         constituents, the collection will be empty.
+	 * @throws IllegalStateException If this subsystem's state is in
+	 *         {@link State#INSTALL_FAILED INSTALL_FAILED},
+	 *         {@link State#UNINSTALLED UNINSTALLED}.
 	 */
 	public Collection<Resource> getConstituents();
-	
+
 	/**
 	 * Returns the current state of this subsystem.
-	 * <p/>
+	 * <p>
 	 * This method must continue to return this subsystem's state while this
-	 * subsystem is in the {@link State#INSTALL_FAILED INSTALL_FAILED} or {@link
-	 * State#UNINSTALLED UNINSTALLED} states.
+	 * subsystem is in the {@link State#INSTALL_FAILED INSTALL_FAILED} or
+	 * {@link State#UNINSTALLED UNINSTALLED} states.
 	 * 
 	 * @return The current state of this subsystem.
 	 */
 	public State getState();
-	
+
 	/**
 	 * Returns the identifier of this subsystem.
-	 * <p/>
+	 * <p>
 	 * The identifier is a monotonically increasing, non-negative integer
 	 * automatically generated at installation time and guaranteed to be unique
 	 * within the framework. The identifier of the root subsystem is zero.
-	 * <p/>
+	 * <p>
 	 * This method must continue to return this subsystem's identifier while
 	 * this subsystem is in the {@link State#INSTALL_FAILED INSTALL_FAILED} or
 	 * {@link State#UNINSTALLED UNINSTALLED} states.
@@ -418,27 +399,25 @@ public interface Subsystem {
 	 * @return The identifier of this subsystem.
 	 */
 	public long getSubsystemId();
-	
+
 	/**
 	 * Returns the symbolic name of this subsystem.
-	 * <p/>
+	 * <p>
 	 * The subsystem symbolic name conforms to the same grammar rules as the
 	 * bundle symbolic name and is derived from one of the following, in order.
 	 * <ul>
-	 * 		<li>The value of the {@link SubsystemConstants#SUBSYSTEM_SYMBOLICNAME
-	 *          Subsystem-SymbolicName} header, if specified.
-	 * 		</li>
-	 * 		<li>The subsystem URI if passed as the {@code location} along with
-	 *          the {@code content} to the {@link #install(String, InputStream)
-	 *          install} method.
-	 *      </li>
-	 * 		<li>Optionally generated in an implementation specific way.
-	 * 		</li>
+	 * <li>The value of the {@link SubsystemConstants#SUBSYSTEM_SYMBOLICNAME
+	 * Subsystem-SymbolicName} header, if specified.</li>
+	 * <li>The subsystem URI if passed as the {@code location} along with the
+	 * {@code content} to the {@link #install(String, InputStream) install}
+	 * method.</li>
+	 * <li>Optionally generated in an implementation specific way.</li>
 	 * </ul>
-	 * The combination of symbolic name and {@link #getVersion() version} is
-	 * unique within a region. The symbolic name of the root subsystem is {@code
+	 * The combination of subsystem symbolic name and {@link #getVersion()
+	 * version} is unique within a region. The symbolic name of the root
+	 * subsystem is {@link SubsystemConstants#ROOT_SUBSYSTEM_SYMBOLICNAME
 	 * org.osgi.service.subsystem.root}.
-	 * <p/>
+	 * <p>
 	 * This method must continue to return this subsystem's symbolic name while
 	 * this subsystem is in the {@link State#INSTALL_FAILED INSTALL_FAILED} or
 	 * {@link State#UNINSTALLED UNINSTALLED} states.
@@ -446,11 +425,11 @@ public interface Subsystem {
 	 * @return The symbolic name of this subsystem.
 	 */
 	public String getSymbolicName();
-	
+
 	/**
 	 * Returns the {@link SubsystemConstants#SUBSYSTEM_TYPE type} of this
 	 * subsystem.
-	 * <p/>
+	 * <p>
 	 * This method must continue to return this subsystem's type while this
 	 * subsystem is in the {@link State#INSTALL_FAILED INSTALL_FAILED} or
 	 * {@link State#UNINSTALLED UNINSTALLED} states.
@@ -458,473 +437,466 @@ public interface Subsystem {
 	 * @return The type of this subsystem.
 	 */
 	public String getType();
-	
+
 	/**
 	 * Returns the {@link SubsystemConstants#SUBSYSTEM_VERSION version} of this
 	 * subsystem.
-	 * <p/>
+	 * <p>
 	 * The subsystem version conforms to the same grammar rules as the bundle
 	 * version and is derived from one of the following, in order.
 	 * <ul>
-	 * 		<li>The value of the {@code Subsystem-Version} header, if specified.
-	 * 		</li>
-	 * 		<li>The subsystem URI if passed as the {@code location} along with
-	 *          the {@code content} to the {@link #install(String, InputStream)
-	 *          install} method.
-	 *      </li>
-	 * 		<li>Defaults to {@code 0.0.0}.
-	 * 		</li>
+	 * <li>The value of the {@link SubsystemConstants#SUBSYSTEM_VERSION
+	 * Subsystem-Version} header, if specified.</li>
+	 * <li>The subsystem URI if passed as the {@code location} along with the
+	 * {@code content} to the {@link #install(String, InputStream) install}
+	 * method.</li>
+	 * <li>Defaults to {@code 0.0.0}.</li>
 	 * </ul>
-	 * The combination of {@link #getSymbolicName() symbolic name} and version
-	 * is unique within a region. The version of the root subsystem matches this
-	 * specification's version.
-	 * <p/>
+	 * The combination of subsystem {@link #getSymbolicName() symbolic name} and
+	 * version is unique within a region. The version of the root subsystem
+	 * matches this specification's version.
+	 * <p>
 	 * This method must continue to return this subsystem's version while this
-	 * subsystem is in the {@link State#INSTALL_FAILED INSTALL_FAILED} or {@link
-	 * State#UNINSTALLED UNINSTALLED} states.
+	 * subsystem is in the {@link State#INSTALL_FAILED INSTALL_FAILED} or
+	 * {@link State#UNINSTALLED UNINSTALLED} states.
 	 * 
 	 * @return The version of this subsystem.
 	 */
 	public Version getVersion();
-	
+
 	/**
-	 * Installs a subsystem from the specified {@code location} identifier.
-	 * <p/>
-	 * This method performs the same function as calling {@link
-	 * #install(String, InputStream)} with the specified {@code location}
-	 * identifier and {@code null} as the {@code content}.
+	 * Installs a subsystem from the specified location identifier.
+	 * <p>
+	 * This method performs the same function as calling
+	 * {@link #install(String, InputStream)} with the specified location
+	 * identifier and {@code null} as the content.
 	 * 
-	 * @param location - The location identifier of the subsystem to install.
+	 * @param location The location identifier of the subsystem to install.
 	 * @return The installed subsystem.
-	 * @throws IllegalStateException If this subsystem's state is in {{@link
-	 * State#INSTALLING INSTALLING}, {@link State#INSTALL_FAILED INSTALL_FAILED}
-	 * , {@link State#UNINSTALLING UNINSTALLING}, {@link State#UNINSTALLED
-	 * UNINSTALLED}}.
+	 * @throws IllegalStateException If this subsystem's state is in
+	 *         {@link State#INSTALLING INSTALLING}, {@link State#INSTALL_FAILED
+	 *         INSTALL_FAILED}, {@link State#UNINSTALLING UNINSTALLING},
+	 *         {@link State#UNINSTALLED UNINSTALLED}.
 	 * @throws SubsystemException If the installation failed.
-	 * @throws SecurityException If the caller does not have the appropriate 
+	 * @throws SecurityException If the caller does not have the appropriate
 	 *         {@link SubsystemPermission}[installed subsystem,LIFECYCLE], and
 	 *         the runtime supports permissions.
 	 * @see #install(String, InputStream)
 	 */
-	public Subsystem install(String location) throws SubsystemException;
-	
+	public Subsystem install(String location);
+
 	/**
-	 * Installs a subsystem from the specified {@code content}.
-	 * <p/>
-	 * The specified {@code location} will be used as an identifier of the
-	 * subsystem. Every installed subsystem is uniquely identified by its
-	 * location, which is typically in the form of a URI. If the specified
-	 * {@code location} conforms to the {@code subsystem-uri} grammar, the
-	 * required symbolic name and optional version information will be used as
-	 * default values.
-	 * <p/>
-	 * If the specified {@code content} is null, a new input stream must be
+	 * Installs a subsystem from the specified content.
+	 * <p>
+	 * The specified location will be used as an identifier of the subsystem.
+	 * Every installed subsystem is uniquely identified by its location, which
+	 * is typically in the form of a URI. If the specified location conforms to
+	 * the {@code subsystem-uri} grammar, the required symbolic name and
+	 * optional version information will be used as default values.
+	 * <p>
+	 * If the specified content is {@code null}, a new input stream must be
 	 * created from which to read the subsystem by interpreting, in an
-	 * implementation dependent manner, the specified {@code location}.
-	 * <p/>
+	 * implementation dependent manner, the specified location.
+	 * <p>
 	 * A subsystem installation must be persistent. That is, an installed
 	 * subsystem must remain installed across Framework and VM restarts.
-	 * <p/>
+	 * <p>
 	 * All references to changing the state of this subsystem include both
 	 * changing the state of the subsystem object as well as the state property
 	 * of the subsystem service registration.
-	 * <p/>
-	 * Implementations should be sensitive to the potential for long running
-	 * operations and periodically check the current thread for interruption. An
-	 * interrupted thread should result in a SubsystemException with an
-	 * InterruptedException as the cause and be treated as an installation
-	 * failure.
-	 * <p/>
-	 * All installation failure flows include the following, in order.
-	 * <ol>
-	 * <li>Uninstall all resources installed as part of this operation.</li>
-	 * <li>Change the state to INSTALL_FAILED.</li>
-	 * <li>Change the state to UNINSTALLING.</li>
-	 * <li>All content and dependencies which may have been installed by 
-	 *     the installing process must be uninstalled.
-	 * <li>Change the state to UNINSTALLED.</li>
-	 * <li>Unregister the subsystem service.</li>
-	 * <li>If the subsystem is a scoped subsystem then, uninstall the region context bundle.</li>
-	 * <li>Throw a SubsystemException with the specified cause.</li>
-	 * </ol>
+	 * <p>
 	 * The following steps are required to install a subsystem.
 	 * <ol>
-	 * <li>If an installed subsystem with the specified {@code location}
-	 * identifier already exists, return the installed subsystem.</li>
-	 * <li>Read the specified {@code content} in order to determine the symbolic
-	 * name, version, and type of the installing subsystem. If an error occurs
-	 * while reading the content, an installation failure results.</li>
+	 * <li>If an installed subsystem with the specified location identifier
+	 * already exists, return the installed subsystem.</li>
+	 * <li>Read the specified content in order to determine the symbolic name,
+	 * version, and type of the installing subsystem. If an error occurs while
+	 * reading the content, an installation failure results.</li>
 	 * <li>If an installed subsystem with the same symbolic name and version
 	 * already exists within this subsystem's region, complete the installation
-	 * with one of the following.
-	 * <ul>
-	 * <li>If the installing and installed subsystems' types are not equal, an
-	 * installation failure results.</li>
-	 * <li>If the installing and installed subsystems' types are equal, and the
+	 * with one of the following.<br/>
+	 * - If the installing and installed subsystems' types are not equal, an
+	 * installation failure results.<br/>
+	 * - If the installing and installed subsystems' types are equal, and the
 	 * installed subsystem is already a child of this subsystem, return the
-	 * installed subsystem.</li>
-	 * <li>If the installing and installed subsystems' types are equal, and the
+	 * installed subsystem.<br/>
+	 * - If the installing and installed subsystems' types are equal, and the
 	 * installed subsystem is not already a child of this subsystem, add the
 	 * installed subsystem as a child of this subsystem, increment the installed
-	 * subsystem's reference count by one, and return the installed subsystem.</li>
-	 * </ul>
-	 * </li>
-	 * <li>Create a new subsystem based on the specified {@code location} and
-	 * {@code content}.</li>
-	 * <li>If the subsystem is scoped, install and activate a new region context
+	 * subsystem's reference count by one, and return the installed subsystem.
+	 * <li>Create a new subsystem based on the specified location and content.</li>
+	 * <li>If the subsystem is scoped, install and start a new region context
 	 * bundle.</li>
-	 * <li>Change the state to INSTALLING and register a new subsystem service.</li>
+	 * <li>Change the state to {@link State#INSTALLING INSTALLING} and register
+	 * a new subsystem service.</li>
 	 * <li>Discover the subsystem's content resources. If any mandatory resource
 	 * is missing, an installation failure results.</li>
 	 * <li>Discover the dependencies required by the content resources. If any
 	 * mandatory dependency is missing, an installation failure results.</li>
-	 * <li>{@link ResolverHook Disable} runtime resolution for the resources.</li>
+	 * <li>Using a framework {@code ResolverHook}, disable runtime resolution
+	 * for the resources.</li>
 	 * <li>For each resource, increment the reference count by one. If the
-	 * reference count is one, install the resource. All dependencies must be
-	 * installed before any content resource. If an error occurs while
+	 * reference count is one, install the resource. If an error occurs while
 	 * installing a resource, an install failure results with that error as the
 	 * cause.</li>
 	 * <li>If the subsystem is scoped, enable the import sharing policy.</li>
 	 * <li>Enable runtime resolution for the resources.</li>
-	 * <li>Change the state of the subsystem to INSTALLED.</li>
+	 * <li>Change the state of the subsystem to {@link State#INSTALLED
+	 * INSTALLED}.</li>
 	 * <li>Return the new subsystem.</li>
 	 * </ol>
+	 * <p>
+	 * Implementations should be sensitive to the potential for long running
+	 * operations and periodically check the current thread for interruption. An
+	 * interrupted thread should result in a {@link SubsystemException} with an
+	 * InterruptedException as the cause and be treated as an installation
+	 * failure.
+	 * <p>
+	 * All installation failure flows include the following, in order.
+	 * <ol>
+	 * <li>Change the state to {@link State#INSTALL_FAILED INSTALL_FAILED}.</li>
+	 * <li>Change the state to {@link State#UNINSTALLING UNINSTALLING}.</li>
+	 * <li>All content and dependencies which may have been installed by the
+	 * installing process must be uninstalled.
+	 * <li>Change the state to {@link State#UNINSTALLED UNINSTALLED}.</li>
+	 * <li>Unregister the subsystem service.</li>
+	 * <li>If the subsystem is a scoped subsystem then, uninstall the region
+	 * context bundle.</li>
+	 * <li>Throw a {@link SubsystemException} with the cause of the installation
+	 * failure.</li>
+	 * </ol>
 	 * 
-	 * @param location - The location identifier of the subsystem to be
-	 *        installed.
-	 * @param content - The input stream from which this subsystem will be read
-	 *        or null to indicate the input stream must be created from the
+	 * @param location The location identifier of the subsystem to be installed.
+	 * @param content The input stream from which this subsystem will be read or
+	 *        {@code null} to indicate the input stream must be created from the
 	 *        specified location identifier. The input stream will always be
 	 *        closed when this method completes, even if an exception is thrown.
 	 * @return The installed subsystem.
-	 * @throws IllegalStateException If this subsystem's state is in {INSTALLING
-	 *         , INSTALL_FAILED, UNINSTALLING, UNINSTALLED}.
+	 * @throws IllegalStateException If this subsystem's state is in
+	 *         {@link State#INSTALLING INSTALLING}, {@link State#INSTALL_FAILED
+	 *         INSTALL_FAILED}, {@link State#UNINSTALLING UNINSTALLING},
+	 *         {@link State#UNINSTALLED UNINSTALLED}.
 	 * @throws SubsystemException If the installation failed.
 	 * @throws SecurityException If the caller does not have the appropriate
-	 *         SubsystemPermission[installed subsystem,LIFECYCLE], and the
-	 *         runtime supports permissions.
+	 *         {@link SubsystemPermission}[installed subsystem,LIFECYCLE], and
+	 *         the runtime supports permissions.
 	 */
-	public Subsystem install(String location, InputStream content) throws SubsystemException;
-	
+	public Subsystem install(String location, InputStream content);
+
 	/**
 	 * Starts this subsystem.
-	 * <p/>
+	 * <p>
 	 * The following table shows which actions are associated with each state.
-	 * An action of Wait means this method will block until a state transition
-	 * occurs, upon which the new state will be evaluated in order to
-	 * determine how to proceed. An action of Return means this method returns
+	 * An action of {@code Wait} means this method will block until a state
+	 * transition occurs, upon which the new state will be evaluated in order to
+	 * determine how to proceed. If a state transition does not occur in a
+	 * reasonable time while waiting then no action is taken and a
+	 * SubsystemException is thrown to indicate the subsystem was unable to be
+	 * started. An action of {@code Return} means this method returns
 	 * immediately without taking any other action.
-	 * <p/>
-	 * <table border="1">
-	 * 		<tr>
-	 * 			<th>State</td>
-	 * 			<th>Action</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>INSTALLING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>INSTALLED</td>
-	 * 			<td>Resolve, Start</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>INSTALL_FAILED</td>
-	 * 			<td>IllegalStateException</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>RESOLVING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>RESOLVED</td>
-	 * 			<td>If this subsystem is in the process of being<br/>
-	 *              started, Wait. Otherwise, Start.</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>STARTING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>ACTIVE</td>
-	 * 			<td>Return</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>STOPPING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>UNINSTALLING</td>
-	 * 			<td>IllegalStateException</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>UNINSTALLED</td>
-	 * 			<td>IllegalStateException</td>
-	 * 		</tr>
+	 * </p>
+	 * <table>
+	 * <tr>
+	 * <th>State</th>
+	 * <th width="4">Action</th>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#INSTALLING INSTALLING}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#INSTALLED INSTALLED}</td>
+	 * <td>{@code Resolve}<br/>
+	 * {@code Start}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#INSTALL_FAILED INSTALL_FAILED}</td>
+	 * <td>{@code IllegalStateException}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#RESOLVING RESOLVING}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#RESOLVED RESOLVED}</td>
+	 * <td>{@code Start}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#STARTING STARTING}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#ACTIVE ACTIVE}</td>
+	 * <td>{@code Return}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#STOPPING STOPPING}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#UNINSTALLING UNINSTALLING}</td>
+	 * <td>{@code IllegalStateException}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#UNINSTALLED UNINSTALLED}</td>
+	 * <td>{@code IllegalStateException}</td>
+	 * </tr>
 	 * </table>
-	 * <p/>
+	 * <p>
 	 * All references to changing the state of this subsystem include both
 	 * changing the state of the subsystem object as well as the state property
 	 * of the subsystem service registration.
-	 * <p/>
-	 * Implementations should be sensitive to the potential for long running
-	 * operations and periodically check the current thread for interruption. An
-	 * interrupted thread should be treated as a start failure with an
-	 * InterruptedException as the cause.
-	 * <p/>
-	 * All start failure flows include the following, in order.
-	 * <ol>
-	 * 		<li>Stop all resources that were started as part of this operation.
-	 *      </li>
-	 *      <li>Change the state to either INSTALLED or RESOLVED.
-	 * 		</li>
-	 * 		<li>Throw a SubsystemException with the specified cause.
-	 *      </li>
-	 * </ol>
-	 * <p/>
+	 * <p>
 	 * A subsystem must be persistently started. That is, a started subsystem
 	 * must be restarted across Framework and VM restarts, even if a start
 	 * failure occurs.
-	 * <p/>
+	 * <p>
 	 * The following steps are required to start this subsystem.
 	 * <ol>
-	 * 		<li>If this subsystem is in the RESOLVED state, proceed to step 5.
-	 * 		</li>
-	 *      <li>Change the state to RESOLVING.
-	 *      </li>
-	 *      <li>Resolve the content resources. A resolution failure results in
-	 *          a start failure with a state of INSTALLED.
-	 *      </li>
-	 *      <li>Change the state to RESOLVED.
-	 *      </li>
-	 *      <li>If this subsystem is scoped, enable the export sharing policy.
-	 * 		</li>
-	 * 		<li>Change the state to STARTING.
-	 *      </li>
-	 *      <li>For each eligible resource, increment the activation count by
-	 *          one. If the activation count is one, start the resource. All
-	 *          dependencies must be started before any content
-	 *          resource, and content resources must be started according to the
-	 *          specified {@link SubsystemConstants#START_LEVEL_DIRECTIVE start
-	 *          order}. If an error occurs while starting a resource, a start
-	 *          failure results with that error as the cause.
-	 *      </li>
-	 *      <li>Change the state to ACTIVE.
-	 * 		</li>
+	 * <li>Set the subsystem <i>autostart setting</i> to <i>started</i>.</li>
+	 * <li>If this subsystem is in the {@link State#RESOLVED RESOLVED} state,
+	 * proceed to step 7.</li>
+	 * <li>Change the state to {@link State#RESOLVING RESOLVING}.</li>
+	 * <li>Resolve the content resources. A resolution failure results in a
+	 * start failure with a state of {@link State#INSTALLED INSTALLED}.</li>
+	 * <li>Change the state to {@link State#RESOLVED RESOLVED}.</li>
+	 * <li>If this subsystem is scoped, enable the export sharing policy.</li>
+	 * <li>Change the state to {@link State#STARTING STARTING}.</li>
+	 * <li>For each eligible resource, increment the active use count by one. If
+	 * the active use count is one, start the resource. All dependencies must be
+	 * started before any content resource, and content resources must be
+	 * started according to the specified
+	 * {@link SubsystemConstants#START_ORDER_DIRECTIVE start order}. If an error
+	 * occurs while starting a resource, a start failure results with that error
+	 * as the cause.</li>
+	 * <li>Change the state to {@link State#ACTIVE ACTIVE}.</li>
+	 * </ol>
+	 * <p>
+	 * Implementations should be sensitive to the potential for long running
+	 * operations and periodically check the current thread for interruption. An
+	 * interrupted thread should be treated as a start failure with an
+	 * {@code InterruptedException} as the cause.
+	 * <p>
+	 * All start failure flows include the following, in order.
+	 * <ol>
+	 * <li>If the subsystem state is {@link State#STARTING STARTING} then change
+	 * the state to {@link State#STOPPING STOPPING} and stop all resources that
+	 * were started as part of this operation.</li>
+	 * <li>Change the state to either {@link State#INSTALLED INSTALLED} or
+	 * {@link State#RESOLVED RESOLVED}.</li>
+	 * <li>Throw a SubsystemException with the specified cause.</li>
 	 * </ol>
-	 * <p/> 
-	 * @throws SubsystemException If this subsystem fails to start. 
+	 * 
+	 * @throws SubsystemException If this subsystem fails to start.
 	 * @throws IllegalStateException If this subsystem's state is in
-	 *         {INSTALL_FAILED, UNINSTALLING, or UNINSTALLED}, or if the state
-	 *         of at least one of this subsystem's parents is not in {STARTING,
-	 *         ACTIVE}.
-	 * @throws SecurityException If the caller does not have the appropriate 
-	 *         SubsystemPermission[this,EXECUTE], and the runtime supports 
-	 *         permissions.
+	 *         {@link State#INSTALL_FAILED INSTALL_FAILED},
+	 *         {@link State#UNINSTALLING UNINSTALLING}, or
+	 *         {@link State#UNINSTALLED UNINSTALLED}, or if the state of at
+	 *         least one of this subsystem's parents is not in
+	 *         {@link State#STARTING STARTING}, {@link State#ACTIVE ACTIVE}.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         {@link SubsystemPermission}[this,EXECUTE], and the runtime
+	 *         supports permissions.
 	 */
-	public void start() throws SubsystemException;
-	
+	public void start();
+
 	/**
 	 * Stops this subsystem.
-	 * <p/>
+	 * <p>
 	 * The following table shows which actions are associated with each state.
-	 * An action of Wait means this method will block until a state transition
-	 * occurs, upon which the new state will be evaluated in order to
-	 * determine how to proceed. An action of Return means this method returns
+	 * An action of {@code Wait} means this method will block until a state
+	 * transition occurs, upon which the new state will be evaluated in order to
+	 * determine how to proceed. If a state transition does not occur in a
+	 * reasonable time while waiting then no action is taken and a
+	 * SubsystemException is thrown to indicate the subsystem was unable to be
+	 * stopped. An action of {@code Return} means this method returns
 	 * immediately without taking any other action.
-	 * <p/>
-	 * <table border="1">
-	 * 		<tr>
-	 * 			<th>State</th>
-	 * 			<th>Action</th>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>INSTALLING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>INSTALLED</td>
-	 * 			<td>Return</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>INSTALL_FAILED</td>
-	 * 			<td>IllegalStateException</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>RESOLVING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>RESOLVED</td>
-	 * 			<td>If this subsystem is in the process of being<br/>
-	 *              started, Wait. Otherwise, Return.</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>STARTING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>ACTIVE</td>
-	 * 			<td>Stop</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>STOPPING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>UNINSTALLING</td>
-	 * 			<td>IllegalStateException</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>UNINSTALLED</td>
-	 * 			<td>IllegalStateException</td>
-	 * 		</tr>
+	 * </p>
+	 * <table>
+	 * <tr>
+	 * <th>State</th>
+	 * <th width="4">Action</th>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#INSTALLING INSTALLING}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#INSTALLED INSTALLED}</td>
+	 * <td>{@code Return}</td>
+	 * <td>
+	 * <tr>
+	 * <td>{@link State#INSTALL_FAILED INSTALL_FAILED}</td>
+	 * <td>{@code IllegalStateException}</td>
+	 * <td>
+	 * <tr>
+	 * <td>{@link State#RESOLVING RESOLVING}</td>
+	 * <td>{@code Wait}</td>
+	 * <td>
+	 * <tr>
+	 * <td>{@link State#RESOLVED RESOLVED}</td>
+	 * <td>{@code Return}</td>
+	 * <td>
+	 * <tr>
+	 * <td>{@link State#STARTING STARTING}</td>
+	 * <td>{@code Wait}</td>
+	 * <td>
+	 * <tr>
+	 * <td>{@link State#ACTIVE ACTIVE}</td>
+	 * <td>{@code Stop}</td>
+	 * <td>
+	 * <tr>
+	 * <td>{@link State#STOPPING STOPPING}</td>
+	 * <td>{@code Wait}</td>
+	 * <td>
+	 * <tr>
+	 * <td>{@link State#UNINSTALLING UNINSTALLING}</td>
+	 * <td>{@code IllegalStateException}</td>
+	 * <td>
+	 * <tr>
+	 * <td>{@link State#UNINSTALLED UNINSTALLED}</td>
+	 * <td>{@code IllegalStateException}</td>
+	 * <td>
 	 * </table>
-	 * <p/>
-	 * Implementations should be sensitive to the potential for long running
-	 * operations and periodically check the current thread for interruption, in
-	 * which case a SubsystemException with an InterruptedException as the cause
-	 * should be thrown. If an interruption occurs while waiting, this method
-	 * should terminate immediately. Once the transition to the STOPPING
-	 * state has occurred, however, this method must not terminate due to an
-	 * interruption until the stop process has completed.
-	 * <p/>
+	 * <p>
 	 * A subsystem must be persistently stopped. That is, a stopped subsystem
 	 * must remain stopped across Framework and VM restarts.
-	 * <p/>
+	 * <p>
 	 * All references to changing the state of this subsystem include both
 	 * changing the state of the subsystem object as well as the state property
 	 * of the subsystem service registration.
-	 * <p/>
+	 * <p>
 	 * The following steps are required to stop this subsystem.
 	 * <ol>
-	 * 		<li>Change the state to STOPPING.
-	 * 		</li>
-	 * 		<li>For each eligible resource, decrement the activation count by
-	 *          one. If the activation count is zero, stop the resource. All
-	 *          content resources must be stopped before any dependencies,
-	 *          and content resources must be stopped in reverse
-	 *          {@link SubsystemConstants#START_LEVEL_DIRECTIVE start order}. If
-	 *          an error occurs while stopping a resource, a stop failure
-	 *          results with that error as the cause.
-	 *      </li>
-	 *      <li>Change the state to RESOLVED.
-	 *      </li>
+	 * <li>Set the subsystem <i>autostart setting</i> to <i>stopped</i>.</li>
+	 * <li>Change the state to {@link State#STOPPING STOPPING}.</li>
+	 * <li>For each eligible resource, decrement the active use count by one. If
+	 * the active use count is zero, stop the resource. All content resources
+	 * must be stopped before any dependencies, and content resources must be
+	 * stopped in reverse {@link SubsystemConstants#START_ORDER_DIRECTIVE start
+	 * order}.</li>
+	 * <li>Change the state to {@link State#RESOLVED RESOLVED}.</li>
 	 * </ol>
 	 * With regard to error handling, once this subsystem has transitioned to
-	 * the STOPPING state, every part of each step above must be attempted.
-	 * Errors subsequent to the first should be logged. Once the stop process
-	 * has completed, a SubsystemException must be thrown with the initial error
-	 * as the specified cause.
-	 * <p/>
+	 * the {@link State#STOPPING STOPPING} state, every part of each step above
+	 * must be attempted. Errors subsequent to the first should be logged. Once
+	 * the stop process has completed, a SubsystemException must be thrown with
+	 * the initial error as the specified cause.
+	 * <p>
+	 * Implementations should be sensitive to the potential for long running
+	 * operations and periodically check the current thread for interruption, in
+	 * which case a SubsystemException with an InterruptedException as the cause
+	 * should be thrown. If an interruption occurs while waiting, this method
+	 * should terminate immediately. Once the transition to the
+	 * {@link State#STOPPING STOPPING} state has occurred, however, this method
+	 * must not terminate due to an interruption until the stop process has
+	 * completed.
+	 * 
 	 * @throws SubsystemException If this subsystem fails to stop cleanly.
 	 * @throws IllegalStateException If this subsystem's state is in
-	 *         {INSTALL_FAILED, UNINSTALLING, or UNINSTALLED}.
-	 * @throws SecurityException If the caller does not have the appropriate 
-	 *         SubsystemPermission[this,EXECUTE], and the runtime supports 
-	 *         permissions.
+	 *         {@link State#INSTALL_FAILED INSTALL_FAILED},
+	 *         {@link State#UNINSTALLING UNINSTALLING}, or
+	 *         {@link State#UNINSTALLED UNINSTALLED}.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         {@link SubsystemPermission}[this,EXECUTE], and the runtime
+	 *         supports permissions.
 	 */
-	public void stop() throws SubsystemException;
-	
+	public void stop();
+
 	/**
 	 * Uninstalls this subsystem.
-	 * <p/>
+	 * <p>
 	 * The following table shows which actions are associated with each state.
-	 * An action of Wait means this method will block until a state transition
-	 * occurs, upon which the new state will be evaluated in order to
-	 * determine how to proceed. An action of Return means this method returns
+	 * An action of {@code Wait} means this method will block until a state
+	 * transition occurs, upon which the new state will be evaluated in order to
+	 * determine how to proceed. If a state transition does not occur in a
+	 * reasonable time while waiting then no action is taken and a
+	 * SubsystemException is thrown to indicate the subsystem was unable to be
+	 * uninstalled. An action of {@code Return} means this method returns
 	 * immediately without taking any other action.
-	 * <p/>
-	 * <table border="1">
-	 * 		<tr>
-	 * 			<th>State</td>
-	 * 			<th>Action</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>INSTALLING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>INSTALLED</td>
-	 * 			<td>Uninstall</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>INSTALL_FAILED</td>
-	 * 			<td>IllegalStateException</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>RESOLVING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>RESOLVED</td>
-	 * 			<td>If this subsystem is in the process of being<br/>
-	 *              started, Wait. Otherwise, Uninstall.</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>STARTING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>ACTIVE</td>
-	 * 			<td>Stop, Uninstall</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>STOPPING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>UNINSTALLING</td>
-	 * 			<td>Wait</td>
-	 * 		</tr>
-	 * 		<tr align="center">
-	 * 			<td>UNINSTALLED</td>
-	 * 			<td>Return</td>
-	 * 		</tr>
+	 * <table>
+	 * <tr>
+	 * <th>State</th>
+	 * <th width="4">Action</th>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#INSTALLING INSTALLING}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#INSTALLED INSTALLED}</td>
+	 * <td>{@code Uninstall}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#INSTALL_FAILED INSTALL_FAILED}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#RESOLVING RESOLVING}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#RESOLVED RESOLVED}</td>
+	 * <td>{@code Uninstall}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#STARTING STARTING}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#ACTIVE ACTIVE}</td>
+	 * <td>{@code Stop}<br/>
+	 * {@code Uninstall}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#STOPPING STOPPING}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#UNINSTALLING UNINSTALLING}</td>
+	 * <td>{@code Wait}</td>
+	 * </tr>
+	 * <tr>
+	 * <td>{@link State#UNINSTALLED UNINSTALLED}</td>
+	 * <td>{@code Return}</td>
+	 * </tr>
 	 * </table>
-	 * <p/>
-	 * Implementations should be sensitive to the potential for long running
-	 * operations and periodically check the current thread for interruption, in
-	 * which case a SubsystemException with an InterruptedException as the cause
-	 * should be thrown. If an interruption occurs while waiting, this method
-	 * should terminate immediately. Once the transition to the UNINSTALLING
-	 * state has occurred, however, this method must not terminate due to an
-	 * interruption until the uninstall process has completed.
-	 * <p/>
+	 * <p>
 	 * All references to changing the state of this subsystem include both
 	 * changing the state of the subsystem object as well as the state property
 	 * of the subsystem service registration.
-	 * <p/>
-	 * The following steps are required to uninstall this subsystem.
+	 * <p>
+	 * The following steps are required to uninstall this subsystem after being
+	 * stopped if necessary.
 	 * <ol>
-	 * 		<li>Change the state to INSTALLED.
-	 * 		<li>Change the state to UNINSTALLING.
-	 * 		</li>
-	 * 		<li>For each referenced resource, decrement the reference count by one. 
-	 * 			If the reference count is zero, uninstall the resource. All content
-	 * 			resources must be uninstalled before any dependencies. If
-	 *          an error occurs while uninstalling a resource, an uninstall
-	 *          failure results with that error as the cause.
-	 *      </li>
-	 *      <li>Change the state to UNINSTALLED.
-	 *      </li>
-	 *      <li>Unregister the subsystem service.
-	 *      </li>
-	 *      <li>Uninstall the region context bundle.
-	 *      </li>
+	 * <li>Change the state to {@link State#INSTALLED INSTALLED}.</li>
+	 * <li>Change the state to {@link State#UNINSTALLING UNINSTALLING}.</li>
+	 * <li>For each referenced resource, decrement the reference count by one.
+	 * If the reference count is zero, uninstall the resource. All content
+	 * resources must be uninstalled before any dependencies.</li>
+	 * <li>Change the state to {@link State#UNINSTALLED UNINSTALLED}.</li>
+	 * <li>Unregister the subsystem service.</li>
+	 * <li>If the subsystem is scoped, uninstall the region context bundle.</li>
 	 * </ol>
 	 * With regard to error handling, once this subsystem has transitioned to
-	 * the UNINSTALLING state, every part of each step above must be attempted.
-	 * Errors subsequent to the first should be logged. Once the uninstall
-	 * process has completed, a SubsystemException must be thrown with the
-	 * specified cause.
-	 * <p/>
+	 * the {@link State#UNINSTALLING UNINSTALLING} state, every part of each
+	 * step above must be attempted. Errors subsequent to the first should be
+	 * logged. Once the uninstall process has completed, a
+	 * {@code SubsystemException} must be thrown with the specified cause.
+	 * <p>
+	 * Implementations should be sensitive to the potential for long running
+	 * operations and periodically check the current thread for interruption, in
+	 * which case a {@code SubsystemException} with an
+	 * {@code InterruptedException} as the cause should be thrown. If an
+	 * interruption occurs while waiting, this method should terminate
+	 * immediately. Once the transition to the {@link State#UNINSTALLING
+	 * UNINSTALLING} state has occurred, however, this method must not terminate
+	 * due to an interruption until the uninstall process has completed.
+	 * 
 	 * @throws SubsystemException If this subsystem fails to uninstall cleanly.
-	 * @throws IllegalStateException If this subsystem's state is in
-	 *         {INSTALL_FAILED}. 
-	 * @throws SecurityException If the caller does not have the appropriate 
-	 *         SubsystemPermission[this,LIFECYCLE], and the runtime supports
-	 *         permissions.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *         {@link SubsystemPermission}[this,LIFECYCLE], and the runtime
+	 *         supports permissions.
 	 */
-	public void uninstall() throws SubsystemException;
+	public void uninstall();
 }