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 [EMAIL PROTECTED] 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 + * [EMAIL PROTECTED] javax.jbi.component.ComponentContext} given to the component + * during its initialization (see + * [EMAIL PROTECTED] 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(); }
