com.sonicsw.xq
Interface XQMessage

All Superinterfaces:

java.lang.Cloneable, java.io.Serializable, XQCloneable

public interface XQMessage
extends XQCloneable, java.io.Serializable

The XQMessage is a message that has a header and can contain zero or more Parts. It provides methods to add, delete, and get the constituent parts.

Message headers support the following conversion table. The marked cases must be supported. The unmarked cases will throw a XQMessageException. The String to primitive conversions will throw a runtime exception if the primitives valueOf() method does not accept it as a valid String representation of the primitive.

A value written as the row type can be read as the column type.

 |        | boolean byte short int long float double String
 |----------------------------------------------------------
 |boolean |    X                                       X
 |byte    |          X     X    X   X                  X
 |short   |                X    X   X                  X
 |int     |                     X   X                  X
 |long    |                         X                  X
 |float   |                               X     X      X
 |double  |                                     X      X
 |String  |    X     X     X    X   X     X     X      X
 |----------------------------------------------------------
 

A Message object contains a built-in facility for supporting application-defined headers. In effect, this provides a mechanism for adding application-specific header fields to a message. Headers allow an application, via message selectors, to have a JMS provider select, or filter, messages on its behalf using application-specific criteria. Header values can be boolean, byte, short, int, long, float, double, and String. Header values are set prior to sending a message.

There are two mechanisms of accessing headers. First, user defined headers are accessible via a variety of type specific methods. These include getByteHeader(),getStringHeader(), getLongHeader(), etc..

In addition to the above accessors, it is also possible to access a super-set of header values utilizing the getHeaderValue() and its variants. This superset not only includes user defined values, but also include transport specific values (usually JMS message headers). For instance, the following JMS predefined headers are accessible via getHeaderValue():

      JMSDestination
      JMSDeliveryMode, 
      JMSMessageID
      JMSTimestamp
      JMSCorrelationID
      JMSReplyTo 
      JMSRedelivered
      JMSType
      JMSExpiration
      JMSPriority
 

For example, to access the JMSMessageID, the user can utilize getHeaderValue( "JMSMessageID" )

See Also:

XQPart

Method Summary

void	addPart(XQPart part) Adds a part to the XQMessage.
void	addPartAt(XQPart part, int index) Adds a part to the XQMessage.
boolean	containsHeader(java.lang.String name) Indicates whether a header value exists.
XQPart	createPart() Creates an empty part.
XQPart	createPart(java.lang.Object content, java.lang.String contentType) Creates a part with the specified content and content-type.
boolean	doesPartExist(java.lang.String cid) Returns true if a part with the given content-Id exists in the message, false otherwise.
boolean	getBooleanHeader(java.lang.String name) Retrieves a user-defined Message header from the XQMessage, if the named boolean header has been set on the message by the sender or the ESB framework.
byte	getByteHeader(java.lang.String name) Retrieves a user-defined Message header from the XQMessage, if the named byte header has been set on the message by the sender or the ESB framework.
java.lang.String	getCorrelationId() Get the CorrelationID for this message.
double	getDoubleHeader(java.lang.String name) Retrieves a user-defined Message header from the XQMessage, if the named double header has been set on the message by the sender or the ESB framework.
float	getFloatHeader(java.lang.String name) Retrieves a user-defined Message header from the XQMessage, if the named float header has been set on the message by the sender or the ESB framework.
java.util.Iterator<java.lang.String>	getHeaderNames() Returns an Iterator for all the header names.
java.lang.Object	getHeaderValue(java.lang.String name) Get the value of the named header.
int	getIntHeader(java.lang.String name) Retrieves a user-defined Message header from the XQMessage, if the named integer header has been set on the message by the sender or the ESB framework.
long	getLongHeader(java.lang.String name) Retrieves a user-defined Message header from the XQMessage, if the named long header has been set on the message by the sender or the ESB framework.
XQPart	getPart(int index) Gets the XQPart from the XQMessage by its index
XQPart	getPart(java.lang.String cid) Gets the XQPart from the XQMessage by its Content-Id.
org.w3c.dom.Document	getPartAsDocument(int index, boolean validate) Gets the XQPart from the XQMessage by index, and returns it as a DOM document.
org.w3c.dom.Document	getPartAsDocument(java.lang.String cid, boolean validate) Gets the XQPart from the XQMessage by its Content-Id, and returns it as a DOM document.
int	getPartCount() Gets the count of the number of Parts for the XQMessage.
XQAddress	getReplyTo() Get the Reply To address for this message.
short	getShortHeader(java.lang.String name) Retrieves a user-defined Message header from the XQMessage, if the named short header has been set on the message by the sender or the ESB framework.
java.lang.String	getStringHeader(java.lang.String name) Retrieves a user-defined Message header from the XQMessage, if the named string header has been set on the message by the sender or the ESB framework.
void	removeAllParts() Remove all Parts from the Message.
java.lang.Object	removeHeader(java.lang.String name) Remove the named header from the message header.
void	removePart(int index) Removes a Part from the Message.
void	removePart(java.lang.String contentID) Removes a Part from the Message.
void	replacePart(XQPart part, int index) Replace the XQPart at the specified location with a new part.
void	replacePart(XQPart part, java.lang.String cid) Replace the XQPart with the specified Content-ID with a new part.
void	setBooleanHeader(java.lang.String name, boolean value) Sets the user-defined boolean header value with the specified name into the message header.
void	setByteHeader(java.lang.String name, byte value) Sets the user-defined byte header value with the specified name into the message header.
void	setCorrelationId(java.lang.String id) Sets the CorrelationID for this message.
void	setDoubleHeader(java.lang.String name, double value) Sets the user-defined double header value with the specified name into the message header.
void	setFloatHeader(java.lang.String name, float value) Sets the user-defined float header value with the specified name into the message header.
void	setHeaderValue(java.lang.String name, java.lang.Object value) Sets a header value with the specified name into the message header.
void	setHeaderValues(java.util.Map<java.lang.String,java.lang.Object> headers) Sets multiple header values into the message header.
void	setIntHeader(java.lang.String name, int value) Sets the user-defined int header value with the specified name into the message header.
void	setLongHeader(java.lang.String name, long value) Sets the user-defined long header value with the specified name into the message header.
void	setPartFromDocument(int index, org.w3c.dom.Document doc) Create a new XQPart for this message from a DOM document.
void	setPartFromDocument(java.lang.String cid, org.w3c.dom.Document doc) Create a new XQPart for this message from a DOM document.
void	setReplyTo(XQAddress replyTo) Sets the Reply To address for this message.
void	setShortHeader(java.lang.String name, short value) Sets the user-defined short header value with the specified name into the message header.
void	setStringHeader(java.lang.String name, java.lang.String value) Sets the user-defined String header value with the specified name into the message header.

