javax.jbi.messaging
Interface MessageExchange

All Known Subinterfaces:

InOnly, InOptionalOut, InOut, RobustInOnly

public interface MessageExchange

TODO MessageExchange : manage exceptions in methods MessageExchange represents a container for normalized messages which is described by an exchange pattern. The exchange pattern defines the names, sequence, and cardinality of messages in an exchange.

When a consumer initiates a message exchange (that is, it creates a new exchange instance and initializes it), it has a choice of how to address the exchange, to indicate the service desired. In increasing order of specificity, the initiating consumer may address the new exchange by:

• Service Type. The consumer supplies only the interface name, indicating the type of service desired. The NMR chooses a suitable provider when the message is sent.
• Service Name. The consumer supplies only the service name, indicating the service provider desired, but not the particular endpoint exposed by that provider to use. The NMR chooses a suitable endpoint when the message is sent.
• Service Endpoint. The consumer specifies the exact service endpoint name it wishes to use. The consumer can determine this dynamically (by querying available active endpoints), or the service endpoint can be determined at design or deployment time. When the message exchange is sent, the NMR will attempt to route the instance to the given endpoint only. (Note that connection metadata can alter this behaviour, by introducing aliases for endpoints.)

The NMR will always use the most specific address type given, ignoring other, less specific ones, if any.

Note that whenever the NMR chooses the provider endpoint, it must set the endpoint property of the message exchange instance to the endpoint it selected.

Note also that setting the different address properties of an exchange instance does not cause side effects. For example, setting the service endpoint will not affect the previously set interface name or service name.

Author:

JSR208 Expert Group

Nested Class Summary

static class

MessageExchange.Role Typesafe enumeration containing the roles a component can play in an exchange.

Field Summary

static java.lang.String

JTA_TRANSACTION_PROPERTY_NAME JTA transaction context property name

Method Summary

Fault	createFault() Generic factory method for Fault objects.
NormalizedMessage	createMessage() Creates a normalized message based on the specified message reference.
ServiceEndpoint	getEndpoint() Retrieves the endpoint used by this exchange.
java.lang.Exception	getError() Retrieves Exception describing the exchanges error status.
java.lang.String	getExchangeId() Returns the unique identifier assigned by the NMR for this exchange.
Fault	getFault() Retrieves the fault message for this exchange, if one exists.
FlowAttributes	getFlowAttributes() Gets the flow attributes
javax.xml.namespace.QName	getInterfaceName() Retrieves the interface name used by this exchange.
NormalizedMessage	getMessage(java.lang.String name) Retrieves a normalized message based on the specified message reference.
javax.xml.namespace.QName	getOperation() Retrieves the operation used by this exchange.
java.net.URI	getPattern() Returns the URI of the pattern for this exchange.
java.lang.Object	getProperty(java.lang.String name) Retrieves the specified property from this exchange.
java.util.Set	getPropertyNames() Get all of the names of the properties for this exchange.
MessageExchange.Role	getRole() Queries the role that the caller (which must be the owner of the this exchange instance) plays in the exchange.
javax.xml.namespace.QName	getService() Retrieves the service used by this exchange.
ExchangeStatus	getStatus() Returns the processing status of the exchange.
boolean	isTransacted() Queries the existence of a JTA transaction context.
void	setEndpoint(ServiceEndpoint endpoint) Specifies the endpoint used by this exchange.
void	setError(java.lang.Exception error) Used to specify the source of a failure status.
void	setFault(Fault fault) Specifies the fault message for this exchange, if one exists.
void	setFlowAttributes(FlowAttributes flowAttributes) Sets the flow attributes
void	setInterfaceName(javax.xml.namespace.QName interfaceName) Specifies the interface name used by this exchange.
void	setMessage(NormalizedMessage msg, java.lang.String name) Sets a normalized message with the specified message reference.
void	setOperation(javax.xml.namespace.QName name) Specifies the operation used by this exchange.
void	setProperty(java.lang.String name, java.lang.Object obj) Specifies a property for this exchange.
void	setService(javax.xml.namespace.QName service) Specifies the service used by this exchange.
void	setStatus(ExchangeStatus status) Sets the processing status of the exchange.

Field Detail

JTA_TRANSACTION_PROPERTY_NAME

static final java.lang.String JTA_TRANSACTION_PROPERTY_NAME

JTA transaction context property name

See Also:

Constant Field Values

Method Detail

createFault

Fault createFault()
                  throws MessagingException

Generic factory method for Fault objects.

Returns:

a new fault message; must be non-null

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

MessagingException - if the exchange is in a terminal state ( getStatus() != ExchangeStatus.ACTIVE ), or if the message exchange pattern does not permit fault messages

createMessage

NormalizedMessage createMessage()
                                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.

Returns:

a new normalized message; must be non-null

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

MessagingException - if the exchange is in a terminal state ( getStatus() != ExchangeStatus.ACTIVE )

