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 [2/2] - in
/servicemix/smx4/nmr/trunk/jbi/api/src/main/java/javax/jbi: ./ component/
management/ messaging/ servicedesc/
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();
}