Methods inherited from interface com.sonicsw.xq.XQCloneable

clone

Method Detail

containsHeader

boolean containsHeader(java.lang.String name)
                       throws XQMessageException

Indicates whether a header value exists. This method tests for the existance of both transport level and user-defined headers.

Parameters:

name - The name of the header

Returns:

true if the header exists

Throws:

XQMessageException - thrown if there is an error

getHeaderNames

java.util.Iterator<java.lang.String> getHeaderNames()
                                                    throws XQMessageException

Returns an Iterator for all the header names. This method allows the user to iterator over transport level and user-defined headers.

Returns:

an Iterator containing all the names of headers

Throws:

XQMessageException - thrown if there is an error

getHeaderValue

java.lang.Object getHeaderValue(java.lang.String name)
                                throws XQMessageException

Get the value of the named header. This method gives access to both user-defined and transport level message header values.

Parameters:

name - The name of the header

Returns:

the value for the header

Throws:

XQMessageException - thrown if there is an error

getBooleanHeader

boolean getBooleanHeader(java.lang.String name)
                         throws XQMessageException

Retrieves a user-defined Message header from the XQMessage, if the named boolean header has been set on the message by the sender or the ESB framework.

Parameters:

name - The name of the header

Returns:

the value for the header

Throws:

XQMessageException - thrown if there is an error

getByteHeader

byte getByteHeader(java.lang.String name)
                   throws XQMessageException

Retrieves a user-defined Message header from the XQMessage, if the named byte header has been set on the message by the sender or the ESB framework.

Parameters:

name - The name of the header

Returns:

the value for the header

Throws:

XQMessageException - thrown if there is an error

getIntHeader

int getIntHeader(java.lang.String name)
                 throws XQMessageException

Retrieves a user-defined Message header from the XQMessage, if the named integer header has been set on the message by the sender or the ESB framework.

Parameters:

name - The name of the header

Returns:

the value for the header

Throws:

XQMessageException - thrown if there is an error

getLongHeader

long getLongHeader(java.lang.String name)
                   throws XQMessageException

Retrieves a user-defined Message header from the XQMessage, if the named long header has been set on the message by the sender or the ESB framework.

Parameters:

name - The name of the header

Returns:

the value for the header

Throws:

XQMessageException - thrown if there is an error

getFloatHeader

float getFloatHeader(java.lang.String name)
                     throws XQMessageException

Retrieves a user-defined Message header from the XQMessage, if the named float header has been set on the message by the sender or the ESB framework.

Parameters:

name - The name of the header

Returns:

the value for the header

Throws:

XQMessageException - thrown if there is an error

getDoubleHeader

double getDoubleHeader(java.lang.String name)
                       throws XQMessageException

Retrieves a user-defined Message header from the XQMessage, if the named double header has been set on the message by the sender or the ESB framework.