getEndpoint

ServiceEndpoint getEndpoint()

Retrieves the endpoint used by this exchange.

Returns:

endpoint address for this message exchange; null if not set

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

getError

java.lang.Exception getError()

Retrieves Exception describing the exchanges error status.

Returns:

exception associated with this exchange; null if not set

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

getExchangeId

java.lang.String getExchangeId()

Returns the unique identifier assigned by the NMR for this exchange.

Returns:

unique id for this exchange; null if not set

getFlowAttributes

FlowAttributes getFlowAttributes()

Gets the flow attributes

Returns:

the flow attributes

setFlowAttributes

void setFlowAttributes(FlowAttributes flowAttributes)

Sets the flow attributes

Parameters:

flowAttributes - the flow attributes

getFault

Fault getFault()

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.

Returns:

fault associated with the exchange, or null if not present

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

getInterfaceName

javax.xml.namespace.QName getInterfaceName()

Retrieves the interface name used by this exchange.

Returns:

interface name for this message exchange; null if not set

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

getMessage

NormalizedMessage getMessage(java.lang.String name)

Retrieves a normalized message based on the specified message reference.

Parameters:

name - message reference; must be non-null and non-empty

Returns:

message with the specified reference name

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

getOperation

javax.xml.namespace.QName getOperation()

Retrieves the operation used by this exchange.

Returns:

operation name for this message exchange; null if not set

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

getPattern

java.net.URI getPattern()

Returns the URI of the pattern for this exchange.

Returns:

pattern URI for this exchange; null if not set

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

getProperty

java.lang.Object getProperty(java.lang.String name)

Retrieves the specified property from this exchange.

Parameters:

name - property name; must be non-null and non-empty

Returns:

property value; may be null

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

getPropertyNames

java.util.Set getPropertyNames()

Get all of the names of the properties for this exchange.

Returns:

a set of all the property names, as Strings; must be non-null; may be an empty set

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

getRole

MessageExchange.Role getRole()

Queries the role that the caller (which must be the owner of the this exchange instance) plays in the exchange.

Returns:

Role the caller (the exchange owner) must play in the exchange; must be non-null

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

getService

javax.xml.namespace.QName getService()

Retrieves the service used by this exchange.

Returns:

service address for this message exchange; null if not set

Throws:

java.lang.IllegalStateException - - if the component is not the owner of this message exchange

getStatus

ExchangeStatus getStatus()

Returns the processing status of the exchange.

Returns:

status of the exchange; must be non-null

isTransacted

boolean isTransacted()

Queries the existence of a JTA transaction context.

Returns:

boolean transactional state of the exchange

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

setEndpoint

void setEndpoint(ServiceEndpoint endpoint)

Specifies the endpoint used by this exchange. Note that this must not affect the value of the Service property of this message exchange.

Parameters:

endpoint - endpoint address; may be null

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

setError

void setError(java.lang.Exception error)

Used to specify the source of a failure status. Invoking this method automatically adjusts the status of the ME to ExchangeStatus.ERROR.

Parameters:

error - error cause; must be non-null

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

setFault

void setFault(Fault fault)
              throws MessagingException

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.

Parameters:

fault - fault message; may be null

Throws:

MessagingException - operation not permitted in the current exchange state

java.lang.IllegalStateException - if the component is not the owner of this message exchange

setInterfaceName

void setInterfaceName(javax.xml.namespace.QName interfaceName)

Specifies the interface name used by this exchange.

Parameters:

interfaceName - interface name to be used by this exchange; may be null

Throws:

java.lang.IllegalStateException - - if the component is not the owner of this message exchange

setMessage

void setMessage(NormalizedMessage msg,
                java.lang.String name)
                throws MessagingException

Sets a normalized message with the specified message reference. The pattern governing this exchange must contain a definition for the reference name supplied.

Parameters:

msg - normalized message; must be non-null

name - message reference; must be non-null and non-empty

Throws:

MessagingException - operation not permitted in the current exchange state

java.lang.IllegalStateException - if the component is not the owner of this message exchange

setOperation

void setOperation(javax.xml.namespace.QName name)

Specifies the operation used by this exchange.

Parameters:

name - operation name; may be null

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

setProperty

void setProperty(java.lang.String name,
                 java.lang.Object obj)

Specifies a property for this exchange.

Parameters:

name - property name; must be non-null and non-empty

obj - property value; may be null

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

setService

void setService(javax.xml.namespace.QName service)

Specifies the service used by this exchange.

Parameters:

service - service address; may be null

Throws:

java.lang.IllegalStateException - if the component is not the owner of this message exchange

setStatus

void setStatus(ExchangeStatus status)
               throws MessagingException

Sets the processing status of the exchange.

Parameters:

status - exchange status; must be non-null

Throws:

MessagingException - failed to set status, possibly due to an invalid state transition.

java.lang.IllegalStateException - if the component is not the owner of this message exchange