servicemix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gno...@apache.org
Subject svn commit: r634741 [1/2] - in /servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi: ./ component/ management/ messaging/ servicedesc/
Date Fri, 07 Mar 2008 16:54:02 GMT
Author: gnodet
Date: Fri Mar  7 08:54:00 2008
New Revision: 634741

URL: http://svn.apache.org/viewvc?rev=634741&view=rev
Log:
Add javadocs to JBI api

Added:
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/package.html
      - copied, changed from r634214, servicemix/smx4/nmr/trunk/nmr/api/src/main/java/org/apache/servicemix/nmr/api/package.html
Modified:
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/JBIException.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/Bootstrap.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/Component.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ComponentContext.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ComponentLifeCycle.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/InstallationContext.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ServiceUnitManager.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/AdminServiceMBean.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/ComponentLifeCycleMBean.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/DeploymentException.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/DeploymentServiceMBean.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/InstallationServiceMBean.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/InstallerMBean.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/LifeCycleMBean.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/MBeanNames.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/DeliveryChannel.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/ExchangeStatus.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/Fault.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOnly.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOptionalOut.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOut.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessageExchange.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessageExchangeFactory.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessagingException.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/NormalizedMessage.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/RobustInOnly.java
    servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/servicedesc/ServiceEndpoint.java

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/JBIException.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/JBIException.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/JBIException.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/JBIException.java Fri Mar  7 08:54:00 2008
@@ -16,15 +16,32 @@
  */
 package javax.jbi;
 