Parameters:

name - The name of the header

Returns:

the value for the header

Throws:

XQMessageException - thrown if there is an error

getShortHeader

short getShortHeader(java.lang.String name)
                     throws XQMessageException

Retrieves a user-defined Message header from the XQMessage, if the named short header has been set on the message by the sender or the ESB framework.

Parameters:

name - The name of the header

Returns:

the value for the header

Throws:

XQMessageException - thrown if there is an error

getStringHeader

java.lang.String getStringHeader(java.lang.String name)
                                 throws XQMessageException

Retrieves a user-defined Message header from the XQMessage, if the named string header has been set on the message by the sender or the ESB framework.

Parameters:

name - The name of the header

Returns:

the value for the header

Throws:

XQMessageException - thrown if there is an error

setHeaderValue

void setHeaderValue(java.lang.String name,
                    java.lang.Object value)
                    throws XQMessageException

Sets a header value with the specified name into the message header. This method can be utilized to set both user-defined and transport level headers.

Parameters:

name - The name of the header

value - The value of the header

Throws:

XQMessageException - thrown if there is an error

setBooleanHeader

void setBooleanHeader(java.lang.String name,
                      boolean value)
                      throws XQMessageException

Sets the user-defined boolean header value with the specified name into the message header.

Parameters:

name - The name of the header

value - The value of the header

Throws:

XQMessageException - thrown if there is an error

setByteHeader

void setByteHeader(java.lang.String name,
                   byte value)
                   throws XQMessageException

Sets the user-defined byte header value with the specified name into the message header.

Parameters:

name - The name of the header

value - The value of the header

Throws:

XQMessageException - thrown if there is an error

setDoubleHeader

void setDoubleHeader(java.lang.String name,
                     double value)
                     throws XQMessageException

Sets the user-defined double header value with the specified name into the message header.

Parameters:

name - The name of the header

value - The value of the header

Throws:

XQMessageException - thrown if there is an error

setFloatHeader

void setFloatHeader(java.lang.String name,
                    float value)
                    throws XQMessageException

Sets the user-defined float header value with the specified name into the message header.

Parameters:

name - The name of the header

value - The value of the header

Throws:

XQMessageException - thrown if there is an error

setIntHeader

void setIntHeader(java.lang.String name,
                  int value)
                  throws XQMessageException

Sets the user-defined int header value with the specified name into the message header.

Parameters:

name - The name of the header

value - The value of the header

Throws:

XQMessageException - thrown if there is an error

setLongHeader

void setLongHeader(java.lang.String name,
                   long value)
                   throws XQMessageException

Sets the user-defined long header value with the specified name into the message header.

Parameters:

name - The name of the header

value - The value of the header

Throws:

XQMessageException - thrown if there is an error

setStringHeader

void setStringHeader(java.lang.String name,
                     java.lang.String value)
                     throws XQMessageException

Sets the user-defined String header value with the specified name into the message header.

Parameters:

name - The name of the header

value - The value of the header

Throws:

XQMessageException - thrown if there is an error

setShortHeader

void setShortHeader(java.lang.String name,
                    short value)
                    throws XQMessageException

Sets the user-defined short header value with the specified name into the message header.

Parameters:

name - The name of the header

value - The value of the header

Throws:

XQMessageException - thrown if there is an error

setHeaderValues

void setHeaderValues(java.util.Map<java.lang.String,java.lang.Object> headers)
                     throws XQMessageException

Sets multiple header values into the message header. Each name, value pair in the Map is added to the message header. This method can be utilized to set both user-defined and transport level headers.

Parameters:

headers - A Map containing name value pairs to add to the message

Throws:

XQMessageException - thrown if there is an error

removeHeader

java.lang.Object removeHeader(java.lang.String name)
                              throws XQMessageException

Remove the named header from the message header. This method can be utilized to remove both user-defined and transport level headers.

Parameters:

name - The name of the header.

Returns:

The value of the header that has been removed

Throws:

XQMessageException - thrown if there is an error

getPartCount

int getPartCount()
                 throws XQMessageException

Gets the count of the number of Parts for the XQMessage.

Returns:

The number of Parts.

Throws:

XQMessageException - thrown if there is an error

getPart

XQPart getPart(int index)
               throws XQMessageException

Gets the XQPart from the XQMessage by its index

Parameters:

index - The 0-based array index of the part requested.

Returns:

The XQPart

Throws:

XQMessageException - thrown if there is an error

getPart

XQPart getPart(java.lang.String cid)
               throws XQMessageException

Gets the XQPart from the XQMessage by its Content-Id.

Parameters:

cid - The Content-Id of the part requested.

Returns:

The XQPart

Throws:

XQMessageException - thrown if there is an error

getPartAsDocument

org.w3c.dom.Document getPartAsDocument(java.lang.String cid,
                                       boolean validate)
                                       throws XQMessageException

