servicemix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gno...@apache.org
Subject svn commit: r634741 [2/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
Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOut.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOut.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOut.java (original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/InOut.java Fri Mar
 7 08:54:00 2008
@@ -16,12 +16,40 @@
  */
 package javax.jbi.messaging;
 
+/**
+ * Supports operations used to process an In Out MEP to completion.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface InOut 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;
+
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessageExchange.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessageExchange.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessageExchange.java
(original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessageExchange.java
Fri Mar  7 08:54:00 2008
@@ -22,64 +22,232 @@
 
 import javax.xml.namespace.QName;
 
+/**
+ * MessageExchange represents a container for normalized messages which
+ * are described by an exchange pattern. The exchange pattern defines the
+ * names, sequence, and cardinality of messages in an exchange.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface MessageExchange {
+
+    /**
+     * JTA transaction context property name.
+     */
     String JTA_TRANSACTION_PROPERTY_NAME = "javax.jbi.transaction.jta";
 
+    /**
+     * Returns the URI of the pattern for this exchange.
+     *
+     * @return pattern URI for this exchange
+     */
     URI getPattern();
 
+    /**
+     * Returns the unique identifier assigned by the NMS for this exchange.
+     *
+     * @return unique id for this exchange
+     */
     String getExchangeId();
 
+    /**
+     * Returns the processing status of the exchange.
+     *
+     * @return status of the exchange
+     */
     ExchangeStatus getStatus();
 
+    /**
+     * Sets the processing status of the exchange.
+     *
+     * @param status exchange status
+     * @throws MessagingException failed to set status, possibly due to
+     *                            an invalid state transition.
+     */
     void setStatus(ExchangeStatus status) throws MessagingException;
 
+    /**
+     * Used to specify the source of a failure status. Invoking this method
+     * automatically adjusts the status of the ME to {@link ExchangeStatus#ERROR}.
+     *
+     * @param error error cause
+     */
     void setError(Exception error);
 
+    /**
+     * Retrieves the Exception describing the exchanges error status.
+     *
+     * @return exception associated with this exchange
+     */
     Exception getError();
 
+    /**
+     * Retrieves the fault message for this exchange, if one exists. A fault/message
+     * reference is unnecessary, since an exchange can carry at most one fault, and
+     * it is always the final message in an exchange.
+     *
+     * @return fault associated with the exchange, or null if not present
+     */
     Fault getFault();
 
+    /**
+     * Specifies the fault message for this exchange, if one exists. A fault/message
+     * reference is unnecessary, since an exchange can carry at most one fault, and
+     * it is always the final message in an exchange.
+     *
+     * @param fault fault
+     * @throws MessagingException operation not permitted in the current exchange state
+     */
     void setFault(Fault fault) throws MessagingException;
 
+    /**
+     * Creates a normalized message based on the specified message reference. The pattern
+     * governing this exchange must contain a definition for the reference name supplied.
+     *
+     * @return a new normalized message
+     * @throws MessagingException failed to create message
+     */
     NormalizedMessage createMessage() throws MessagingException;
 
+    /**
+     * Generic factory method for Fault objects.
+     *
+     * @return a new fault
+     * @throws MessagingException failed to create fault
+     */
     Fault createFault() throws MessagingException;
 
+    /**
+     * Retrieves a normalized message based on the specified message reference.
+     *
+     * @param name message reference
+     * @return message with the specified reference name
+     */
     NormalizedMessage getMessage(String name);
 
+    /**
+     * Sets a normalized message with the specified message reference. The pattern
+     * governing this exchange must contain a definition for the reference name
+     * supplied.
+     *
+     * @param msg normalized message
+     * @param name message reference
+     * @throws MessagingException operation not permitted in the current exchange state
+     */
     void setMessage(NormalizedMessage msg, String name) throws MessagingException;
 
+    /**
+     * Retrieves the specified property from the exchange.
+     *
+     * @param name property name
+     * @return property value
+     */
     Object getProperty(String name);
 
+    /**
+     * Specifies a property for the exchange.
+     *
+     * @param name property name
+     * @param obj property value
+     */
     void setProperty(String name, Object obj);
 
+    /**
+     * Specifies the endpoint used by this exchange.
+     *
+     * @param endpoint endpoint address
+     */
     void setEndpoint(ServiceEndpoint endpoint);
 
+    /**
+     * Specifies the service used by this exchange.
+     *
+     * @param service service address
+     */
     void setService(QName service);
 
+    /**
+     * Specifies the interface name used by this exchange.
+     *
+     * @param interfaceName interface name
+     */
     void setInterfaceName(QName interfaceName);
 
+    /**
+     * Specifies the operation used by this exchange.
+     *
+     * @param name operation name
+     */
     void setOperation(QName name);
 
+    /**
+     * Retrieves the endpoint used by this exchange.
+     *
+     * @return endpoint address for this message exchange
+     */
     ServiceEndpoint getEndpoint();
 
+    /**
+     * Retrieves the interface name used by this exchange.
+     *
+     * @return interface used for this message exchange
+     */
     QName getInterfaceName();
 
+    /**
+     * Retrieves the service used by this exchange.
+     * 
+     * @return service address for this message exchange
+     */
     QName getService();
 
+    /**
+     * Retrieves the operation used by this exchange.
+     * 
+     * @return operation name for this message exchange
+     */
     QName getOperation();
 
+    /**
+     * Queries the existence of a transaction context.
+     * 
+     * @return boolean transactional state of the exchange
+     */
     boolean isTransacted();
 
+    /**
+     * Queries the role that the caller plays in the exchange.
+     *
+     * @return Role expected of caller.
+     */
     Role getRole();
 
+    /**
+     * Returns the name of all properties for this exchange.
+     * 
+     * @return a set of all the property names, as Strings.
+     */
     java.util.Set getPropertyNames();
 
+    /**
+     * Typesafe enum containing the roles a component can play in a service.
+     * 
+     */
     public static final class Role {
+
+        /**
+         * Service provider.
+         */
         public static final Role PROVIDER = new Role();
 
+        /**
+         * Service Consumer.
+         */
         public static final Role CONSUMER = new Role();
 
+        /**
+         * Prevent direct instantiation.
+         */
         private Role() {
         }
     }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessageExchangeFactory.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessageExchangeFactory.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessageExchangeFactory.java
(original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessageExchangeFactory.java
Fri Mar  7 08:54:00 2008
@@ -20,16 +20,83 @@
 
 import javax.xml.namespace.QName;
 
+/**
+ * A message exchange factory is used used to create new instances of
+ * MessageExchange. Service consumers use these factories to create
+ * message exchanges when initiating a new service request. Message
+ * exchange factories are created using the
+ * {@link javax.jbi.component.ComponentContext} given to the component
+ * during its initialization (see
+ * {@link javax.jbi.component.ComponentLifeCycle}). There are a variety
+ * of ways to creating such factories, each of which creates a context
+ * that is used to provide some of the default properties of
+ * MessageExchange instances created by the factory instances. For example,
+ * a factory can be created for a particular endpoint, ensuring that all exchanges
+ * created by the factory have that endpoint set as the default endpoint property
+ * of the exchange. This allows components to retain factories as a way of aligning
+ * internal processing context with the context contained in the factory, ensuring
+ * that the exchanges created consistently reflect that context.
+ */
 public interface MessageExchangeFactory {
+
+    /**
+     * Creates a new MessageExchange instance used to initiate a service
+     * invocation. JBI defines a set of four basic message exchange types,
+     * corresponding to the predefined in-* WSDL 2.0 Message Exchange Patterns.
+     *
+     * @param serviceName name of the service to be invoked
+     * @param operationName name of the operation to be invoked
+     * @return new message exchange, initialized for invoking the given service and operation
+     * @throws MessagingException if the given service or operation are not registered
+     *                            with the NMR or the factory was created for a particular
+     *                            interface, and the given serviceName does not implement
+     *                            that interface.
+     */
     MessageExchange createExchange(QName serviceName, QName operationName) throws MessagingException;
 
+    /**
+     * Creates a new MessageExchange instance used to initiate a service invocation.
+     * JBI defines a set of eight fundamental message exchange types which are created
+     * using binding and engine delivery channels. This base method is provided for
+     * extensibility, to satisfy the need for vendor-specific message exchange patterns.
+     * The registration and administration of these patterns is not addressed by JBI.
+     *
+     * @param pattern message exchange pattern
+     * @return new message exchange
+     * @throws MessagingException specified pattern is not registered to a message exchange
type
+     */
     MessageExchange createExchange(URI pattern) throws MessagingException;
 
+    /**
+     * Convenience method that creates an In-Only message exchange.
+     * 
+     * @return new In-Only message exchange
+     * @throws MessagingException failed to create exchange
+     */
     InOnly createInOnlyExchange() throws MessagingException;
 
+    /**
+     * Convenience method that creates an In-Optional-Out message exchange.
+     *
+     * @return new In-Optional-Out message exchange
+     * @throws MessagingException failed to create exchange
+     */
     InOptionalOut createInOptionalOutExchange() throws MessagingException;
 
+    /**
+     * Convenience method that creates an In-Out message exchange.
+     *
+     * @return new In-Out message exchange
+     * @throws MessagingException failed to create exchange
+     */
     InOut createInOutExchange() throws MessagingException;
 
+    /**
+     * Convenience method that creates an Robust-In-Only message exchange.
+     *
+     * @return new Robust-In-Only message exchange
+     * @throws MessagingException failed to create exchange
+     */
     RobustInOnly createRobustInOnlyExchange() throws MessagingException;
+
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessagingException.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessagingException.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessagingException.java
(original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/MessagingException.java
Fri Mar  7 08:54:00 2008
@@ -16,15 +16,38 @@
  */
 package javax.jbi.messaging;
 
+/**
+ * Generic exception used to report messaging related errors
+ * in the Normalized Message Service.
+ *
+ * @author JSR208 Expert Group
+ */
 public class MessagingException extends javax.jbi.JBIException {
+
+    /**
+     * Create a new MessagingException.
+     *
+     * @param msg error detail
+     */
     public MessagingException(String msg) {
         super(msg);
     }
 
+    /**
+     * Create a new MessagingException with the specified cause and error text.
+     *
+     * @param msg error detail
+     * @param cause underlying error
+     */
     public MessagingException(String msg, Throwable cause) {
         super(msg, cause);
     }
 
+    /**
+     * Create a new MessagingException with the specified cause.
+     * 
+     * @param cause underlying error
+     */
     public MessagingException(Throwable cause) {
         super(cause);
     }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/NormalizedMessage.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/NormalizedMessage.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/NormalizedMessage.java
(original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/NormalizedMessage.java
Fri Mar  7 08:54:00 2008
@@ -22,26 +22,95 @@
 import javax.security.auth.Subject;
 import javax.xml.transform.Source;
 
+/**
+ * Represents a JBI Normalized Message.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface NormalizedMessage {
+
+    /**
+     * Add an attachment to the message.
+     *
+     * @param id unique identifier for the attachment
+     * @param content attachment content
+     * @throws MessagingException failed to add attachment
+     */
     void addAttachment(String id, DataHandler content) throws MessagingException;
 
+    /**
+     * Retrieve the content of the message.
+     *
+     * @return message content
+     */
     Source getContent();
 
+    /**
+     * Retrieve attachment with the specified identifier.
+     *
+     * @param id unique identifier for attachment
+     * @return DataHandler representing attachment content, or null if an attachment
+     *         with the specified identifier is not found
+     */
     DataHandler getAttachment(String id);
 
+    /**
+     * Returns a list of identifiers for each attachment to the message.
+     *
+     * @return iterator over String attachment identifiers
+     */
     Set getAttachmentNames();
 
+    /**
+     * Removes attachment with the specified unique identifier.
+     *
+     * @param id attachment identifier
+     * @throws MessagingException failed to remove attachment
+     */
     void removeAttachment(String id) throws MessagingException;
 
+    /**
+     * Set the content of the message.
+     *
+     * @param content message content
+     * @throws MessagingException failed to set content
+     */
     void setContent(Source content) throws MessagingException;
 
+    /**
+     * Set a property on the message.
+     *
+     * @param name property name
+     * @param value property value
+     */
     void setProperty(String name, Object value);
 
+    /**
+     * Set the security Subject for the message.
+     *
+     * @param subject Subject to associated with message.
+     */
     void setSecuritySubject(Subject subject);
 
+    /**
+     * Retrieve a list of property names for the message.
+     *
+     * @return list of property names
+     */
     Set getPropertyNames();
 
+    /**
+     * Retrieve a property from the message.
+     *
+     * @param name property name
+     * @return property value, or null if the property does not exist
+     */
     Object getProperty(String name);
 
+    /**
+     * Retrieve the security Subject from the message.
+     *
+     * @return security Subject associated with message, or null.
+     */
     Subject getSecuritySubject();
 }

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/RobustInOnly.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/RobustInOnly.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/RobustInOnly.java
(original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/messaging/RobustInOnly.java
Fri Mar  7 08:54:00 2008
@@ -16,8 +16,26 @@
  */
 package javax.jbi.messaging;
 
+/**
+ * Supports operations used to process an Robust In Only MEP to completion.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface RobustInOnly 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;
+
 }

Copied: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/package.html (from r634214,
servicemix/smx4/nmr/trunk/nmr/api/src/main/java/org/apache/servicemix/nmr/api/package.html)
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/package.html?p2=servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/package.html&p1=servicemix/smx4/nmr/trunk/nmr/api/src/main/java/org/apache/servicemix/nmr/api/package.html&r1=634214&r2=634741&rev=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/nmr/api/src/main/java/org/apache/servicemix/nmr/api/package.html
(original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/package.html Fri Mar  7 08:54:00
2008
@@ -19,7 +19,7 @@
 </head>
 <body>
 
-Defines the core NMR and its client side invocation API.
+Java Business Integration APIs/SPIs
 
 </body>
 </html>

Modified: servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/servicedesc/ServiceEndpoint.java
URL: http://svn.apache.org/viewvc/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/servicedesc/ServiceEndpoint.java?rev=634741&r1=634740&r2=634741&view=diff
==============================================================================
--- servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/servicedesc/ServiceEndpoint.java
(original)
+++ servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi/servicedesc/ServiceEndpoint.java
Fri Mar  7 08:54:00 2008
@@ -18,12 +18,48 @@
 
 import javax.xml.namespace.QName;
 
+/**
+ * Reference to an endpoint, used to refer to an endpoint as well as
+ * query information about the endpoint. An endpoint is an addressable
+ * entity in the JBI system, used for accessing the provider of a
+ * specific service.
+ *
+ * @author JSR208 Expert Group
+ */
 public interface ServiceEndpoint {
+
+    /**
+     * Get a reference to this endpoint, using an endpoint reference
+     * vocabulary that is known to the provider.
+     *
+     * @param operationName the name of the operation to be performed by a
+     *                      consumer of the generated endpoint reference. Set
+     *                      to null if this is not applicable.
+     * @return endpoint reference as an XML fragment; null if the provider
+     *         does not support such references.
+     */
     org.w3c.dom.DocumentFragment getAsReference(QName operationName);
 
+    /**
+     * Returns the name of this endpoint.
+     *
+     * @return the endpoint name
+     */
     String getEndpointName();
 
+    /**
+     * Get the qualified names of all the interfaces implemented by this
+     * service endpoint.
+     *
+     * @return array of all interfaces implemented by this service endpoint;
+     *         must be non-null and non-empty.
+     */
     javax.xml.namespace.QName[] getInterfaces();
 
+    /**
+     * Returns the service name of this endpoint.
+     * 
+     * @return the qualified service name.
+     */
     javax.xml.namespace.QName getServiceName();
 }



Mime
View raw message