+/**
+ * JBIException is the top-level exception thrown by all JBI system components.
+ */
 public class JBIException extends Exception {
+
+    /**
+     * Creates a new instance of JBIException with an exception message.
+     * @param aMessage String describing this exception.
+     */
     public JBIException(String aMessage) {
         super(aMessage);
     }
 
+    /**
+     * Creates a new instance of JBIException with the specified message and cause.
+     * @param aMessage String describing this exception.
+     * @param aCause Throwable which represents an underlying problem (or null).
+     */
     public JBIException(String aMessage, Throwable aCause) {
         super(aMessage, aCause);
     }
 
+    /**
+     * Creates a new instance of JBIException with the specified cause.
+     * @param aCause Throwable which represents an underlying problem (or null).
+     */
     public JBIException(Throwable aCause) {
         super(aCause);
     }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/Bootstrap.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/Bootstrap.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/Bootstrap.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/Bootstrap.java Fri Mar  7 08:54:00 2008
@@ -20,14 +20,97 @@
 
 import javax.management.ObjectName;
 
+/**
+ * This interface is implemented by a JBI Component to provide any
+ * special processing required at install/uninstall time. The methods
+ * defined here are called by the JBI implementation during the installation
+ * (or uninstallation) of the component that, among other things, supplies
+ * an implementation of this interface.
+ *
+ * Initialization/cleanup tasks such as creation/deletion of directories,
+ * files, and database tables can be done by the onInstall() and onUninstall()
+ * methods, respectively. This also allows the component to terminate the
+ * installation or uninstallation in the event of an error.
+ *
+ * After calling onInstall() or onUninstall(), regardless of outcome, the JBI
+ * implementation must call the cleanUp() method afterwards. Similarly, if
+ * init(InstallationContext) fails with an exception, the JBI implementation
+ * must call the cleanUp() method.
+ *
+ * Component implementors should note that there is no guarantee that the same
+ * instance of its Bootstrap implementation will be used during both install
+ * and uninstall operations on the component. Data that need to be retained
+ * between installation-time and uninstallation-time must be persisted in such
+ * as fashion that a separate instance of the bootstrap class can find them,
+ * despite component or system shutdown.
+ *
+ * @author JSR208 Exert Group
+ */
 public interface Bootstrap {
+
+    /**
+     * Initializes the installation environment for a component. This method is
+     * expected to save any information from the installation context that may
+     * be needed by other methods.
+     *
+     * If the component needs to register an optional installer configuration MBean,
+     * it MUST do so during execution of this method, or the getExtensionMBean()
+     * method.
+     *
+     * This method must be called after the installation root (available through
+     * the installContext parameter) is prepared. 
+
+     * @param installContext the context containing information from the install
+     *                       command and from the component installation ZIP file;
+     *                       this must be non-null.
+     * @throws JBIException  when there is an error requiring that the installation
+     *                       be terminated
+     */
     void init(InstallationContext installContext) throws JBIException;
 
+    /**
+     * Cleans up any resources allocated by the bootstrap implementation,
+     * including performing deregistration of the extension MBean, if applicable.
+     *
+     * This method must be called after the onInstall() or onUninstall() method
+     * is called, whether it succeeds or fails. It must be called after init() is
+     * called, if init() fails by throwing an exception.
+     * 
+     * @throws JBIException if the bootstrap cannot clean up allocated resources
+     */
     void cleanUp() throws JBIException;
 
+    /**
+     * Obtains the ObjectName of the optional installer configuration MBean. If
+     * none is provided by this component, this method must return null.
+     *
+     * This method must be called before onInstall() (or onUninstall()) is called
+     * by the JBI implementation.
+     *
+     * @return ObjectName of the optional installer configuration MBean; returns null
+     *         if there is no such MBean
+     */
     ObjectName getExtensionMBeanName();
 
+    /**
+     * Called at the beginning of installation of a component to perform any special
+     * installation tasks required by the component.
+     *
+     * This method must not be called if the init() method failed with an exception.
+     *  
+     * @throws JBIException when there is an error requiring that the installation be
+     *         terminated
+     */
     void onInstall() throws JBIException;
 
+    /**
+     * Called at the beginning of uninstallation of a component to perform any special
+     * uninstallation tasks required by the component.
+     *
+     * This method must not be called if the init() method failed with an exception.
+     *
+     * @throws JBIException when there is an error requiring that the uninstallation be
+     *         terminated.
+     */
     void onUninstall() throws JBIException;
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/Component.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/Component.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/Component.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/Component.java Fri Mar  7 08:54:00 2008
@@ -22,16 +22,106 @@
 import org.w3c.dom.Document;
 import org.w3c.dom.DocumentFragment;
 
+/**
+ * This interface, implemented by component implementations, allows
+ * the JBI implementation to query the component for various types
+ * of information. This includes:
+ * <ul>
+ *   <li>The component's life cycle control interface.</li>
+ *   <li>The component's service unit manager, for handling deployments.</li>
+ *   <li>A method for querying service metadata describing services
+ *       provided by this component.</li>
+ *   <li>"Policy" methods that are called by the JBI implementation to
+ *       query if proposed matches of this component to a provider (or
+ *       consumer) are acceptable, according to this component's policies.</li>
+ *   <li>Endpoint reference (EPR) resolution. Some components will provide
+ *       the ability to resolve EPRs (typically binding components). This
+ *       ability to resolve EPRs is used by JBI to facilitate resolution of
+ *       EPRs received by service consumers.</li>
+ *
+ * The name of the class that implements this interface for a component is
+ * specified in the installation descriptor for that component.
+ *
+ * @author JSR208 Exert Group
+ */
 public interface Component {
+
+    /**
+     * Get the life cycle control interface for this component. This interface
+     * allows the JBI implementation to control the running state of this component.
+     *
+     * This method must be called before any other methods of this interface are
+     * called. In addition, the JBI implementation must call the init() method of
+     * the component life cycle returned by this method before calling any other
+     * methods on this interface, or the component life cycle interface.
+     *
+     * @return the life cycle control interface for this component; must be non-null.
+     */
     ComponentLifeCycle getLifeCycle();
 
+    /**
+     * Get the Service Unit manager for this component. If this component does not
+     * support deployments, it must return null.
+     *
+     * @return the ServiceUnitManager for this component, or null if there is none.
+     */
     ServiceUnitManager getServiceUnitManager();
 
+    /**
+     * Retrieves a DOM representation containing metadata which describes the service
+     * provided by this component, through the given endpoint. The result can use WSDL
+     * 1.1 or WSDL 2.0.
+     *
+     * @param endpoint the service endpoint.
+     * @return the description for the specified service endpoint.
+     */
     Document getServiceDescription(ServiceEndpoint endpoint);
 
+    /**
+     * This method is called by JBI to check if this component, in the role of provider
+     * of the service indicated by the given exchange, can actually perform the operation
+     * desired.
+     *
+     * @param endpoint the endpoint to be used by the consumer; must be non-null.
+     * @param exchange the proposed message exchange to be performed; must be non-null.
+     * @return true if this provider component can interact with the described consumer
+     *         to perform the given exchange.
+     */
     boolean isExchangeWithConsumerOkay(ServiceEndpoint endpoint, MessageExchange exchange);
 
+    /**
+     * This method is called by JBI to check if this component, in the role of consumer
+     * of the service indicated by the given exchange, can actually interact with the
+     * provider properly. The provider is described by the given endpoint and the service
+     * description supplied by that endpoint.
+     *
+     * @param endpoint the endpoint to be used by the provider; must be non-null.
+     * @param exchange the proposed message exchange to be performed; must be non-null.
+     * @return true if this consumer component can interact with the described provider
+     *         to perform the given exchange.
+     */
     boolean isExchangeWithProviderOkay(ServiceEndpoint endpoint, MessageExchange exchange);
 
+    /**
+     * Resolve the given endpoint reference. This is called by JBI when it is attempting to
+     * resolve the given EPR on behalf of a component.
+     *
+     * If this component returns a non-null result, it must conform to the following:
+     * <ul>
+     *   <li>This component implements the ServiceEndpoint returned.</li>
+     *   <li>The result must not be registered or activated with the JBI implementation.</li>
+     * </ul>
+     *
+     * Dynamically resolved endpoints are distinct from static ones; they must not be activated
+     * (see {@link javax.jbi.component.ComponentContext#activateEndpoint(javax.xml.namespace.QName, String)}),
+     * nor registered (see {@link ComponentContext}) by components. They can only be used to address
+     * message exchanges; the JBI implementation must deliver such exchanges to the component that
+     * resolved the endpoint reference (see
+     * {@link javax.jbi.component.ComponentContext#resolveEndpointReference(org.w3c.dom.DocumentFragment)}).
+     *
+     * @param epr the endpoint reference, in some XML dialect understood by the appropriate component
+     *            (usually a binding); must be non-null.
+     * @return the service endpoint for the EPR; null if the EPR cannot be resolved by this component.
+     */
     ServiceEndpoint resolveEndpointReference(DocumentFragment epr);
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ComponentContext.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ComponentContext.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ComponentContext.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ComponentContext.java Fri Mar  7 08:54:00 2008
@@ -29,45 +29,276 @@
 import org.w3c.dom.Document;
 import org.w3c.dom.DocumentFragment;
 
+/**
+ * This interface provides access to data needed by a JBI component
+ * about the JBI environment in which it is installed, as well providing
+ * the means to allow the component to inform the JBI environment about
+ * services provided by this component. This interface provides methods
+ * for the following functions:
+ * <ul>
+ *   <li>Get the <bold>DeliveryChannel</bold> for this component. This is
+ *       required to allow the component to send and receive message
+ *       exchanges.</li>
+ *   <li><bold>Activate</bold> (and deactivate) service endpoints provided
+ *       by this component.</li>
+ *   <li><bold>Register</bold> (and deregister) external endpoints provided
+ *       by this component.</li>
+ *   <li><bold>Query</bold> available endpoints (internal and external).</li>
+ *   <li><bold>Query</bold> various data about the component, as installed
+ *       in the JBI environment (name, workspace root, install root, initial
+ *       JNDI context, MBean Server, Transaction Manager).</li>
+ *   <li><bold>Loggers</bold>. Obtain the component's logger and subloggers.</li>
+ *   <li><bold>MBean name creator</bold>. Access a utility for creating
+ *       custom MBean names.</li>
+ *   <li><bold>EPR Resolver</bold>. Ask JBI to resolve an endpoint reference
+ *       (EPR), converting it into a service endpoint.</li>
+ *
+ * Note: The term "NMR" (meaning Normalized Message Router) is used here to refer
+ * to the messaging system of the JBI implementation. This term is used as a
+ * synonym for the JBI implementation, and refers only to the logical message
+ * routing functions of a JBI implementation. It is not meant to require that
+ * JBI implementations literally have a subsystem named "NMR".
+ *
+ * @author JSR208 Expert Group
+ */
 public interface ComponentContext {
+
+    /**
+     * Activates the named endpoint with the NMR. Activation indicates to the NMR
+     * that this component is ready to process requests sent to the named endpoint.
+     *
+     * Note that the JBI implementation may call this component's
+     * {@link Component#getServiceDescription(ServiceEndpoint)} method before returning
+     * from this method call; the component's implementation must be ready to supply
+     * service description metadata before the result of this activation call (a
+     * ServiceEndpoint) is known.
+     *
+     * @param serviceName qualified name of the service the endpoint exposes; must
+     *                    be non-null.
+     * @param endpointName the name of the endpoint to be activated; must be non-null
+     *                     and non-empty.
+     * @return a reference to the activated endpoint; must be non-null.
+     * @throws JBIException if the endpoint cannot be activated.
+     */
     ServiceEndpoint activateEndpoint(QName serviceName, String endpointName) throws JBIException;
 
+
+    /**
+     * Deactivates the given endpoint with the NMR. Deactivation indicates to the NMR
+     * that this component will no longer process requests sent to the named endpoint.
+     *
+     * @param endpoint reference to the endpoint to be deactivated; must be non-null.
+     * @throws JBIException if the endpoint cannot be deactivated.
+     */
     void deactivateEndpoint(ServiceEndpoint endpoint) throws JBIException;
 
+    /**
+     * Registers the given external endpoint with the NMR. This indicates to the NMR that
+     * the given endpoint is used as a proxy for external service consumers to access an
+     * internal service of the same service name (but a different endpoint name).
+     *
+     * @param externalEndpoint the external endpoint to be registered, must be non-null.
+     * @throws JBIException if an external endpoint with the same name is already registered,
+     *                      by this or another component.
+     */
     void registerExternalEndpoint(ServiceEndpoint externalEndpoint) throws JBIException;
 
+    /**
+     * Deregisters the given external endpoint with the NMR. This indicates to the NMR that
+     * the given external endpoint can no longer be used as a proxy for external service
+     * consumers to access an internal service of the same service name.
+     *
+     * @param externalEndpoint the external endpoint to be deregistered; must be non-null.
+     * @throws JBIException if the given external endpoint was not previously registered.
+     */
     void deregisterExternalEndpoint(ServiceEndpoint externalEndpoint) throws JBIException;
 
+    /**
+     * Resolve the given endpoint reference into a service endpoint. This is called by the
+     * component when it has an EPR that it wants to resolve into a service endpoint.
+     *
+     * Note that the service endpoint returned refers to a dynamic endpoint; the endpoint
+     * will exist only as long as this component retains a strong reference to the object
+     * returned by this method. The endpoint may not be included in the list of "activated"
+     * endpoints.
+     *
+     * @param epr endpoint reference as an XML fragment; must be non-null.
+     * @return the service endpoint corresponding to the given endpoint reference; null if
+     *         the reference cannot be resolved.
+     */
     ServiceEndpoint resolveEndpointReference(DocumentFragment epr);
 
+    /**
+     * Get the unique component name of this component, ass assigned by the identification
+     * section of this component's installation descriptor.
+     *
+     * @return the component name; must be non-null and non-empty.
+     */
     String getComponentName();
 
+    /**
+     * Get a channel for this component to use to communicate with the Normalized Message
+     * Router. This channel must be used by the component to send and receive message
+     * exchanges.
+     *
+     * @return the delivery channel for this component; must be non-null.
+     * @throws MessagingException if a channel has already been opened, but not yet closed.
+     */
     DeliveryChannel getDeliveryChannel() throws MessagingException;
 
+    /**
+     * Get the service endpoint for the named activated endpoint, if any.
+     *
+     * @param service qualified-name of the endpoint's service; must be non-null.
+     * @param name name of the endpoint; must be non-null.
+     * @return the named endpoint, or null if the named endpoint is not activated.
+     */
     ServiceEndpoint getEndpoint(QName service, String name);
 
+    /**
+     * Retrieve the service description metadata for the specified endpoint.
+     *
+     * Note that the result can use either the WSDL 1.1 or WSDL 2.0 description language.
+     *
+     * @param endpoint endpoint reference; must be non-null.
+     * @return metadata describing endpoint, or null if metadata is unavailable.
+     * @throws JBIException invalid endpoint reference.
+     */
     Document getEndpointDescriptor(ServiceEndpoint endpoint) throws JBIException;
 
+    /**
+     * Queries the NMR for active endpoints that implement the given interface. This
+     * will return the endpoints for all services and endpoints that implement the
+     * named interface (portType in WSDL 1.1). This method does NOT include external
+     * endpoints (those registered using {@link #registerExternalEndpoint(ServiceEndpoint)}).
+     *
+     * @param interfaceName qualified name of interface/portType that is implemented
+     *                      by the endpoint; if null then all activated endpoints in
+     *                      the JBI environment must be returned.
+     * @return an array of available endpoints for the specified interface name; must
+     *         be non-null; may be empty.
+     */
     ServiceEndpoint[] getEndpoints(QName interfaceName);
 
+    /**
+     * Queries the NMR for active endpoints belonging to the given service. This
+     * method does NOT include external endpoints (those registered using
+     * {@link #registerExternalEndpoint(ServiceEndpoint)}).
+     *
+     * @param serviceName qualified name of the service that the endpoints are part
+     *                    of; must be non-null.
+     * @return an array of available endpoints for the specified service name; must
+     *         be non-null; may be empty.
+     */
     ServiceEndpoint[] getEndpointsForService(QName serviceName);
 
+    /**
+     * Queries the NMR for external endpoints that implement the given interface name.
+     * This methods returns only registered external endpoints (see
+     * {@link #registerExternalEndpoint(ServiceEndpoint)}).
+     *
+     * @param interfaceName qualified name of interface implemented by the endpoints;
+     *                      must be non-null.
+     * @return an array of available external endpoints for the specified interface name;
+     *         must be non-null; may be empty.
+     */
     ServiceEndpoint[] getExternalEndpoints(QName interfaceName);
 
+    /**
+     * Queries the NMR for external endpoints that are part of the given service.
+     *
+     * @param serviceName qualified name of service that contains the endpoints;
+     *                    must be non-null.
+     * @return an array of available external endpoints for the specified service name;
+     *         must be non-null; may be empty.
+     */
     ServiceEndpoint[] getExternalEndpointsForService(QName serviceName);
 
+    /**
+     * Get the installation root directory path for this component.
+     *
+     * This method MUST return the file path formatted for the underlying platform.
+     *
+     * @return the installation root directory path, in platform-specific form;
+     *         must be non-null and non-empty.
+     */
     String getInstallRoot();
 
+    /**
+     * Get a logger instance from JBI. Loggers supplied by JBI are guaranteed to have
+     * unique names such that they avoid name collisions with loggers from other
+     * components created using this method. The suffix parameter allows for the
+     * creation of subloggers as needed. The JBI specification says nothing about
+     * the exact names to be used, only that they must be unique across components
+     * and the JBI implementation itself.
+     *
+     * @param suffix for creating subloggers; use an empty string for the base component
+     *               logger; must be non-null.
+     * @param resourceBundleName name of ResourceBundle to be used for localizing messages
+     *                           for the logger. May be null if none of the messages require
+     *                           localization. The resource, if non-null, must be loadable
+     *                           using the component's class loader as the initiating loader.
+     * @return a standard logger, named uniquely for this component (plus the given suffix,
+     *         if applicable); must be non-null.
+     * @throws java.util.MissingResourceException if the ResourceBundleName is non-null and no
+     *                                            corresponding resource can be found.
+     * @throws JBIException if the resourceBundleName has changed from a previous invocation
+     *                      by this component of this method with the same suffix.
+     */
     Logger getLogger(String suffix, String resourceBundleName) throws MissingResourceException, JBIException;
 
+    /**
+     * Get a reference to the MBeanNames creator for use in creating custom MBean names.
+     *
+     * @return reference to the MBeanNames creator; must be non-null.
+     */
     javax.jbi.management.MBeanNames getMBeanNames();
 
+    /**
+     * Get the JMX MBean server used to register all MBeans in the JBI environment.
+     *
+     * @return a reference to the MBean server; must be non-null.
+     */
     javax.management.MBeanServer getMBeanServer();
 
+    /**
+     * Get the JNDI naming context for this component. This context is a standard JNDI
+     * InitialContext but its content will vary based on the environment in which the JBI
+     * implementation is running.
+     * 
+     * @return the JNDI naming context; must be non-null.
+     */
     javax.naming.InitialContext getNamingContext();
 
+    /**
+     * Get the TransactionManager for this implementation. The instance returned is an
+     * implementation of the standard JTA interface. If none is available, this method
+     * returns null.
+     *
+     * The object returned by this method is untyped, to allow this interface to be compiled
+     * in environments that do not support JTA. If not null, the object returned must be of
+     * type javax.transaction.TransactionManager.
+     *
+     * This downcast is necessary because JBI is used in environments that do not support
+     * JTA (i.e., J2SE). Explicit use of JTA types would cause compilation failures in
+     * such environments.
+     *
+     * @return A TransactionManager instance, or null if none is available in the
+     *         execution environment.
+     */
     Object getTransactionManager();
 
+    /**
+     * Get the root directory path for this component's private workspace.
+     *
+     * This method MUST return the file path formatted for the underlying platform.
+     *
+     * The returned value must indicate a valid file path that the component may use
+     * to write files to, and read files from.
+     *
+     * @return the private workspace root path, in platform-specific form;
+     *         must be non-null and non-empty.
+     */
     String getWorkspaceRoot();
 
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ComponentLifeCycle.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ComponentLifeCycle.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ComponentLifeCycle.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ComponentLifeCycle.java Fri Mar  7 08:54:00 2008
@@ -17,17 +17,80 @@
 package javax.jbi.component;
 
 import javax.jbi.JBIException;
-
 import javax.management.ObjectName;
 
+/**
+ * This interface must be implemented by a JBI component to provide initialization,
+ * start, stop, and shutdown life cycle processing. These methods comprise the life
+ * cycle contract between the JBI implementation and the component. The life cycle
+ * of a component begins with a call to the init() method on an instance of the
+ * component's implementation of this interface, and ends with the first call to the
+ * shutDown() method on that instance. Between these two calls, there can be any
+ * number of stop() and start() calls.
+ *
+ * The JBI implementation must track the running state of a component, and ensure
+ * that life cycle state changes are always legal. For example, if the management
+ * interface for controlling a component's life cycle ({@link
+ * javax.jbi.management.ComponentLifeCycleMBean}) is used to start a component that
+ * was just installed (and thus in the <i>Shutdown</i> state), the implementation
+ * must invoke this component's {@link #init(ComponentContext)} method before
+ * invoking its {@link #start()} method.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface ComponentLifeCycle {
+
+    /**
+     * Get the JMX object name for the extension MBean for this component; if there
+     * is none, return null.
+     *
+     * @return the JMX object name of the additional MBean or null if there is no
+     *         additional MBean.
+     */
     ObjectName getExtensionMBeanName();
 
+    /**
+     * Initialize the component. This performs initialization required by the component
+     * but does not make it ready to process messages. This method is called once for
+     * each life cycle of the component.
+     *
+     * If the component needs to register an additional MBean to extend its life cycle,
+     * or provide other component management tasks, it should be registered during this
+     * call.
+     *
+     * @param context the component's context, providing access to component data provided
+     *                by the JBI environment; must be non-null.
+     * @throws JBIException if the component is unable to initialize.
+     */
     void init(ComponentContext context) throws JBIException;
 
+    /**
+     * Shut down the component. This performs clean-up, releasing all run-time resources
+     * used by the component. Once this method has been called, {@link #init(ComponentContext)}
+     * must be called before the component can be started again with a call to {@link #start()}.
+     *
+     * @throws JBIException if the component is unable to shut down.
+     */
     void shutDown() throws JBIException;
 
+    /**
+     * Start the component. This makes the component ready to process messages. This method
+     * is called after {@link #init(ComponentContext)}, both when the component is being
+     * started for the first time and when the component is being restarted after a previous
+     * call to {@link #shutDown()}. If {@link #stop()} was called previously but {@link #shutDown()}
+     * was not, {@link #start()} can be called again without another call to
+     * {@link #init(ComponentContext)}.
+     *
+     * @throws JBIException if the component is unable to start.
+     */
     void start() throws JBIException;
 
+    /**
+     * Stop the component. This makes the component stop accepting messages for processing.
+     * After a call to this method, {@link #start()} may be called again without first
+     * calling {@link #init(ComponentContext)}.
+     *
+     * @throws JBIException if the component is unable to stop.
+     */
     void stop() throws JBIException;
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/InstallationContext.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/InstallationContext.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/InstallationContext.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/InstallationContext.java Fri Mar  7 08:54:00 2008
@@ -18,20 +18,119 @@
 
 import org.w3c.dom.DocumentFragment;
 
+/**
+ * This context contains information necessary for a JBI component to perform
+ * its installation/uninstallation processing.
+ */
 public interface InstallationContext {
+
+    /**
+     * Get the name of the class that implements the {@link Component}
+     * interface for this component. This must be the component class name
+     * given in the component's installation descriptor.
+     *
+     * @return the {@link Component} implementation class name, which
+     *         must be non-null and non-empty.
+     */
     String getComponentClassName();
 
+    /**
+     * Get a list of elements that comprise the class path for this component.
+     * Each element represents either a directory (containing class files) or
+     * a library file. All elements are reachable from the install root. These
+     * elements represent class path items that the component's execution-time
+     * component class loader uses, in search order. All path elements must use
+     * the file separator character appropriate to the system (i.e.,
+     * <code>File.separator</code>).
+     * 
+     * @return a list of String objects, each of which contains a class path
+     *         elements. The list must contain at least one class path element.
+     */
     java.util.List getClassPathElements();
 
+    /**
+     * Get the unique name assigned to this component. This name must be assigned
+     * from the component's installation descriptor identification section.
+     *
+     * @return the unique component name, which must be non-null and non-empty.
+     */
     String getComponentName();
 
+    /**
+     * Get the JBI context for this component. The following methods are valid
+     * to use on the context:
+     * <ul>
+     *   <li>{@link ComponentContext#getLogger(String, String)}</li>
+     *   <li>{@link ComponentContext#getMBeanNames()}</li>
+     *   <li>{@link ComponentContext#getMBeanServer()}</li>
+     *   <li>{@link ComponentContext#getNamingContext()}</li>
+     *   <li>{@link ComponentContext#getTransactionManager()}</li>
+     * </ul>
+     *
+     * All other methods on the returned context must throw a IllegalStateException
+     * exception if invoked.
+     *
+     * @return the JBI context for this component, which must be non-null.
+     */
     ComponentContext getContext();
 
+    /**
+     * Get the installation root directory full path name for this component.
+     * This path name must be formatted for the platform the JBI environment
+     * is running on.
+     *
+     * @return the installation root directory name, which must be non-null
+     *         and non-empty.
+     */
     String getInstallRoot();
 
+    /**
+     * Return a DOM document fragment representing the installation descriptor
+     * (jbi.xml) extension data for the component, if any.
+     *
+     * The Installation Descriptor Extension data are located at the end of the
+     * <component> element of the installation descriptor.
+     *
+     * @return a DOM document fragment containing the installation descriptor
+     *         (jbi.xml) extension data, or null if none is present in the descriptor.
+     */
     DocumentFragment getInstallationDescriptorExtension();
 
+    /**
+     * Returns <code>true</code> if this context was created in order to install a
+     * component into the JBI environment. Returns false if this context was created
+     * to uninstall a previously installed component.
+     *
+     * This method is provided to allow Bootstrap implementations to tailor their
+     * behaviour according to use case. For example, the
+     * {@link Bootstrap#init(InstallationContext)} method implementation may create
+     * different types of extension MBeans, depending on the use case specified by
+     * this method.
+     *
+     * @return <code>true</code> if this context was created in order to install a
+     *         component into the JBI environment; otherwise the context was created
+     *         to uninstall an existing component.
+     */
     boolean isInstall();
 
+    /**
+     * Set the list of elements that comprise the class path for this component. Each
+     * element represents either a directory (containing class files) or a library file.
+     * Elements are reached from the install root. These elements represent class path
+     * items that the component's execution-time component class loader uses, in search
+     * order. All file paths are relative to the install root of the component.
+     *
+     * This method allows the component's bootstrap to alter the execution-time class
+     * path specified by the component's installation descriptor. The component
+     * configuration determined during installation can affect the class path needed by
+     * the component at execution-time. All path elements must use the file separator
+     * character appropriate to the system (i.e., <code>File.separator</code>).
+     *
+     * @param classPathElements a list of String objects, each of which contains a class
+     *        path elements; the list must be non-null and contain at least one class path
+     *        element.
+     * @throws java.lang.IllegalArgumentException if the class path elements is null, empty,
+     *                                            or if an individual element is ill-formed.
+     */
     void setClassPathElements(java.util.List classPathElements);
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ServiceUnitManager.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ServiceUnitManager.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ServiceUnitManager.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/component/ServiceUnitManager.java Fri Mar  7 08:54:00 2008
@@ -18,16 +18,129 @@
 
 import javax.jbi.management.DeploymentException;
 
+/**
+ * This interface defines component-supplied methods for managing service
+ * unit deployments, and is implemented by the component. The JBI
+ * implementation queries the component for the implementation of this
+ * interface using the {@link Component#getServiceUnitManager()} method.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface ServiceUnitManager {
+
+    /**
+     * Deploy a Service Unit to the component. This is called by the JBI
+     * implementation in order to deploy the given artifact to the implementing
+     * component.
+     *
+     * Upon successful deployment, a non-empty result string must be returned,
+     * that starts with the JBI-defined component-task-result element. For example:
+     * <pre>
+     * &lt;component-task-result&gt;
+     *   &lt;component-name&gt;BC1&lt;/component-name&gt;
+     *   &lt;component-task-result-details
+     *     xmlns="http://java.sun.com/xml/ns/jbi/management-message"&gt;
+     *       &lt;task-result-details&gt;
+     *           &lt;task-id>deploy&lt;/task-id&gt;
+     *           &lt;task-result>SUCCESS&lt;/task-result&gt;
+     *       &lt;/task-result-details&gt;
+     *   &lt;/component-task-result-details&gt;
+     * &lt;/component-task-result&gt;
+     * </pre>
+     * A failed deployment of the service unit must be reported using the
+     * <code>component-task-result</code> element as well; the
+     * <code>task-result</code> must be set to FAILED.
+     *
+     * @param serviceUnitName name of the service unit being deployed; must be
+     *        non-null and non-empty and unique among service units already
+     *        deployed to the component.
+     * @param serviceUnitRootPath path of the service unit artifact root, in
+     *        platform specific format; must be non-null and non-empty.
+     * @return a deployment status message, which is an XML string that conforms
+     *         to the schema given in the <i>MBean Status and Result Strings</i>
+     *         section of the <i><b>Management</b></i> chapter of the JBI
+     *         specification; must be non-null and non-empty.
+     * @exception DeploymentException if the deployment operation is
+     *            unsuccessful.
+      */
     String deploy(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException;
 
+    /**
+     * Initialize the given deployed service unit. This is the first phase of
+     * a two-phase start, where the component must prepare to receive service
+     * requests related to the deployment (if any).
+     * <p>
+     * The serviceUnitRootPath parameter is provided to facilitate restart of
+     * the component. This allows simple components to rely entirely on JBI's
+     * ability to persist deployment information, avoiding the need for the
+     * component to provide its own persistence mechanism.
+     *
+     * @param serviceUnitName name of the service unit being initialized; must
+     *        be non-null, non-empty, and match the name of a previously
+     *        deployed (but not yet undeployed) service unit.
+     * @param serviceUnitRootPath path of the service unit artifact root, in
+     *        platform specific format; must be non-null and non-empty.
+     * @exception DeploymentException if the service unit is not deployed, or
+     *            if it is in an incorrect state.
+     */
     void init(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException;
 
+    /**
+     * Start the deployed service unit. This is the second phase of a two-phase
+     * start, where the component can now initiate service requests related to
+     * the deployment.
+     *
+     * @param serviceUnitName the name of the service unit being started; must
+     *        be non-null, non-empty, and match the name of a previously
+     *        deployed (but not yet undeployed) service unit.
+     * @exception DeploymentException if the service unit is not deployed, or
+     *           if it is in an incorrect state.
+     */
     void start(String serviceUnitName) throws DeploymentException;
 
+    /**
+     * Stop the deployed service unit. This causes the component to cease
+     * generating service requests related to the given service unit. This
+     * returns the service unit to a state equivalent to after
+     * {@link #init(String, String)} was called.
+     *
+     * @param serviceUnitName name of the service unit being stopped; must
+     *        be non-null, non-empty, and match the name of a previously
+     *        deployed (but not yet undeployed) service unit.
+     * @exception DeploymentException if the service unit is not deployed, or
+     *            if it is in an incorrect state.
+     */
     void stop(String serviceUnitName) throws DeploymentException;
 
+    /**
+     * Shut down the deployment. This causes the deployment to return to the
+     * to the state it was in after {@link #deploy(String, String)}, and before
+     * {@link #init(String, String)}.
+     *
+     * @param serviceUnitName name of the service unit being shut down; must
+     *        be non-null, non-empty, and match the name of a previously
+     *        deployed (but not yet undeployed) service unit.
+     * @exception DeploymentException if the service unit is not deployed, or
+     *            if it is in an incorrect state.
+     */
     void shutDown(String serviceUnitName) throws DeploymentException;
 
+    /**
+     * Undeploy a service unit from the component. The service unit must be
+     * shut down to undeploy it.
+     *
+     * @param serviceUnitName name of the service unit being undeployed; must
+     *        be non-null, non-empty, and match the name of a previously
+     *        deployed (but not yet undeployed) service unit.
+     * @param serviceUnitRootPath path of the service unit artifact root, in
+     *        platform specific format; must be non-null and non-empty.
+     * @return deployment status message, which is an XML string that conforms
+     *         to the <code>component-task-result</code> type from
+     *         the schema given in the <i>MBean Status and Result Strings</i>
+     *         section of the <i><b>Management</b></i> chapter of the JBI
+     *         specification; must be non-null and non-empty.
+     * @exception DeploymentException if undeployment operation is unsuccessful,
+     *            or if the service unit is in an incorrect state.
+     */
     String undeploy(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException;
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/AdminServiceMBean.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/AdminServiceMBean.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/AdminServiceMBean.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/AdminServiceMBean.java Fri Mar  7 08:54:00 2008
@@ -18,20 +18,119 @@
 
 import javax.management.ObjectName;
 
+/**
+ * This interface defines a set of administrative methods allowing a JMX-based
+ * administrative tool to perform a variety of administrative tasks.
+ * <ul>
+ *   <li>Find component lifecycle MBean names for:
+ *     <ul>
+ *       <li>Individual components, by name</li>
+ *       <li>All binding components</li>
+ *       <li>All service engines</li>
+ *     </ul>
+ *   </li>
+ *   <li>Find lifecyle MBeans names for implementation-defined services:
+ *     <ul>
+ *       <li>Individual implementation services, by name</li>
+ *       <li>All implementation services</li>
+ *     </ul>
+ *   </li>
+ *   <li>Query whether an individual component is a binding or engine</li>
+ *   <li>Query implementation information (version etc.)</li>
+ * </ul>
+ *
+ * @author JSR208 Expert Group
+ */
 public interface AdminServiceMBean {
+
+    /**
+     * Get a list of {@link ComponentLifeCycleMBean}s for all binding components
+     * currently installed in the JBI system.
+     *
+     * @return array of JMX object names of component life cycle MBeans for all
+     *         installed binding components; must be non-null; may be empty
+     */
     ObjectName[] getBindingComponents();
 
+    /**
+     * Find the {@link ComponentLifeCycleMBean} of a JBI Installable Component
+     * by its unique name.
+     *
+     * @param name the name of the engine or binding component; must be non-
+     *        null and non-empty
+     * @return the JMX object name of the component's life cycle MBean, or
+     *         <code>null</code> if there is no such component with the given
+     *         <code>name</code>
+     */
     ObjectName getComponentByName(String name);
 
+    /**
+     * Get a list of {@link ComponentLifeCycleMBean}s for all service engines
+     * currently installed in the JBI system.
+     *
+     * @return array of JMX object names of component life cycle MBeans for all
+     *         installed service engines; must be non-null; may be empty
+     */
     ObjectName[] getEngineComponents();
 
+    /**
+     * Return current version and other info about this JBI implementation. The
+     * contents of the returned string are implementation dependent.
+     *
+     * @return information string about the JBI implementation, including
+     *         version information; must be non-null and non-empty
+     */
     String getSystemInfo();
 
+    /**
+     * Lookup a system service {@link LifeCycleMBean} by name. System services
+     * are implementation-defined services which can administered through JMX,
+     * and have a life cycle.
+     * <p>
+     * System services are not related to service engines.
+     *
+     * @param serviceName name of the system service; must be non-null and non-
+     *        empty; values are implementation-dependent
+     * @return JMX object name of the system service's LifeCycleMBean, or
+     *         <code>null</code> if there is no system service with the given
+     *         <code>name</code>.
+     */
     ObjectName getSystemService(String serviceName);
 
+    /**
+     * Looks up all JBI system services {@link LifeCycleMBean}'s currently
+     * installed. System services are implementation-defined services which can
+     * administered through JMX. System services are not related to service
+     * engines.
+     *
+     * @return array of LifecycleMBean JMX object names of system services
+     *         currently installed in the JBI implementation; must be non-null;
+     *         may be empty
+     */
     ObjectName[] getSystemServices();
 
+    /**
+     * Check if a given JBI component is a Binding Component.
+     *
+     * @param componentName the unique name of the component; must be non-null
+     *        and non-empty
+     * @return <code>true</code> if the component is a binding component;
+     *         <code>false</code> if the component is a service engine or if
+     *         there is no component with the given <code>componentName</code>
+     *         installed in the JBI system
+     */
     boolean isBinding(String componentName);
 
+    /**
+     * Check if a given JBI component is a Service Engine.
+     *
+     * @param componentName the unique name of the component; must be non-null
+     *        and non-empty
+     * @return <code>true</code> if the component is a service engine;
+     *         <code>false</code> if the component is a binding component, or if
+     *         there is no component with the given <code>componentName</code>
+     *         installed in the JBI system
+     */
     boolean isEngine(String componentName);
+
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/ComponentLifeCycleMBean.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/ComponentLifeCycleMBean.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/ComponentLifeCycleMBean.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/ComponentLifeCycleMBean.java Fri Mar  7 08:54:00 2008
@@ -18,6 +18,34 @@
 
 import javax.management.ObjectName;
 
+/**
+ * ComponentLifeCycleMBean defines the standard life cycle controls for
+ * JBI Installable Components.
+ * <ul>
+ *   <li>Initialize the component, preparing it to receive service requests.</li>
+ *   <li>Start the component, allowing it to initiate service requests.</li>
+ *   <li>Stop the component from initiating any more service requests.</li>
+ *   <li>Shut down the component, returning it to the uninitialized state
+ *       where it cannot receive service requests.</li>
+ *   <li>Query the JMX object name of the extension MBean for the component.</li>
+ * </ul>
+ *
+ * @author JSR208 Expert Group
+ */
 public interface ComponentLifeCycleMBean extends LifeCycleMBean {
+
+    /**
+     * Get the JMX ObjectName for the life cycle extension MBean for this
+     * component. If there is none, return <code>null</code>.
+     * Note that this MBean may serve as a container for multiple MBeans,
+     * as required by the component implementation.
+     *
+     * @return ObjectName the JMX object name of the additional MBean
+     *         or <code>null</code> if there is no additional MBean.
+     * @exception javax.jbi.JBIException if there is a failure getting component
+     *            information for the component to which this life cycle
+     *            applies.
+     */
     ObjectName getExtensionMBeanName() throws javax.jbi.JBIException;
+
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/DeploymentException.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/DeploymentException.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/DeploymentException.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/DeploymentException.java Fri Mar  7 08:54:00 2008
@@ -16,15 +16,44 @@
  */
 package javax.jbi.management;
 
+/**
+ * DeploymentException is an exception thrown by the Deployment Service and
+ * the Service Unit Manager.
+ *
+ * @author JSR208 Expert Group
+ */
 public class DeploymentException extends javax.jbi.JBIException {
+
+    /**
+     * Creates a new instance of DeploymentException with an exception detail
+     * message.
+     *
+     * @param aMessage the detail message for this exception.
+     */
     public DeploymentException(String aMessage) {
         super(aMessage);
     }
 
+    /**
+     * Creates a new instance of DeploymentException with and exception detail
+     * message and a cause.
+     *
+     * @param aMessage the detail message for this exception.
+     * @param aCause <code>Error</code> or <code>Exception</code> which
+     *        represents the cause of the problem (<code>null</code> if none,
+     *        or if the cause is not known).
+     */
     public DeploymentException(String aMessage, Throwable aCause) {
         super(aMessage, aCause);
     }
 
+    /**
+     * Creates a new instance of DeploymentException with the specified cause.
+     *
+     * @param aCause <code>Error</code> or <code>Exception</code> which
+     *        represents the cause of the problem (<code>null</code> if none,
+     *        or if the cause is not known).
+     */
     public DeploymentException(Throwable aCause) {
         super(aCause);
     }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/DeploymentServiceMBean.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/DeploymentServiceMBean.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/DeploymentServiceMBean.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/DeploymentServiceMBean.java Fri Mar  7 08:54:00 2008
@@ -16,37 +16,219 @@
  */
 package javax.jbi.management;
 
+/**
+ * The deployment service MBean allows administrative tools to manage
+ * service assembly deployments. The tasks supported are:
+ * <ul>
+ *   <li>Deploying a service assembly.</li>
+ *   <li>Undeploying a previously deployed service assembly.</li>
+ *   <li>Querying deployed service assemblies:
+ *     <ul>
+ *       <li>For all components in the system.</li>
+ *       <li>For a particular component.</li>
+ *     </ul>
+ *   </li>
+ *   <li>Control the state of deployed service assemblies:
+ *     <ul>
+ *       <li>Start the service units that contained in the SA.</li>
+ *       <li>Stop the service units that contained in the SA. </li>
+ *       <li>Shut down the service units that contained in the SA.</li>
+ *     </ul>
+ *   </li>
+ *   <li>Query the service units deployed to a particular component.</li>
+ *   <li>Check if a service unit is deployed to a particular component.</li>
+ *   <li>Query the deployment descriptor for a particular service assembly.</li>
+ * </ul>
+ *
+ * @author JSR208 Expert Group
+ */
 public interface DeploymentServiceMBean {
 
+    /**
+     * The service assembly is started. This means that the assembly's offered
+     * services can accept message exchanges, and it can send exchanges to
+     * consume services.
+     */
     String STARTED = "Started";
 
-    String SHUTDOWN = "Shutdown";
-
+    /**
+     * The service assembly has been deployed, or shutdown
+     */
+     String SHUTDOWN = "Shutdown";
+
+    /**
+     * The service assembly is stopped. This means that the assembly's offered
+     * services can accept message exchanges, but it will not send any.
+     */
     String STOPPED = "Stopped";
 
+    /**
+     * Deploys the given Service Assembly to the JBI environment.
+     * <p>
+     * Note that the implementation must not automatically start the service
+     * assembly after deployment; it must wait for the {@link #start(String)}
+     * method to be invoked by the administrative tool.
+     *
+     * @param saZipURL String containing the location URL of the
+     *        Service Assembly ZIP file; must be non-null, non-empty, and a
+     *        legal URL
+     * @return Result/Status of the current deployment; must conform to
+     *         JBI management result/status XML schema; must be non-null and
+     *         non-empty
+     * @exception Exception if complete deployment fails
+     */
     String deploy(String saZipURL) throws Exception;
 
+    /**
+     * Undeploys the given Service Assembly from the JBI environment.
+     *
+     * @param saName name of the Service Assembly that is to be 
+     *        undeployed; must be non-null and non-empty
+     * @return Result/Status of the current undeployment; must conform to
+     *         JBI management result/status XML schema; must be non-null and
+     *         non-empty
+     * @exception Exception if compelete undeployment fails
+     */
     String undeploy(String saName) throws Exception;
 
+    /**
+     * Returns an array of service unit names that are currently deployed to
+     * the named component.
+     *
+     * @param componentName the name of the component to query; must be
+     *        non-null and non-empty
+     * @return array of service unit names deployed in the named component;
+     *         must be non-null; may be empty
+     * @exception Exception if a processing error occurs
+     */
     String[] getDeployedServiceUnitList(String componentName) throws Exception;
 
+    /**
+     * Returns a list of Service Assemblies deployed to the JBI environment.
+     *
+     * @return list of Service Assembly names; must be non-null; may be
+     *         empty
+     * @exception Exception if a processing error occurs
+     */
     String[] getDeployedServiceAssemblies() throws Exception;
 
+    /**
+     * Returns the deployment descriptor of the Service Assembly that was
+     * deployed to the JBI enviroment, serialized to a <code>String</code>.
+     *
+     * @param saName name of the service assembly to be queried;
+     *        must be non-null and non-empty
+     * @return descriptor of the Assembly Unit; must be non-null
+     * @exception Exception if a processing error occurs
+     */
     String getServiceAssemblyDescriptor(String saName) throws Exception;
 
+    /**
+     * Returns an array of Service Assembly names, where each assembly contains
+     * Service Units for the given component.
+     *
+     * @param componentName name of the component to query; must be non-null
+     *        and non-empty
+     * @return array of of Service Assembly names, where each assembly contains
+     *         a Service Unit for the named component; must be non-null; may
+     *         be empty
+     * @exception Exception if a processing error occurs
+     */
     String[] getDeployedServiceAssembliesForComponent(String componentName) throws Exception;
 
+    /**
+     * Returns an array of component names, where for each the given assembly
+     * contains a service unit for the component.
+     *
+     * @param saName the service assembly to be queried; must be
+     *        non-null and non-empty
+     * @return array of component names, where for each name the given assembly
+     *         contains a service unit from the given service assembly; must
+     *         be non-null; may be empty
+     * @exception Exception if a processing error occurs
+     */
     String[] getComponentsForDeployedServiceAssembly(String saName) throws Exception;
 
+    /**
+     * Queries if the named Service Unit is currently deployed to the named
+     * component.
+     *
+     * @param componentName name of the component to query; must be non-null
+     *        and non-empty
+     * @param suName name of the subject service unit; must be non-null
+     *        and non-empty
+     * @return <code>true</code> if the named service unit is currently deployed
+     *         to the named component
+     */
     boolean isDeployedServiceUnit(String componentName, String suName) throws Exception;
 
+    /**
+     * Returns <code>true</code> if the the given component accepts the
+     * deployment of service units. This is used by admin tools to
+     * determine which components can be named in service assembly
+     * deployment descriptors.
+     *
+     * @param componentName name of the component; must be non-null and
+     *        non-empty
+     * @return <code>true</code> if the named component accepts deployments;
+     *         <code>false</code> if the named component does not accept
+     *         deployments or it does not exist
+     *
+     */
     boolean canDeployToComponent(String componentName);
 
+    /**
+     * Start the service assembly. This puts the assembly into the {@link
+     * #STARTED} state.
+     *
+     * @param serviceAssemblyName name of the assembly to be started; must be
+     *        non-null and non-empty
+     * @return result / status string giving the results of starting (and
+     *         possibly initializing) each service unit in the assembly; must
+     *         be non-null and non-empty
+     * @exception Exception if there is no such assembly
+     * @exception Exception if the assembly fails to start
+     *
+     */
     String start(String serviceAssemblyName) throws Exception;
 
+    /**
+     * Stop the service assembly. This puts the assembly into the {@link
+     * #STOPPED} state.
+     *
+     * @param serviceAssemblyName name of the assembly to be stopped; must be
+     *        non-null and non-empty
+     * @return result / status string giving the results of stopping each
+     *         service unit in the assembly; must be non-null and non-empty
+     * @exception Exception if there is no such assembly
+     * @exception Exception if the assembly fails to stop
+     */
     String stop(String serviceAssemblyName) throws Exception;
 
+    /**
+     * Shut down the service assembly. This puts the assembly back into the
+     * {@link #SHUTDOWN} state.
+     *
+     * @param serviceAssemblyName name of the assembly to be shut down; must be
+     *        non-null and non-empty
+     * @return result / status string giving the results of shutting down
+     *         each service unit in the assembly; must be non-null and non-empty
+     * @exception Exception if there is no such assembly
+     * @exception Exception if the assembly fails to shut down
+     */
     String shutDown(String serviceAssemblyName) throws Exception;
 
+    /**
+     * Get the running state of a service assembly. The possible result values
+     * of this query are enumerated by the following set of constants:
+     * {@link #SHUTDOWN}, {@link #STOPPED}, {@link #STARTED}.
+     *
+     * @param serviceAssemblyName name of the assembly to query; must be
+     *        non-null and non-empty
+     * @return the state of the service assembly, as a string value; must be one
+     *         of the enumerated string values provided by this interface:
+     *         {@link #SHUTDOWN}, {@link #STOPPED}, or {@link #STARTED}
+     * @exception Exception if there is no such assembly
+     */
     String getState(String serviceAssemblyName) throws Exception;
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/InstallationServiceMBean.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/InstallationServiceMBean.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/InstallationServiceMBean.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/InstallationServiceMBean.java Fri Mar  7 08:54:00 2008
@@ -18,14 +18,84 @@
 
 import javax.management.ObjectName;
 
+/**
+ * The installation service MBean allows administrative tools to manage
+ * component and shared library installations.  The tasks supported are:
+ * <ul>
+ *   <li>Installing (and uninstalling) a shared library</li>
+ *   <li>Creating (loading) and destroying (unloading) a component installer
+ *       MBean.</li>
+ *   <li>Finding an existing component installer MBean.
+ * </ul>
+ *
+ * Installing and uninstalling components is accomplished using
+ * {@link InstallerMBean}s, loaded by this MBean.  An individual installer MBean
+ * is needed for each component installation / uninstallation.  This is to support
+ * the more complex installation process that some components require.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface InstallationServiceMBean {
-    ObjectName loadNewInstaller(String installJarURL);
 
+    /**
+     * Load the installer for a new component for the given component
+     * installation package.
+     *
+     * @param installZipURL URL locating a ZIP file containing the
+     *        JBI Installation package to be installed; must be non-null,
+     *        non-empty, and a legal URL
+     * @return the JMX ObjectName of the InstallerMBean loaded from
+     *         installZipURL; must be non-null
+     */
+    ObjectName loadNewInstaller(String installZipURL);
+
+    /**
+     * Load the InstallerMBean for a previously installed component.
+     * <p>
+     * The "component name" refers to the
+     * <code>&lt;identification>&lt;name></code> element value from the
+     * component's installation package (see {@link #loadNewInstaller(String)}).
+     *
+     * @param aComponentName the component name identifying the installer to 
+     *        load; must be non-null and non-empty
+     * @return the JMX ObjectName of the InstallerMBean loaded from an existing
+     *         installation context; <code>null</code> if the installer MBean
+     *         doesn't exist
+     */
     ObjectName loadInstaller(String aComponentName);
 
+    /**
+     * Unload an InstallerMBean previously loaded for a component.
+     *
+     * @param aComponentName the component name identifying the installer to 
+     *        unload; must be non-null and non-empty
+     * @param isToBeDeleted <code>true</code> if the component is to be deleted
+     *        as well
+     * @return true if the operation was successful, otherwise false
+     */
     boolean unloadInstaller(String aComponentName, boolean isToBeDeleted);
 
+    /**
+     * Install a shared library installation package.
+     * <p>
+     * The return value is the unique name for the shared-library, as found
+     * in the the value of the installation descriptor's
+     * <code>&lt;identification>&lt;name></code> element.
+     *
+     * @param aSharedLibURI URL locating a zip file containing a shared library
+     *        installation package; must be non-null, non-empty, and a legal
+     *        URL
+     * @return the unique name of the shared library loaded from slZipURL; must
+     *         be non-null and non-empty
+     */
     String installSharedLibrary(String aSharedLibURI);
 
+    /**
+     * Uninstall a previously installed shared library.
+     *
+     * @param aSharedLibName the name of the shared name space to uninstall; must be
+     *        non-null and non-empty
+     * @return true if the uninstall was successful
+     */
     boolean uninstallSharedLibrary(String aSharedLibName);
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/InstallerMBean.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/InstallerMBean.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/InstallerMBean.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/InstallerMBean.java Fri Mar  7 08:54:00 2008
@@ -18,14 +18,70 @@
 
 import javax.management.ObjectName;
 
+/**
+ * The InstallerMBean defines standard installation and uninstallation controls
+ * for components. InstallerMBeans are created by the
+ * {@link InstallationServiceMBean}. The InstallerMBean offers controls to
+ * allow an administrative tool to:
+ * <ul>
+ *   <li>Install the component from the installation package.</li>
+ *   <li>Uninstall the component.</li>
+ *   <li>Check the installation status of the component.</li>
+ *   <li>Get the file path to the component's installation root directory.</li>
+ * </ul>
+ *
+ * @author JSR208 Expert Group
+ */
 public interface InstallerMBean {
+
+    /**
+     * Get the installation root directory path for this component.
+     *
+     * @return the full installation path of this component; this must be in
+     *         absolute path name form, in platform-specific format; must be
+     *         non-null and non-empty
+     */
     String getInstallRoot();
 
+    /**
+     * Install a component.
+     * <p>
+     * Note that the implementation must leave the component in its
+     * installed, shutdown state. Automatic starting of components during
+     * installation by implementations is not allowed.
+     *
+     * @return JMX ObjectName representing the LifeCycleMBean for the installed
+     *         component, or <code>null</code> if the installation did not
+     *         complete
+     * @exception javax.jbi.JBIException if the installation fails
+     */
     ObjectName install() throws javax.jbi.JBIException;
 
+    /**
+     * Determine whether or not the component is installed.
+     *
+     * @return <code>true</code> if this component is currently installed,
+     *         otherwise <code>false</code>
+     */
     boolean isInstalled();
 
+    /**
+     * Uninstall the component. This completely removes the component from the
+     * JBI system.
+     *
+     * @exception javax.jbi.JBIException if the uninstallation fails
+     */
     void uninstall() throws javax.jbi.JBIException;
 
+    /**
+     * Get the installer configuration MBean name for this component.
+     *
+     * @return the MBean object name of the Installer Configuration MBean;
+     *         <code>null</code> if none is provided by this component
+     * @exception javax.jbi.JBIException if the component is not in the
+     *            appropriate state (after install() but before life cycle
+     *            initialization), or if any error occurs during processing
+     */
     ObjectName getInstallerConfigurationMBean() throws javax.jbi.JBIException;
+
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/LifeCycleMBean.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/LifeCycleMBean.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/LifeCycleMBean.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/LifeCycleMBean.java Fri Mar  7 08:54:00 2008
@@ -18,22 +18,55 @@
 
 import javax.jbi.JBIException;
 
+/**
+ * LifeCycleMBean is a base interface that defines standard life cycle controls
+ * for JBI implementation services (which are implementation-specific), and JBI
+ * components (bindings and engines).
+ *
+ * @author JSR208 Expert Group
+ */
 public interface LifeCycleMBean {
 
+    /** Value returned by {@link #getCurrentState()} for a shutdown component. */
     String SHUTDOWN = "Shutdown";
 
+    /** Value returned by {@link #getCurrentState()} for a stopped component. */
     String STOPPED = "Stopped";
 
-    String STARTED = "Started";
+    /** Value returned by {@link #getCurrentState()} for a running component. */
+     String STARTED = "Started";
 
+    /** Value returned by {@link #getCurrentState()} for a component in an unknown state. */
     String UNKNOWN = "Unknown";
 
+    /**
+     * Start the item.
+     *
+     * @exception javax.jbi.JBIException if the item fails to start.
+     */
     void start() throws JBIException;
 
+    /**
+     * Stop the item. This suspends current messaging activities.
+     *
+     * @exception javax.jbi.JBIException if the item fails to stop.
+     */
     void stop() throws JBIException;
 
+    /**
+     * Shut down the item. This releases resources and returns the item
+     * to an uninitialized state.
+     *
+     * @exception javax.jbi.JBIException if the item fails to shut down.
+     */
     void shutDown() throws JBIException;
 
-    String getCurrentState();
+    /**
+     * Get the current state of this managed compononent.
+     *
+     * @return the current state of this managed component (must be one of the
+     *         string constants defined by this interface)
+     */
+     String getCurrentState();
 
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/MBeanNames.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/MBeanNames.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/MBeanNames.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/management/MBeanNames.java Fri Mar  7 08:54:00 2008
@@ -18,13 +18,55 @@
 
 import javax.management.ObjectName;
 
+/**
+ * This interface provides methods to create JMX object names for component-
+ * supplied MBeans. This ensures that component-supplied MBeans follow the
+ * JBI implementation-determined naming convention.
+ *
+ * Components obtain instances of this name creator using {@link
+ * javax.jbi.component.ComponentContext#getMBeanNames()}.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface MBeanNames {
 
+    /** The custom name that must be used for bootstrap extensions */
     String BOOTSTRAP_EXTENSION = "BootstrapExtension";
 
+    /** The custom name that must be used for component life cycle extensions */
     String COMPONENT_LIFE_CYCLE_EXTENSION = "LifeCycleExtension";
 
+    /**
+     * Formulate and return an MBean ObjectName for a custom control
+     * of this name creator's JBI component.
+     * <p>
+     * This is used by components to create JMX names for their own JMX
+     * controls, allowing the JBI implementation to prefix the created name
+     * to fit within the implementation's own naming scheme.
+     * <p>
+     * Standard extensions must use the following custom name constants:
+     * <ul>
+     *   <li>Bootstrap (installer) extension: {@link #BOOTSTRAP_EXTENSION}.</li>
+     *   <li>Component life cycle extension:
+     *       {@link #COMPONENT_LIFE_CYCLE_EXTENSION}.
+     *   </li>
+     * </ul>
+     * All other custom component MBeans must use custom names that do not
+     * collide with the standard extension names.
+     *
+     * @param customName the name of the custom control; must be non-null and
+     *        non-empty; must be legal for use in a JMX object name
+     * @return the JMX ObjectName of the MBean, or <code>null</code> if
+     *         the <code>customName</code> is invalid
+     */
     ObjectName createCustomComponentMBeanName(String customName);
 
+    /**
+     * Retrieve the default JMX Domain Name for MBeans registered in
+     * this instance of the JBI implementation.
+     *
+     * @return the JMX domain name for this instance of the JBI implemention;
+     *         must be non-null and non-empty
+     */
     String getJmxDomainName();
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/DeliveryChannel.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/DeliveryChannel.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/DeliveryChannel.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/DeliveryChannel.java Fri Mar  7 08:54:00 2008
@@ -20,24 +20,114 @@
 
 import javax.xml.namespace.QName;
 
-public interface DeliveryChannel {
+/**
+ * Bi-directional communication channel used to interact with the Normalized
+ * Message Service.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface DeliveryChannel
+{
+    /**
+     * Closes the delivery channel, halting all message traffic.
+     *
+     * @throws MessagingException fatal error while closing channel.
+     */
     void close() throws MessagingException;
 
+    /**
+     * Create a message exchange factory. This factory will create exchange
+     * instances with all appropriate properties set to null.
+     *
+     * @return a message exchange factory
+     */
     MessageExchangeFactory createExchangeFactory();
 
+    /**
+     * Create a message exchange factory for the given interface name.
+     *
+     * @param interfaceName name of the interface for which all exchanges
+     *                      created by the returned factory will be set
+     * @return an exchange factory that will create exchanges for the given
+     *         interface; must be non-null
+     */
     MessageExchangeFactory createExchangeFactory(QName interfaceName);
 
+    /**
+     * Create a message exchange factory for the given service name.
+     *
+     * @param serviceName name of the service for which all exchanges
+     *                    created by the returned factory will be set
+     * @return an exchange factory that will create exchanges for the given
+     *         service; must be non-null
+     */
     MessageExchangeFactory createExchangeFactoryForService(QName serviceName);
 
+    /**
+     * Create a message exchange factory for the given endpoint.
+     *
+     * @param endpoint endpoint for which all exchanges created by the
+     *                 returned factory will be set for
+     * @return an exchange factory that will create exchanges for the
+     *         given endpoint
+     */
     MessageExchangeFactory createExchangeFactory(ServiceEndpoint endpoint);
 
+    /**
+     * Blocking call used to service a MessageExchange instance which has
+     * been initiated by another component.  This method supports concurrent
+     * invocation for multi-threaded environments.
+     *
+     * @return mesage exchange instance
+     * @throws MessagingException failed to accept
+     */
     MessageExchange accept() throws MessagingException;
 
+    /**
+     * Identical to accept(), but returns after specified interval even if
+     * a message exchange is unavailable.
+     *
+     * @param timeout time to wait in milliseconds
+     * @return mesage exchange instance or null if timeout is reached
+     * @throws MessagingException failed to accept
+     */
     MessageExchange accept(long timeout) throws MessagingException;
 
+    /**
+     * Routes a MessageExchange instance through the Normalized Message Service
+     * to the appropriate servicing component. This method supports concurrent
+     * invocation for multi-threaded environments.
+     *
+     * @param exchange message exchange to send
+     * @throws MessagingException unable to send exchange
+     */
     void send(MessageExchange exchange) throws MessagingException;
 
+    /**
+     * Routes a MessageExchange instance through the Normalized Message Service
+     * to the appropriate servicing component, blocking until the exchange is
+     * returned.  This method supports concurrent invocation for multi-threaded
+     * environments.
+     *
+     * @param exchange message exchange to send
+     * @return true if the exchange has been processed and returned by the
+     *         servicing component, false otherwise.
+     * @throws MessagingException unable to send exchange
+     */
     boolean sendSync(MessageExchange exchange) throws MessagingException;
 
+    /**
+     * Routes a MessageExchange instance through the Normalized Message Service
+     * to the appropriate servicing component, blocking until the specified
+     * timeout is reached.  This method supports concurrent invocation for
+     * multi-threaded environments.
+     *
+     * @param exchange message exchange to send
+     * @param timeout time to wait in milliseconds
+     * @return true if the exchange has been processed and returned by the
+     *         servicing component, false in the case of timeout.
+     * @throws MessagingException unable to send exchange
+     */
     boolean sendSync(MessageExchange exchange, long timeout) throws MessagingException;
+
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/ExchangeStatus.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/ExchangeStatus.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/ExchangeStatus.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/ExchangeStatus.java Fri Mar  7 08:54:00 2008
@@ -16,24 +16,56 @@
  */
 package javax.jbi.messaging;
 
+/**
+ * Typesafe enumeration containing status values for a message exchange.
+ *
+ * @author JSR208 Expert Group
+ */
 public final class ExchangeStatus {
 
+    /**
+     * Indicates that an ME has not been processed to completion.
+     */
     public static final ExchangeStatus ACTIVE = new ExchangeStatus("Active");
 
+    /**
+     * Indicates that an ME has terminated abnormally within the JBI environment.
+     */
     public static final ExchangeStatus ERROR = new ExchangeStatus("Error");
 
+    /**
+     * Indicates that an ME has been processed to completion.
+     */
     public static final ExchangeStatus DONE = new ExchangeStatus("Done");
 
+    /** String representation of status. */
     private String mStatus;
 
+    /**
+     * Private constructor used to create a new ExchangeStatus type.
+     *
+     * @param status value
+     */
     private ExchangeStatus(String status) {
         mStatus = status;
     }
 
+    /**
+     * Returns string value of enumerated type.
+     *
+     * @return String representation of status value.
+     */
     public String toString() {
         return mStatus;
     }
 
+    /**
+     * Returns instance of ExchangeStatus that corresponds to given string.
+     *
+     * @param status string value of status
+     * @return ExchangeStatus
+     * @throws java.lang.IllegalArgumentException if string can't be translated
+     */
     public static ExchangeStatus valueOf(String status) {
         ExchangeStatus instance;
 
@@ -57,6 +89,11 @@
         return instance;
     }
 
+    /**
+     * Returns hash code value for this object.
+     *
+     * @return hash code value
+     */
     public int hashCode() {
         return mStatus.hashCode();
     }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/Fault.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/Fault.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/Fault.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/Fault.java Fri Mar  7 08:54:00 2008
@@ -16,6 +16,11 @@
  */
 package javax.jbi.messaging;
 
+/**
+ * Models WSDL fault messages.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface Fault extends NormalizedMessage {
 
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOnly.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOnly.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOnly.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOnly.java Fri Mar  7 08:54:00 2008
@@ -16,8 +16,26 @@
  */
 package javax.jbi.messaging;
 
+/**
+ * Supports operations used to process an In Only MEP to completion.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface InOnly extends MessageExchange {
+
+    /**
+     * Retrieves the <i>in</i> normalized message from this exchange.
+     *
+     * @return in message
+     */
     NormalizedMessage getInMessage();
 
+    /**
+     * Sets the <i>in</i> normalized message for this exchange.
+     *
+     * @param msg in message
+     * @throws MessagingException unable to set in message
+     */
     void setInMessage(NormalizedMessage msg) throws MessagingException;
+
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOptionalOut.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOptionalOut.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOptionalOut.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOptionalOut.java Fri Mar  7 08:54:00 2008
@@ -16,12 +16,40 @@
  */
 package javax.jbi.messaging;
 
+/**
+ * Supports operations used to process an In Optional Out MEP to completion.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface InOptionalOut extends MessageExchange {
+
+    /**
+     * Retrieves the <i>in</i> normalized message from this exchange.
+     *
+     * @return in message
+     */
     NormalizedMessage getInMessage();
 
+    /**
+     * Retrieves the <i>out</i> normalized message from this exchange.
+     *
+     * @return out message
+     */
     NormalizedMessage getOutMessage();
-
+    /**
+     * Sets the <i>in</i> normalized message for this exchange.
+     *
+     * @param msg in message
+     * @throws MessagingException unable to set in message
+     */
     void setInMessage(NormalizedMessage msg) throws MessagingException;
 
+    /**
+     * Sets the <i>out</i> normalized message for this exchange.
+     *
+     * @param msg out message
+     * @throws MessagingException unable to set out message
+     */
     void setOutMessage(NormalizedMessage msg) throws MessagingException;
+
 }



Mime
View raw message