Gets the XQPart from the XQMessage by its Content-Id, and returns it as a DOM document. If the content of the part cannot be parsed, an exception is thrown.

Parameters:

cid - Content-Id of the part to fetch.

validate - Whether to perform XML Schema validation during parsing.

Returns:

DOM document

Throws:

XQMessageException - on error.

getPartAsDocument

org.w3c.dom.Document getPartAsDocument(int index,
                                       boolean validate)
                                       throws XQMessageException

Gets the XQPart from the XQMessage by index, and returns it as a DOM document. If the content of the part cannot be parsed, an exception is thrown.

Parameters:

index - Zero-based index of the part to fetch.

validate - Whether to perform XML Schema validation during parsing.

Returns:

DOM document

Throws:

XQMessageException - on error.

setPartFromDocument

void setPartFromDocument(java.lang.String cid,
                         org.w3c.dom.Document doc)
                         throws XQMessageException

Create a new XQPart for this message from a DOM document.

Parameters:

cid - Content-Id for the new part.

doc - DOM document to serialize into the part.

Throws:

XQMessageException - on error.

setPartFromDocument

void setPartFromDocument(int index,
                         org.w3c.dom.Document doc)
                         throws XQMessageException

Create a new XQPart for this message from a DOM document.

Parameters:

index - Zero-based index for the new part.

doc - DOM document to serialize into the part.

Throws:

XQMessageException - on error.

createPart

XQPart createPart(java.lang.Object content,
                  java.lang.String contentType)
                  throws XQMessageException

Creates a part with the specified content and content-type. The Part is not automatically added to the Message.

Parameters:

content - The content of the part.

contentType - The Content-Type associated with the content.

Returns:

the newly created part

Throws:

XQMessageException - thrown if there is an error

createPart

XQPart createPart()
                  throws XQMessageException

Creates an empty part. The Part is not automatically added to the Message.

Returns:

the newly created part

Throws:

XQMessageException - thrown if there is an error

addPart

void addPart(XQPart part)
             throws XQMessageException

Adds a part to the XQMessage. The part is added to the end of the message.

Parameters:

part - The XQPart to be added.

Throws:

XQMessageException - thrown if the message already contains a part with the same ContentID as the part being added.

addPartAt

void addPartAt(XQPart part,
               int index)
               throws XQMessageException

Adds a part to the XQMessage. The part is added at the specified position.

Parameters:

part - The XQPart to be added.

index - The 0-based index where to add the part

Throws:

XQMessageException - thrown if the message already contains a part with the same ContentID as the part being added.

replacePart

void replacePart(XQPart part,
                 int index)
                 throws XQMessageException

Replace the XQPart at the specified location with a new part.

Parameters:

part - the new part to be used in the message

index - the 0-based index of the part to replace.

Throws:

XQMessageException - thrown if there is an error or if no parts exist at the specified index

replacePart

void replacePart(XQPart part,
                 java.lang.String cid)
                 throws XQMessageException

Replace the XQPart with the specified Content-ID with a new part.

Parameters:

part - the new part to be used in the message

cid - the Content-ID of the part to replace.

Throws:

XQMessageException - thrown if there is an error or if no parts exist with the specified cid.

removePart

void removePart(int index)
                throws XQMessageException

Removes a Part from the Message.

Parameters:

index - the 0-based index of the part to remove.

Throws:

XQMessageException - thrown if there is an error

removePart

void removePart(java.lang.String contentID)
                throws XQMessageException

Removes a Part from the Message.

Parameters:

contentID - The Content-Id of the part to remove

Throws:

XQMessageException - thrown if there is an error

removeAllParts

void removeAllParts()
                    throws XQMessageException

Remove all Parts from the Message.

Throws:

XQMessageException

doesPartExist

boolean doesPartExist(java.lang.String cid)

Returns true if a part with the given content-Id exists in the message, false otherwise.

Parameters:

cid - Content-Id to check.

Returns:

true if a part with the given content-Id exists in the message, false otherwise.

getReplyTo

XQAddress getReplyTo()
                     throws XQMessageException

Get the Reply To address for this message.

Returns:

The address, null if no ReplyTo is defined for the message

Throws:

XQMessageException - thrown if there is an error

setCorrelationId

void setCorrelationId(java.lang.String id)
                      throws XQMessageException

Sets the CorrelationID for this message.

Throws:

XQMessageException - thrown if there is an error

getCorrelationId

java.lang.String getCorrelationId()
                                  throws XQMessageException

Get the CorrelationID for this message.

Returns:

String id or null if no correlationID is defined for the message

Throws:

XQMessageException - thrown if there is an error

setReplyTo

void setReplyTo(XQAddress replyTo)
                throws XQMessageException

Sets the Reply To address for this message.

Throws:

XQMessageException - thrown if there is an error