incubator-aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From g..@apache.org
Subject svn commit: r960581 - in /incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem: Subsystem.java SubsystemAdmin.java SubsystemConstants.java SubsystemEvent.java SubsystemException.java SubsystemListener.java
Date Mon, 05 Jul 2010 12:23:15 GMT
Author: gcc
Date: Mon Jul  5 12:23:14 2010
New Revision: 960581

URL: http://svn.apache.org/viewvc?rev=960581&view=rev
Log:
ARIES-349 - Added/updated Javadoc for subsystem.api package.

Modified:
    incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/Subsystem.java
    incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemAdmin.java
    incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemConstants.java
    incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemEvent.java
    incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemException.java
    incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemListener.java

Modified: incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/Subsystem.java
URL: http://svn.apache.org/viewvc/incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/Subsystem.java?rev=960581&r1=960580&r2=960581&view=diff
==============================================================================
--- incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/Subsystem.java
(original)
+++ incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/Subsystem.java
Mon Jul  5 12:23:14 2010
@@ -20,86 +20,178 @@ import org.osgi.framework.Bundle;
 import org.osgi.framework.Version;
 
 /**
- * Interface representing an installed subsystem
+ * A representation of a subsystem in the framework. A subsystem is a
+ * collection of bundles and/or other resource. A subsystem has isolation
+ * semantics. Subsystem types are defined that have different default isolation
+ * semantics. For example, an Application subsystem does not export any of the
+ * packages or services provided by its content bundles, and imports any
+ * packages or services that are required to satisfy unresolved package or
+ * service dependencies of the content bundles.
+ * 
+ * A subsystem is defined using a manifest format.
  */
 public interface Subsystem {
 
+    /**
+     * The states of a subsystem in the framework. These states match those of a
+     * Bundle and are derived using the same rules as CompositeBundles. As such,
+     * they are more a reflection of what content bundles are permitted to do
+     * rather than an aggregation of the content bundle states.
+     */
     public enum State {
 
+        /**
+         * A subsystem is in the INSTALLED state when it is initially created.
+         * It may or may not contain content bundles. No content bundles are
+         * permitted to be resolved while the subsystem is in the INSTALLED
+         * state.
+         */
         INSTALLED,
+
+        /**
+         * A subsystem in the RESOLVED is allowed to have its content bundles
+         * resolved. The content bundles are not allowed to activate while the
+         * subsystem is in the RESOLVED state.
+         */
         RESOLVED,
+
+        /**
+         * A subsystem is in the STARTING state when all its content bundles are
+         * enabled for activation. The content bundles are started according to
+         * the start-level specification.
+         */
         STARTING,
+
+        /**
+         * A subsystem in the STOPPING state is in the process of taking its its active start
level to
+         * zero, stopping all the content bundles.
+         */
         STOPPING,
+
+        /**
+         * A subsystem is in the ACTIVE state when it has reached the beginning
+         * start-level (for starting it's contents), and all its persistently
+         * started content bundles that are resolved and have had their
+         * start-levels met have completed, or failed, their activator start
+         * method.
+         */
         ACTIVE,
+
+        /**
+         * A subsystem is in the UNINSTALLED state when all its content bundles
+         * and uninstalled and its system bundle context is invalidated.
+         */
         UNINSTALLED
 
     }
 
     /**
-     * Retrieve the state of the subsystem.
+     * Gets the state of the subsystem.
      *
-     * @return
+     * @return the state of the subsystem.
      */
     State getState();
 
     /**
-     * Start the subsystem (i.e. start all its constituent bundles according to their start
level).
+     * Starts the subsystem. The subsystem is started according to the rules
+     * defined for Bundles and the content bundles are enabled for activation.
+     * 
+     * @throws SubsystemException
+     *             If this subsystem could not be started.
+     * @throws IllegalStateException
+     *             If this subsystem has been uninstalled.
+     * @throws SecurityException
+     *             If the caller does not have the appropriate
+     *             AdminPermission[this,EXECUTE] and the runtime supports
+     *             permissions.
      */
     void start() throws SubsystemException;
 
     /**
-     * Stop the subsystem (i.e. stop all its constituent bundles).
+     * Stops the subsystem. The subsystem is stopped according to the rules
+     * defined for Bundles and the content bundles are disabled for activation
+     * and stopped.
+     * 
+     * @throws SubsystemException
+     *             TODO: does not fit with BundleException from Bundle.stop.
+     *             What are the circumstances that cause this to be throw? When
+     *             an exception is thrown from a content bundle?
+     * @throws IllegalStateException
+     *             If this subsystem has been uninstalled.
+     * @throws SecurityException
+     *             If the caller does not have the appropriate
+     *             AdminPermission[this,EXECUTE] and the runtime supports
+     *             permissions.
      */
     void stop() throws SubsystemException;
 
     /**
-     * The identifier of the subsystem.  Must be unique in the framework.
-     *
-     * @return
+     * Gets the identifier of the subsystem. Subsystem identifiers are assigned
+     * when the subsystem is installed and are unique within the framework.
+     * 
+     * @return the identifier for the subsystem.
      */
     long getSubsystemId();
 
     /**
-     * The location of the subsystem.
-     * The location will be used when updating a subsystem to load the new
-     * content and/or identify subsystems to update.
-     *
-     * @return
+     * The location identifier used to install this subsystem through
+     * SubsystemAdmin.install. This identifier does not change while this
+     * subsystem remains installed, even after SubsystemAdmin.update. This
+     * location identifier is used in SubsystemAdmin.update if no other update
+     * source is specified.
+     * 
+     * @return The string representation of the subsystem's location identifier.
      */
     String getLocation();
 
     /**
-     * Retrieve the symbolic name of this subsystem.
+     * Gets the symbolic name of this subsystem.
      *
-     * @return
+     * @return the symbolic name of this subsystem.
      */
     String getSymbolicName();
 
     /**
-     * Retrieve the version of this subsystem.
+     * Gets the version of this subsystem.
      *
-     * @return
+     * @return the version of this subsystem.
      */
     Version getVersion();
 
     /**
-     * Return the subsystem headers
-     *
-     * @return
+     * Gets the headers used to define this subsystem. The headers will be
+     * localized using the locale returned by java.util.Locale.getDefault. This
+     * is equivalent to calling <code>getHeaders(null)</code>.
+     * 
+     * @return the headers used to define this subsystem.
+     * @throws SecurityException
+     *             If the caller does not have the appropriate
+     *             AdminPermission[this,METADATA] and the runtime supports
+     *             permissions.
      */
     Map<String, String> getHeaders();
 
     /**
-     * Return the subsystem headers
-     *
-     * @return
+     * Gets the headers used to define this subsystem.
+     * 
+     * @param locale
+     *            The locale name to be used to localize the headers. If the
+     *            locale is <code>null</code> then the locale returned by
+     *            java.util.Locale.getDefault is used. If the value is the empty
+     *            string then the returned headers are returned unlocalized.
+     * @return the headers used to define this subsystem, localized to the
+     *         specified locale.
+     * @throws SecurityException
+     *             If the caller does not have the appropriate
+     *             AdminPermission[this,METADATA] and the runtime supports
+     *             permissions.
      */
     Map<String, String> getHeaders(String locale);
 
     /**
-     * Retrieve the constituent bundles of this subsystem.
+     * Gets the content bundles of this subsystem.
      *
-     * @return
+     * @return the content of this subsystem.
      */
     Collection<Bundle> getConstituents();
 

Modified: incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemAdmin.java
URL: http://svn.apache.org/viewvc/incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemAdmin.java?rev=960581&r1=960580&r2=960581&view=diff
==============================================================================
--- incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemAdmin.java
(original)
+++ incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemAdmin.java
Mon Jul  5 12:23:14 2010
@@ -15,48 +15,53 @@ package org.apache.aries.subsystem;
 
 import java.io.InputStream;
 import java.util.Collection;
-import java.util.Map;
 
 import org.osgi.framework.Version;
 
 /**
- * Subsystems administration interface.
- *
- * A service implementing this interface will be registered in the OSGi registry.
- *
+ * Subsystem administration interface.
+ * 
+ * A service implementing this interface will be registered in the OSGi service
+ * registry. This service provides the capability to manage subsystem (e.g.
+ * install, uninstall, update). Each instance of the service manages subsystems
+ * at a single level. For example, if subsystems are hierarchically nested, then
+ * an instance of this service is used to manage the subsystems at each level in
+ * the hierarchy.
+ * 
  * Install / update / uninstall operations will be performed sequentially, i.e.
  * they will be synchronized so that no two operations will be performed at the
  * same time.
- *
- * This service will also be made available from managed subsystems, so that only subsystems
- * from the current framework will be available, not nested frameworks.
- *
+ * 
  */
 public interface SubsystemAdmin {
 
     /**
-     * Retrieve all subsystems managed by this service.
-     * This includes all the top-level subsystems installed in the composite
-     * which this service has been retrieved from.
-     *
-     * @return
+     * Gets the subsystems managed by this service. This only includes the
+     * top-level Subsystems installed in the Framework, CoompositeBundle or
+     * Subsystem from which this service has been retrieved.
+     * 
+     * @return the Subsystems managed by this service.
      */
     Collection<Subsystem> getSubsystems();
 
     /**
-     * Retrieve a subsystem given its id.
-     *
+     * Gets the Subsystem identified by its id.
+     * 
      * @param id
-     * @return
+     *            The id of the Subsystem to get.
+     * @return the Subsystem matching the given id.
      */
     Subsystem getSubsystem(long id);
 
     /**
-     * Retrieve a subsystem given its symbolic name and id
-     *
+     * Gets a Subsystem given its symbolic name and version.
+     * 
      * @param symbolicName
+     *            The symbolic name of the subsystem to be returned.
      * @param version
-     * @return
+     *            The version of the Subsystem to be returned.
+     * @return the Subsystem matching the symbolic name and version or
+     *         <code>null</code> if no match is found.
      */
     Subsystem getSubsystem(String symbolicName, Version version);
 
@@ -72,26 +77,54 @@ public interface SubsystemAdmin {
     Subsystem install(String location) throws SubsystemException;
 
     /**
-     * Install a new subsystem from the specified <code>InputStream</code> object.
 
+     * Install a new subsystem from the specified <code>InputStream</code>
+     * object.
      * 
-     * If the specified <code>InputStream</code> is <code>null</code>,
-     * the <code>InputStream</code> must be created from the specified location.
+     * If the specified <code>InputStream</code> is <code>null</code>,
the
+     * <code>InputStream</code> must be created from the specified location.
      * 
-     * The specified location identifier will be used as the identity of the subsystem. 
-     * Every installed subsystem is uniquely identified by its location identifier which
is typically in the form of a URL.
+     * The specified location identifier will be used as the identity of the
+     * subsystem. Every installed subsystem is uniquely identified by its
+     * location identifier which is typically in the form of a URL.
+     * 
+     * A subsystem and its contents must remain installed across Framework and
+     * VM restarts. The subsystem itself is installed atomically, however its
+     * contents are not.
      * 
      * The following steps are required to install a subsystem:
      * 
-     * 1. If a subsystem containing the same location identifier is already installed, the
<code>Subsystem</code> object for that subsystem is returned.
-     * 2. The subsystem's content is read from the input stream.  If this fails, a SubsystemException
is thrown.
-     * 3. The subsystem's associated resources are located
-     * 4. The subsystem's state is set to <code>INSTALLED</code>
-     * 5. The subsystem event of type INSTALLED is fired.
-     * 6. The subsystem object for the newly installed subsystem is returned
+     * <ol>
+     * <li> If a subsystem containing the same location identifier is already
+     *    installed, the <code>Subsystem</code> object for that subsystem is
+     *    returned. </li>
+     * <li> The subsystem's content is read from the input stream. If
+     *    this fails, a <code>SubsystemException</code> is thrown.</li>

+     * <li> The empty subsystem object is created and assigned a unique id 
+     *    which is higher than any previous bundle of subsystem identifier.</li> 
+     * <li> The subsystem's associated resources are located. </li>
+     * <li> The subsystem's state is set to <code>INSTALLED</code> </li>
+     * <li> The subsystem event of type <code>INSTALLED</code> is fired.</li>

+     * <li> Installation of subsystem content is started. </li>
+     * <li> The subsystem object for the newly installed subsystem is returned.</li>
+     * </ol>
+     * 
+     * TODO: discuss the above steps.
      * 
      * @param location
+     *            The location identifier of the subsystem to be installed.
      * @param content
-     * @return
+     *            The <code>InputStream</code> from where the subsystem is to
be
+     *            installed or <code>null</code> if the location is to be used
+     *            to create the <code>InputStream</code>.
+     * @return the installed subsystem.
+     * @throws SubsystemException
+     *             If the <code>InputStream</code> cannot be read or the
+     *             installation fails. This exception is not thrown in the event
+     *             of the subsystems contents failing to install.
+     * @throws SecurityException
+     *             If the caller does not have the appropriate
+     *             AdminPermission[installed subsystem,LIFECYCLE], and the Java
+     *             Runtime Environment supports permissions.
      */
     Subsystem install(String location, InputStream content) throws SubsystemException;
 
@@ -99,38 +132,90 @@ public interface SubsystemAdmin {
      * Update the given subsystem.
      *
      * This method performs the same function as calling {@link #update(Subsystem, InputStream)}

-     * with the specified subsystem and a <code>null</code> InputStream.
+     * with the specified subsystem and a <code>null</code> <code>InputStream</code>.
      * 
-     * @param subsystem
+     * @param subsystem The subsystem to be updated.
      */
     void update(Subsystem subsystem) throws SubsystemException;
 
     /**
-     * Update the given subsystem from an <code>InputStream</code>.  
+     * Update the given subsystem from an <code>InputStream</code>.
+     * 
+     * If the specified <code>InputStream</code> is <code>null</code>,
the
+     * InputStream must be created from the subsystem's
+     * {@link SubsystemConstants#SUBSYSTEM_UPDATELOCATION
+     * Subsystem-UpdateLocation} Manifest header if present, or this subsystem's
+     * location provided when the subsystem was originally installed.
      * 
-     * If the specified <code>InputStream</code> is <code>null</code>,
the InputStream must be created from
-     * the subsystem's {@link SubsystemConstants#SUBSYSTEM_UPDATELOCATION Subsystem-UpdateLocation}
Manifest header 
-     * if present, or this subsystem's original location.
-     *
      * @param subsystem
+     *            The subsystem to be updated.
      * @param content
+     *            The <code>InputStream</code> from which to update the
+     *            subsystem or <code>null</code> if the
+     *            {@link SubsystemConstants#SUBSYSTEM_UPDATELOCATION
+     *            Subsystem-UpdateLocation} or original location are to be used.
+     * @throws SubsystemException
+     *             If the <code>InputStream</code> cannot be read of the update
+     *             fails.
+     * @throws IllegalStateException
+     *             If the subsystem is in the <code>UNINSTALLED</code> state.
+     * @throws SecurityException
+     *             If the caller does not have the appropriate
+     *             AdminPermission[this,LIFECYCLE] for both the current
+     *             subsystem and the updated subsystem and the Java Runtime
+     *             Environment supports permissions.
      */
     void update(Subsystem subsystem, InputStream content) throws SubsystemException;
 
     /**
      * Uninstall the given subsystem.
-     *
+     * 
+     * This method causes the Framework to notify other bundles and subsystems
+     * that this subsystem is being uninstalled, and then puts this subsystem
+     * into the <code>UNINSTALLED</code> state. The Framework must remove any
+     * resources related to this subsystem that it is able to remove. If this
+     * subsystem has exported any packages, the Framework must continue to make
+     * these packages available to their importing bundles or subsystems until
+     * the Package-Admin.refreshPackages method has been called or the Framework
+     * is relaunched.
+     * 
+     * The following steps are required to uninstall a subsystem: 
+     * <ol>
+     * <li> If this subsystem's state is UNINSTALLED then an IllegalStateException
is thrown.</li>
+     * <li> If this subsystem's state is ACTIVE, STARTING or STOPPING, this
+     *    subsystem is stopped as described in the Subsystem.stop method. If
+     *    Subsystem.stop throws an exception, a Framework event of type
+     *    FrameworkEvent.ERROR is fired containing the exception. </li>
+     * <li> This subsystem's state is set to UNINSTALLED. </li>
+     * <li> A subsystem event of type SubsystemEvent.UNINSTALLED is fired.</li>

+     * <li> This subsystem and any persistent storage area provided for this subsystem

+     *    by the Framework are removed.</li>
+     * </ol>
+     * 
      * @param subsystem
+     *            The subsystem to uninstall.
+     * @throws SubsystemException
+     *             If the uninstall failed.
+     * @throws IlegalStateException
+     *             If the subsystem is already in the <code>UNISTALLED</code>
+     *             state.
+     * @throws SecurityException
+     *             If the caller does not have the appropriate
+     *             AdminPermission[this,LIFECYCLE] and the Java Runtime
+     *             Environment supports permissions.
      */
-    void uninstall(Subsystem subsystem) throws SubsystemException;
+  void uninstall(Subsystem subsystem) throws SubsystemException;
 
     /**
-     * Abort the current operation.
-     * The installing thread must throw a SubsystemException if the operation
-     * has actually been canceled and rolled back before terminating.
-     *
+     * Cancel the current operation.
+     * 
+     * The installing thread must throw a <code>SubsystemException</code> if
the
+     * operation has actually been cancelled and rolled back before completion.
+     * 
      * @return <code>true</code> if an operation was ongoing and requested to
be
-     *    cancelled, <code>false</code> if there was no ongoing operation
+     *         cancelled, <code>false</code> if there was no ongoing operation.
+     * 
+     *         TODO: discuss this. Why is it necessary?
      */
     boolean cancel();
 

Modified: incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemConstants.java
URL: http://svn.apache.org/viewvc/incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemConstants.java?rev=960581&r1=960580&r2=960581&view=diff
==============================================================================
--- incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemConstants.java
(original)
+++ incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemConstants.java
Mon Jul  5 12:23:14 2010
@@ -40,37 +40,68 @@ public class SubsystemConstants {
     public static final String SUBSYSTEM_SYMBOLICNAME        = "Subsystem-SymbolicName";
 
     /**
-     * Version of the subsystem
+     * Version of the subsystem.  If not present, the default value is 0.0.0.
      */
     public static final String SUBSYSTEM_VERSION             = "Subsystem-Version";
 
     /**
-     * Human readable name
+     * The human readable subsystem name.
      */
     public static final String SUBSYSTEM_NAME                = "Subsystem-Name";
 
     /**
-     * Human readable description
+     * The human readable subsystem description.
      */
     public static final String SUBSYSTEM_DESCRIPTION         = "Subsystem-Description";
 
     /**
-     * Name of the resource to use for localized headers
+     * Name of the resource to use for localized headers.
      */
     public static final String SUBSYSTEM_LOCALIZATION        = "Subsystem-Localization";
 
     /**
-     * Location to use when updating the subsystem
+     * Location to use when updating the subsystem.
      */
     public static final String SUBSYSTEM_UPDATELOCATION      = "Subsystem-UpdateLocation";
 
+    /**
+     * The list of subsystem contents identified by a symbolic name and version.
+     */
     public static final String SUBSYSTEM_CONTENT             = "Subsystem-Content";
+
+    /**
+     * TODO: what is this for?
+     */
     public static final String SUBSYSTEM_RESOURCES           = "Subsystem-Resources";
 
+    /**
+     * The packages to be imported into the subsystem for use by the subsystem contents.
+     */
     public static final String SUBSYSTEM_IMPORTPACKAGE       = "Subsystem-ImportPackage";
+
+    /**
+     * The packages to be exported by the subsystem for use outside the
+     * subsystem. The packages declarations must match a package provide by a
+     * bundle listed in the subsystem content.
+     */
     public static final String SUBSYSTEM_EXPORTPACKAGE       = "Subsystem-ExportPackage";
+
+    /**
+     * A list of service filters used to identify services that this subsystem requires.
+     */
     public static final String SUBSYSTEM_IMPORTSERVICE       = "Subsystem-ImportService";
+
+    /**
+     * A list of service filters used to identify the services provided by
+     * bundles inside the subsystem that can be exported outside the subsystem.
+     */
     public static final String SUBSYSTEM_EXPORTSERVICE       = "Subsystem-ExportService";
+    
+    /**
+     * A list of Bundles the subsystem requires. These bundles are made
+     * available to satisfy Require-Bundle statements for the subsystem content
+     * bundles.
+     */
     public static final String SUBSYSTEM_REQUIREBUNDLE       = "Subsystem-RequireBundle";
 
     //====================================================
@@ -91,31 +122,38 @@ public class SubsystemConstants {
     public static final String APPLICATION_SYMBOLICNAME      = "Application-SymbolicName";
 
     /**
-     * Version of the application
+     * Version of the application.  If not present, the default value is 0.0.0.
      */
     public static final String APPLICATION_VERSION           = "Application-Version";
 
     /**
-     * Human readable name
+     * Human readable application name.
      */
     public static final String APPLICATION_NAME              = "Application-Name";
 
     /**
-     * Human readable description
+     * Human readable description.
      */
     public static final String APPLICATION_DESCRIPTION       = "Application-Description";
 
     /**
-     * Name of the resource to use for localized headers
+     * Name of the resource to use for localized headers.
      */
     public static final String APPLICATION_LOCALIZATION      = "Application-Localization";
 
     /**
-     * Location to use when updating the subsystem
+     * Location to use when updating the application.
      */
     public static final String APPLICATION_UPDATELOCATION    = "Application-UpdateLocation";
 
+    /**
+     * The list of application contents identified by a symbolic name and version.
+     */
     public static final String APPLICATION_CONTENT           = "Application-Content";
+    
+    /**
+     * TODO: what is this for?
+     */
     public static final String APPLICATION_RESOURCES         = "Application-Resources";
 
 
@@ -137,17 +175,17 @@ public class SubsystemConstants {
     public static final String LIBRARY_SYMBOLICNAME          = "Library-SymbolicName";
 
     /**
-     * Version of the application
+     * Version of the application.  If not present, the default value is 0.0.0.
      */
     public static final String LIBRARY_VERSION               = "Library-Version";
 
     /**
-     * Human readable name
+     * Human readable library name.
      */
     public static final String LIBRARY_NAME                  = "Library-Name";
 
     /**
-     * Human readable description
+     * Human readable library description.
      */
     public static final String LIBRARY_DESCRIPTION           = "Library-Description";
 
@@ -157,11 +195,18 @@ public class SubsystemConstants {
     public static final String LIBRARY_LOCALIZATION          = "Library-Localization";
 
     /**
-     * Location to use when updating the subsystem
+     * Location to use when updating the library
      */
     public static final String LIBRARY_UPDATELOCATION        = "Library-UpdateLocation";
 
+    /**
+     * The list of library contents identified by a symbolic name and version.
+     */
     public static final String LIBRARY_CONTENT               = "Library-Content";
+    
+    /**
+     * TODO: what is this for.
+     */
     public static final String LIBRARY_RESOURCES             = "Library-Resources";
 
 
@@ -189,7 +234,7 @@ public class SubsystemConstants {
     public static final String RESOURCE_TYPE_ATTRIBUTE       = "type";
 
     /**
-     * Identify resources that are bundles.
+     * Identify resources that are bundles (this is the default type).
      */
     public static final String RESOURCE_TYPE_BUNDLE          = "bundle";
 

Modified: incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemEvent.java
URL: http://svn.apache.org/viewvc/incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemEvent.java?rev=960581&r1=960580&r2=960581&view=diff
==============================================================================
--- incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemEvent.java
(original)
+++ incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemEvent.java
Mon Jul  5 12:23:14 2010
@@ -13,19 +13,58 @@
  */
 package org.apache.aries.subsystem;
 
+import java.io.InputStream;
+
 /**
  * Event sent to listeners when an operation has been performed on a subsystem.
  */
 public class SubsystemEvent {
 
+    /**
+     * The subsystem lifecycle event types that can be produced by a subsystem.
+     * See {@link Subsystem} and {@link SubsystemAdmin} for details on the
+     * circumstances under which these events are fired.
+     */
     public enum Type {
+        
+        /**
+         * Event type used to indicate a subsystem has been installed.
+         */
         INSTALLED,
+
+        /**
+         * Event type used to indicate a subsystem has been started.
+         */
         STARTED,
+
+        /**
+         * Event type used to indicate a subsystem has been stopped.
+         */
         STOPPED,
+        
+        /**
+         * Event type used to indicate a subsystem has been updated.
+         */
         UPDATED,
+        
+        /**
+         * Event type used to indicate a subsystem has been uninstalled.
+         */
         UNINSTALLED,
+        
+        /**
+         * Event type used to indicate a subsystem has been resolved.
+         */
         RESOLVED,
+        
+        /**
+         * Event type used to indicate a subsystem is starting.
+         */
         STARTING,
+        
+        /**
+         * Event type used to indicate a subsystem is stopping.
+         */
         STOPPING
     }
     private final Type type;
@@ -34,20 +73,41 @@ public class SubsystemEvent {
 
     private final Subsystem subsystem;
 
+    /**
+     * Constructs a new subsystem event.
+     * 
+     * @param type The type of the event.  For example, INSTALLED.  See {@link SubsystemEvent.Type}
for the list of event types.
+     * @param timestamp The timestamp for the event.
+     * @param subsystem The subsystem for which the event is being created.
+     */
     public SubsystemEvent(Type type, long timestamp, Subsystem subsystem) {
         this.type = type;
         this.timestamp = timestamp;
         this.subsystem = subsystem;
     }
 
+    /**
+     * Gets the type of the subsystem event.  See {@link SubsystemEvent.Type} for the list
of event types.
+     * @return the type of the subsystem event.
+     */
     public Type getType() {
         return type;
     }
 
+    /**
+     * Gets the timestamp for the subsystem event.
+     * 
+     * @return the timestamp for the subsystem event.
+     */
     public long getTimestamp() {
         return timestamp;
     }
 
+    /**
+     * Gets the subsystem for which the event was created.
+     * 
+     * @return the subsystem for which the event was created.
+     */
     public Subsystem getSubsystem() {
         return subsystem;
     }

Modified: incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemException.java
URL: http://svn.apache.org/viewvc/incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemException.java?rev=960581&r1=960580&r2=960581&view=diff
==============================================================================
--- incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemException.java
(original)
+++ incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemException.java
Mon Jul  5 12:23:14 2010
@@ -15,21 +15,40 @@ package org.apache.aries.subsystem;
 
 /**
  * Exception thrown by SubsystemAdmin or Subsystem when
- * a problem occur.
+ * a problem occurs.
  */
 public class SubsystemException extends RuntimeException {
 
+    /**
+     * Construct a subsystem exception which no message.
+     */
     public SubsystemException() {
     }
 
+    /**
+     * Construct a subsystem exception specifying a message.
+     * 
+     * @param message The message to include in the exception.
+     */
     public SubsystemException(String message) {
         super(message);
     }
 
+    /**
+     * Construct a subsystem exception, wrapping an existing exception.
+     * 
+     * @param message The message to be included in the exception
+     * @param cause The cause of the exception.
+     */
     public SubsystemException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    /**
+     * Construct a subsystem exception, wrapping an existing exception.
+     * 
+     * @param cause The cause of the exception.
+     */
     public SubsystemException(Throwable cause) {
         super(cause);
     }

Modified: incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemListener.java
URL: http://svn.apache.org/viewvc/incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemListener.java?rev=960581&r1=960580&r2=960581&view=diff
==============================================================================
--- incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemListener.java
(original)
+++ incubator/aries/trunk/subsystem/subsystem-api/src/main/java/org/apache/aries/subsystem/SubsystemListener.java
Mon Jul  5 12:23:14 2010
@@ -14,11 +14,20 @@
 package org.apache.aries.subsystem;
 
 /**
- * Registered OSGi services implementing this interface
- * will be delivered subsystem events.
+ * A listener for subsystem events (see {@link SubsystemEvent}).
+ * 
+ * Registered OSGi services implementing this interface will be notified of
+ * subsystem events when they occur. Notifications will only be delivered for
+ * subsystems that are at the same level. For example, events are not seen for
+ * parent or child subsystems.
  */
 public interface SubsystemListener {
 
+    /**
+     * Called to deliver a subsystem event to this subsystem listener.
+     * 
+     * @param event The subsystem event being delivered.
+     */
     void subsystemEvent(SubsystemEvent event);
 
 }



Mime
View raw message