You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@aries.apache.org by Lin Sun <li...@gmail.com> on 2010/07/06 21:47:40 UTC
Re: 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
Hi
Nice docs!
I found the Subsystem.State docs are a bit confusing where it says
"they are more a reflection of what content bundles are permitted to
do". For example, when subsystem.state is active, the content
bundles are permitted to be beyond in active status, and can be in
stopped, resolved, etc. Aren't the subsystem state same as the
composite bundle state or we didn't want to point that out directly in
javadoc?
Thanks
Lin
On Mon, Jul 5, 2010 at 8:23 AM, <gc...@apache.org> wrote:
> 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);
>
> }
>
>
>