You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicemix.apache.org by gn...@apache.org on 2008/03/07 17:54:02 UTC
svn commit: r634741 [1/2] - in
/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi: ./ component/
management/ messaging/ servicedesc/
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>
+ * <component-task-result>
+ * <component-name>BC1</component-name>
+ * <component-task-result-details
+ * xmlns="http://java.sun.com/xml/ns/jbi/management-message">
+ * <task-result-details>
+ * <task-id>deploy</task-id>
+ * <task-result>SUCCESS</task-result>
+ * </task-result-details>
+ * </component-task-result-details>
+ * </component-task-result>
+ * </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><identification><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><identification><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;
+
}