org.adroitlogic.ultraesb.api
Interface Message

public interface Message

The public API of a Message passing through the UltraESB

Method Summary

void	addAttachment(java.lang.String key, MessageFormat att) Add an attachment to the message identified by the specified key
void	addException(ErrorInfo e) Attach an error that this message encountered
void	addException(java.lang.Exception e) Attach an Exception that this message encountered
void	addMessageFileForRelease(MessageFile mf) Associate a MessageFile (a temporary file) for release back to the FileCache, once this message completes.
void	addMessageFormatForRelease(MessageFormat mf) Link a MessageFormat (i.e.
void	addMessageForRelease(Message m) Link a Message for GC along with this message
void	addMessageProperty(java.lang.String key, java.lang.Object value) Add a message property - i.e.
void	addResponseCorrelation(java.lang.String key, java.lang.Object value) Add an entry for correlation into the response message for this message.
void	addTransportHeader(java.lang.String key, java.lang.String value) Add a transport header to this message
void	beginTransaction() Begin a transaction using the default (i.e.
void	beginTransaction(java.lang.String transactionManagerBeanId) Begin a new Spring transaction and associate its context with this message
Message	cloneMessage() Clone the current message - without transport headers, properties or payload.
void	commitTransaction() Invoked to request a commit of the current transaction
boolean	containsAttachments() Does this message contain attachments?
Message	createDefaultResponseMessage() Create the default response message to this message
MessageFormat	detachPayload() Detach the current payload from this message.
MessageFormat	getAttachment(java.lang.String key) Get the attachment with the given key
java.util.Map	getAttachments() Return the Map of attachments keyed with the identifying string
java.lang.String	getContentType() Get the content type of the message if set.
java.util.UUID	getCorrelatedRequestUUID() The request message UUID for a response message
MessageFormat	getCurrentPayload() Get the current payload of the message
java.lang.String	getDestinationURL() Get the current destination URL for this message.
java.util.Map	getDuplicateTransportHeaders() Get the map of current transport header duplicate values
java.util.List	getExceptions() Get a list of errors this message encountered
java.lang.String	getFirstTransportHeader(java.lang.String key) Get the first transport header with the given key
java.lang.String	getFirstTransportHeaderIgnoreCase(java.lang.String key) This will perform a case insensitive lookup for the first occurrence of the given transport header
java.lang.String	getLastAddressValue() Return the address value (e.g.
ErrorInfo	getLastException() Get the last error encountered and linked to this message
java.lang.String	getLastSentURL() Return the absolute URL to which the corresponding request message, or this message was last sent
Mediation	getMediation() Return a reference to Mediation utilities
java.util.Map	getMessageProperties() Return current message properties as an unmodifiable map
java.lang.Object	getMessageProperty(java.lang.String key) Get the message property associated with the specified key
java.util.UUID	getMessageUUID() Get the UUID of the message
MessageFormat	getOriginalPayload() The original payload of the message - as received from the transport, unless modified
java.lang.String	getOriginatingTransport() Get originating transport
java.util.UUID	getParentMessageUUID() The parent message UUID
java.lang.String	getProxyServiceID() Get the id of the proxy service to which this message belongs
java.lang.String	getRequestContentType() Return the content type of the original request.
java.util.Map	getTransportHeaders() Get the map of current transport header values ignoring duplicates
java.util.List	getTransportHeaders(java.lang.String key) Get a List of transport header values for the given key
org.springframework.transaction.TransactionStatus	getTxnStatus() Get the Spring TransactionStatus for this message
void	holdCompletion() Used to hold execution of the message completion handlers when the current sequence completes.
boolean	isHoldCompletionTask() Is this message currently marked to hold completion tasks on at the end of the execution thread (e.g.
boolean	isMarkedAsFailed() Is this message currently marked as failed?
boolean	isRequest() Is this message a request message?
boolean	isResponse() Is this message a response message?
void	removeMessageProperty(java.lang.String key) Remove the message property associated with the specified key
void	removeTransportHeader(java.lang.String key) Remove all occurrences of the specified transport header
void	replaceTransportHeader(java.lang.String key, java.lang.String value) Replace the first occurrence of the transport header with the given value
void	resumeAndCommitTransaction() To be invoked typically in an async-response flow to re-energize a suspended transaction, and then commit Note.
void	resumeAndRollbackTransaction() To be invoked typically in an async-response flow to re-energize a suspended transaction, and then rollback Note.
void	resumeTransaction() To be invoked typically in an async-response flow to re-energize a suspended transaction Note.
void	rollbackTransaction() Invoked to request a rollback of the current transaction
void	setContentType(java.lang.String contentType) Set the content type of the message
void	setCurrentPayload(MessageFormat currentPayload) Set the current payload of the message
void	setDestinationURL(java.lang.String destinationURL) Set the destination URL for this message
void	setMarkedAsFailed(boolean markedAsFailed) Mark this message as failed, by passing true.
void	suspendTransaction() Suspend a transaction using the default (i.e.
void	suspendTransaction(java.lang.String transactionManagerBeanId) Invoked typically in a request flow to suspend the active transaction, and to save its state into the response correlation map

Method Detail

isMarkedAsFailed

boolean isMarkedAsFailed()

Is this message currently marked as failed?

Returns:

true if message has been marked as failed

setMarkedAsFailed

void setMarkedAsFailed(boolean markedAsFailed)

Mark this message as failed, by passing true. This will direct any message completion handlers to appropriately perform completion tasks expected of a failed message. (e.g. moving a file to the failed directory)

Parameters:

markedAsFailed - true marks this message as failed

isHoldCompletionTask

boolean isHoldCompletionTask()

Is this message currently marked to hold completion tasks on at the end of the execution thread (e.g. completion tasks for the mail transport would be to delete or move the email after processing)

Returns:

true if marked for holding of completion tasks

holdCompletion

void holdCompletion()

Used to hold execution of the message completion handlers when the current sequence completes. (i.e. the thread of execution) This allows a message completion to be postponed from the inSequence to the outSequence, where a successful receipt or status code can be checked and the message completed on its state (e.g. completion tasks for the mail transport would be to delete or move the email after processing)

getCurrentPayload

MessageFormat getCurrentPayload()

Get the current payload of the message

Returns:

the current payload

setCurrentPayload

void setCurrentPayload(MessageFormat currentPayload)

Set the current payload of the message

Parameters:

currentPayload - the new payload of the message

addAttachment

void addAttachment(java.lang.String key,
                   MessageFormat att)

Add an attachment to the message identified by the specified key

Parameters:

key - the identification key for the attachment

att - the attachment payload

getAttachment

MessageFormat getAttachment(java.lang.String key)

Get the attachment with the given key

Parameters:

key - the identifier of the attachment

Returns:

the attachment payload

containsAttachments

boolean containsAttachments()

Does this message contain attachments?

Returns:

true if the message contains attachments

getAttachments

java.util.Map getAttachments()

Return the Map of attachments keyed with the identifying string

Returns:

attachments map or an empty map

getOriginalPayload

MessageFormat getOriginalPayload()

The original payload of the message - as received from the transport, unless modified

Returns:

the original message payload

detachPayload

MessageFormat detachPayload()

Detach the current payload from this message. A detached Payload should be reclaimed (e.g. if a RawFileMessage) by the user code, and will not be reclaimed automatically as the Message object completes processing

Returns:

the message payload detached

getFirstTransportHeader

java.lang.String getFirstTransportHeader(java.lang.String key)

Get the first transport header with the given key

Parameters:

key - the header name

Returns:

the header value if any or null

getFirstTransportHeaderIgnoreCase

java.lang.String getFirstTransportHeaderIgnoreCase(java.lang.String key)

This will perform a case insensitive lookup for the first occurrence of the given transport header

Parameters:

key - the case insensitive header name

Returns:

the header value if any or null

addTransportHeader

void addTransportHeader(java.lang.String key,
                        java.lang.String value)

Add a transport header to this message

Parameters:

key - header name

value - header value

removeTransportHeader

void removeTransportHeader(java.lang.String key)

Remove all occurrences of the specified transport header

Parameters:

key - header name to remove

replaceTransportHeader

void replaceTransportHeader(java.lang.String key,
                            java.lang.String value)

Replace the first occurrence of the transport header with the given value

Parameters:

key - the header name

value - the new value

getTransportHeaders

java.util.List getTransportHeaders(java.lang.String key)

Get a List of transport header values for the given key

Returns:

transport headers as a List for the given key

getTransportHeaders

java.util.Map getTransportHeaders()

Get the map of current transport header values ignoring duplicates

Returns:

transport headers as a Map, when ignoring duplicates

getDuplicateTransportHeaders

java.util.Map getDuplicateTransportHeaders()

Get the map of current transport header duplicate values

Returns:

transport header duplicates as a Map

addMessageProperty

void addMessageProperty(java.lang.String key,
                        java.lang.Object value)

Add a message property - i.e. any Object can be a property

Parameters:

key - property key

value - property value

getMessageProperty

java.lang.Object getMessageProperty(java.lang.String key)

Get the message property associated with the specified key

Parameters:

key - property key

Returns:

property value

removeMessageProperty

void removeMessageProperty(java.lang.String key)

Remove the message property associated with the specified key

Parameters:

key - property key

getMessageProperties

java.util.Map getMessageProperties()

Return current message properties as an unmodifiable map

Returns:

the current message properties

isRequest

boolean isRequest()

Is this message a request message?

Returns:

true if a request

isResponse

boolean isResponse()

Is this message a response message?

Returns:

true if a response

getDestinationURL

java.lang.String getDestinationURL()

Get the current destination URL for this message. This is the default target address if this message is sent via a default address endpoint

Returns:

the destination URL

setDestinationURL

void setDestinationURL(java.lang.String destinationURL)

Set the destination URL for this message

Parameters:

destinationURL - the new destination URL

getContentType

java.lang.String getContentType()

Get the content type of the message if set. Note: sometimes the content type maybe available as a transport header

Returns:

the content type of the message

getRequestContentType

java.lang.String getRequestContentType()

Return the content type of the original request. On a response message, this method returns the content type of the original request

Returns:

the original request content type if known, or null

setContentType

void setContentType(java.lang.String contentType)

Set the content type of the message

Parameters:

contentType - the content type string to be set

getProxyServiceID

java.lang.String getProxyServiceID()

Get the id of the proxy service to which this message belongs

Returns:

the id of the owning proxy service

addResponseCorrelation

void addResponseCorrelation(java.lang.String key,
                            java.lang.Object value)

Add an entry for correlation into the response message for this message. Correlation values are useful when information needs to be passed from a request message to its asynchronous response

Parameters:

key - correlation map key

value - value to correlate

getMessageUUID

java.util.UUID getMessageUUID()

Get the UUID of the message

Returns:

the UUID of this message

getCorrelatedRequestUUID

java.util.UUID getCorrelatedRequestUUID()

The request message UUID for a response message

Returns:

the correlated request message UUID

getParentMessageUUID

java.util.UUID getParentMessageUUID()

The parent message UUID

Returns:

The parent message UUID

getTxnStatus

org.springframework.transaction.TransactionStatus getTxnStatus()

Get the Spring TransactionStatus for this message

Returns:

the status of the transaction

addMessageFileForRelease

void addMessageFileForRelease(MessageFile mf)

Associate a MessageFile (a temporary file) for release back to the FileCache, once this message completes. Any temporary files obtained and used from the FileCache, must be thus associated for clean removal and re-use and to prevent resource exhaustion. Users are free to use files created outside of the FileCache as they wish, and ensure that handles are not leaked.

Parameters:

mf - the MessageFile to be registered for removal

addMessageFormatForRelease

void addMessageFormatForRelease(MessageFormat mf)

Link a MessageFormat (i.e. payload) for GC along with this message

Parameters:

mf - the payload to link

addMessageForRelease

void addMessageForRelease(Message m)

Link a Message for GC along with this message

Parameters:

m - the Message to link

cloneMessage

Message cloneMessage()

Clone the current message - without transport headers, properties or payload. The cloned message has a unique UUID

Returns:

the cloned message

createDefaultResponseMessage

Message createDefaultResponseMessage()

Create the default response message to this message

Returns:

the response message created for this message

addException

void addException(java.lang.Exception e)

Attach an Exception that this message encountered

Parameters:

e - the Exception

addException

void addException(ErrorInfo e)

Attach an error that this message encountered

Parameters:

e - the ErrorInfo with optional error code and message

getExceptions

java.util.List getExceptions()

Get a list of errors this message encountered

Returns:

list of errors linked to this message

getLastException

ErrorInfo getLastException()

Get the last error encountered and linked to this message

Returns:

the last error if any, or null

beginTransaction

void beginTransaction(java.lang.String transactionManagerBeanId)

Begin a new Spring transaction and associate its context with this message

suspendTransaction

void suspendTransaction(java.lang.String transactionManagerBeanId)

Invoked typically in a request flow to suspend the active transaction, and to save its state into the response correlation map

Parameters:

transactionManagerBeanId - the Spring bean ID of the transaction manager

resumeAndCommitTransaction

void resumeAndCommitTransaction()

To be invoked typically in an async-response flow to re-energize a suspended transaction, and then commit Note. This functionality may be available with only some JTA transaction managers JTA spec 3.2.3: "Note that some transaction manager implementations allow a suspended transaction to be resumed by a different thread. This feature is not required by JTA"

resumeTransaction

void resumeTransaction()

To be invoked typically in an async-response flow to re-energize a suspended transaction Note. This functionality may be available with only some JTA transaction managers JTA spec 3.2.3: "Note that some transaction manager implementations allow a suspended transaction to be resumed by a different thread. This feature is not required by JTA"

resumeAndRollbackTransaction

void resumeAndRollbackTransaction()

To be invoked typically in an async-response flow to re-energize a suspended transaction, and then rollback Note. This functionality may be available with only some JTA transaction managers JTA spec 3.2.3: "Note that some transaction manager implementations allow a suspended transaction to be resumed by a different thread. This feature is not required by JTA"

rollbackTransaction

void rollbackTransaction()

Invoked to request a rollback of the current transaction

commitTransaction

void commitTransaction()

Invoked to request a commit of the current transaction

beginTransaction

void beginTransaction()

Begin a transaction using the default (i.e. only) TransactionManager defined in the configuration

suspendTransaction

void suspendTransaction()

Suspend a transaction using the default (i.e. only) TransactionManager defined in the configuration

getMediation

Mediation getMediation()

Return a reference to Mediation utilities

Returns:

a reference to Mediation

getOriginatingTransport

java.lang.String getOriginatingTransport()

Get originating transport

Returns:

originating transport

getLastAddressValue

java.lang.String getLastAddressValue()

Return the address value (e.g. Prefix, URL etc) to which the corresponding request message, or this message was last sent

Returns:

the address value which generated this response, or the last address to which this message was sent

getLastSentURL

java.lang.String getLastSentURL()

Return the absolute URL to which the corresponding request message, or this message was last sent

Returns:

the absolute URL which generated this response, or the last absolute URL to which this message was sent