Sonic ESB API

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

Sonic ESB API

Copyright © 2001-2012 Progress Software Corporation. All Rights Reserved.
HTML formatted on 13-Mar-2012.