IBM WebSphere Application ServerTM
Release 7

com.ibm.websphere.sib
Interface SIMessage

All Superinterfaces:
java.lang.Cloneable, java.io.Serializable

public interface SIMessage
extends java.lang.Cloneable, java.io.Serializable

The SIMessage interface is the public interface to an SIBus message for use by Mediations as well as other SIBus components.


Method Summary
 void clearMessageProperties()
          Delete all the Properties from the Message.
 void clearReplyFields()
          Clear the four ReplyXxxx fields in the message header.
 void clearUserProperties()
          Delete all the User Properties from the Message.
 java.lang.Object clone()
          Obtain a new SIMessage which is a clone of this SIMessage.
 void deleteMessageProperty(java.lang.String name)
          Delete the Property with the given name from the Message.
 void deleteUserProperty(java.lang.String name)
          Delete the User Property with the given name from the Message.
 java.lang.String getApiMessageId()
          Get the contents of the ApiMessageId field from the message API Meta-Data.
 java.lang.String getCorrelationId()
          Get the contents of the CorrelationId field from the message API Meta-Data.
 commonj.sdo.DataGraph getDataGraph()
          Return the SDO DataGraph which contains the SIMessage content in a tree representation using the existing Data Mediator.
 byte[] getDataGraphAsBytes()
          Provide access to the message payload information in the form of a new byte array.
 java.lang.String getDiscriminator()
          Get the contents of the topic Discriminator field from the message header.
 java.lang.String getFormat()
          Get the contents of the Format field from the message API Meta-Data.
 java.util.List getForwardRoutingPath()
          Get the contents of the ForwardRoutingPath for this SIMessage.
 java.io.Serializable getMessageProperty(java.lang.String name)
          Return the Property stored in the Message under the given name.
 commonj.sdo.DataGraph getNewDataGraph(java.lang.String format)
          Return a new SDO DataGraph which contains a copy of the SIMessage content in the tree representation specified by the format field.
 int getPriority()
          Get the value of the Priority field from the message header.
 int getRedeliveredCount()
          Get the value of the RedeliveredCount field from the message header.
 Reliability getReliability()
          Get the value of the Reliability field from the message header.
 long getRemainingTimeToLive()
          Get the remaining time in milliseconds before the message expires.
 java.lang.String getReplyDiscriminator()
          Get the contents of the ReplyDiscriminator field from the message header.
 int getReplyPriority()
          Get the value of the ReplyPriority field from the message header.
 Reliability getReplyReliability()
          Get the value of the ReplyReliability field from the message header.
 long getReplyTimeToLive()
          Get the value of the ReplyTimeToLive field from the message header.
 java.util.List getReverseRoutingPath()
          Get the contents of the ReverseRoutingPath for this SIMessage.
 java.lang.String getSystemMessageId()
          Get the unique System Message Id from the message header.
 long getTimeToLive()
          Get the value of the TimeToLive field from the message header.
 java.lang.String getUserId()
          Get the contents of the UserId field from the message API Meta-Data.
 java.io.Serializable getUserProperty(java.lang.String name)
          Return the User Property stored in the Message under the given name.
 java.util.List getUserPropertyNames()
          Get a list of the names of the User Properties in the message.
 boolean isWellFormed()
          Check if the DataGraph currently set in the message is valid.
 void setApiMessageId(java.lang.String value)
          Set the contents of the ApiMessageId field in the message API Meta-Data.
 void setCorrelationId(java.lang.String value)
          Set the contents of the CorrelationId field in the message API Meta-Data.
 void setDataGraph(commonj.sdo.DataGraph newDataGraph, java.lang.String format)
          Set the SIMessage content to a a new SDO DataGraph tree representation.
 void setDiscriminator(java.lang.String value)
          Set the contents of the topic Discriminator field in the message header.
 void setForwardRoutingPath(java.util.List value)
          Set the ForwardRoutingPath for this SIMessage.
 void setMessageProperty(java.lang.String name, java.io.Serializable item)
          Add an item to the Message Properties under the given name.
 void setPriority(int value)
          Set the value of the Priority field in the message header.
 void setReliability(Reliability value)
          Set the value of the Reliability field in the message header.
 void setRemainingTimeToLive(long value)
          Set the remaining time in milliseconds before the message should expire.
 void setReplyDiscriminator(java.lang.String value)
          Set the contents of the ReplyDiscriminator field in the message header.
 void setReplyPriority(int value)
          Set the value of the ReplyPriority field in the message header.
 void setReplyReliability(Reliability value)
          Set the value of the ReplyReliability field in the message header.
 void setReplyTimeToLive(long value)
          Set the value of the ReplyTimeToLive field in the message header.
 void setReverseRoutingPath(java.util.List value)
          Set the ReverseRoutingPath for this SIMessage.
 void setTimeToLive(long value)
          Set the value of the TimeToLive field in the message header.
 void setUserId(java.lang.String value)
          Set the contents of the UserId field in the message API Meta-Data.
 void setUserProperty(java.lang.String name, java.io.Serializable item)
          Add User Property to the message under the given name.
 

Method Detail

clone

java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Obtain a new SIMessage which is a clone of this SIMessage.

Returns:
Object A clone of the original SIMessage.
Throws:
java.lang.CloneNotSupportedException - The clone of the SIBusSdoMessage failed - see the exception text.

getDataGraph

commonj.sdo.DataGraph getDataGraph()
                                   throws SIDataGraphSchemaNotFoundException,
                                          SIMessageException
Return the SDO DataGraph which contains the SIMessage content in a tree representation using the existing Data Mediator.

Returns:
DataGraph The SDO DataGraph representing the SIMessage. null is returned if the format of the SIMessage is SIApiConstants.JMS_FORMAT
Throws:
SIDataGraphSchemaNotFoundException - is thrown if a schema needed to parse the message is not available.
SIMessageException - is thrown if the message can not be parsed for any other reason. The linked Exception(s) indicate the underlying problem.

getNewDataGraph

commonj.sdo.DataGraph getNewDataGraph(java.lang.String format)
                                      throws SIMessageDomainNotSupportedException,
                                             SIDataGraphSchemaNotFoundException,
                                             SIDataGraphFormatMismatchException,
                                             SIMessageException
Return a new SDO DataGraph which contains a copy of the SIMessage content in the tree representation specified by the format field.

Parameters:
format - A formatted String containing the Data Mediator indicator and any necessary meta-data.
Returns:
DataGraph A new SDO DataGraph representing the SIMessage. null is returned only if the format of the message AND the requested are both SIApiConstants.JMS_FORMAT.
Throws:
java.lang.NullPointerException - is thrown if the format parameter is null.
SIMessageDomainNotSupportedException - is thrown if the message domain indicated by the format is not supported.
SIDataGraphSchemaNotFoundException - is thrown if a schema needed to parse the message is not available.
SIDataGraphFormatMismatchException - is thrown if the format requested is not compatible with the data in the message.
SIMessageException - is thrown if the message can not be parsed for any other reason. The linked Exception(s) indicate the underlying problem.

setDataGraph

void setDataGraph(commonj.sdo.DataGraph newDataGraph,
                  java.lang.String format)
                  throws SIMessageDomainNotSupportedException,
                         SIDataGraphSchemaNotFoundException,
                         SIDataGraphFormatMismatchException,
                         SIMessageException
Set the SIMessage content to a a new SDO DataGraph tree representation.

Parameters:
newDataGraph - The SDO DataGraph which the SIMessage is to contain. Must be specified as null if the format parameter is SIApiConstants.JMS_FORMAT
format - The message format describing the DataGraph model.
Throws:
java.lang.NullPointerException - is thrown if either the newDataGraph or format parameter is null. Note that this exception is not thrown if the newDataGraph is null and the format parameter is SIApiConstants.JMS_FORMAT
SIMessageDomainNotSupportedException - is thrown if the message domain indicated by the format is not supported.
SIDataGraphSchemaNotFoundException - may be thrown if a schema indicated by the given format is not available.
SIDataGraphFormatMismatchException - may be thrown if the given format is not compatible with the given DataGraph.
SIMessageException - is thrown if the DataGraph can not be set into the message for any other reason. The linked Exception(s) indicate the underlying problem.

isWellFormed

boolean isWellFormed()
Check if the DataGraph currently set in the message is valid. If the DataGraph is not valid the message will not be able to be sent through the SIbus or stored in the message store.

Returns:
true if the message contains a well formed DataGraph.

getDataGraphAsBytes

byte[] getDataGraphAsBytes()
                           throws SIMessageException,
                                  SIDataGraphSchemaNotFoundException
Provide access to the message payload information in the form of a new byte array. The contents of the byte will depend upon the format of this message instance.

Returns:
a new byte array containing a serialized rendering of the message payload
Throws:
SIMessageException - is thrown if the message can not be parsed for any other reason. The linked Exception(s) indicate the underlying problem.
SIDataGraphSchemaNotFoundException - is thrown if a schema needed to parse the message is not available.

getMessageProperty

java.io.Serializable getMessageProperty(java.lang.String name)
                                        throws java.io.IOException,
                                               java.lang.ClassNotFoundException
Return the Property stored in the Message under the given name.

Message Properties are stored as name-value pairs where the value may be any Object which implements java.io.Serializable. This method may be used to get the accessable system (SI_) properties, JMS properties and user properties, however user property names must be prefixed by "user." when passed into this method.

The reference returned is to a copy of the Object stored in the Message, so any changes made to it will not be reflected in the Message.

Parameters:
name - The name of the Property to be returned. For a user property, the name must include the "user." prefix.
Returns:
Serializable A reference to the Message Property. Null is returned if there is no such item.
Throws:
java.io.IOException - De-serialization of the Property failed.
java.lang.ClassNotFoundException - De-serialization of the Property failed because a necessary Java Class could not be found.

setMessageProperty

void setMessageProperty(java.lang.String name,
                        java.io.Serializable item)
                        throws java.io.IOException
Add an item to the Message Properties under the given name.

Message Properties are stored as name-value pairs where the value may be any Object which implements java.io.Serializable. This method may be used to set the modifyable system (SI_) properties, JMS properties and user properties, however user property names must be prefixed by "user." when passed into this method.

If a Property with the given name already exists in the Message, it will be replaced by the Object passed in to this method.

If the given name is null, no data will be stored. If the Object passed in is null, this will have the effect of deleting the Property completely.

Parameters:
name - A String value used to access the Property in future. For a user property, the name must include the "user." prefix.
item - An Object which implements java.io.Serializable
Throws:
java.io.IOException - Serialization of the Property failed.

deleteMessageProperty

void deleteMessageProperty(java.lang.String name)
Delete the Property with the given name from the Message.

This method may be used to delete the modifyable system (SI_) properties, JMS properties and user properties, however user property names must be prefixed by "user." when passed into this method.

If the given name is null, no data will be deleted.

Parameters:
name - The String value of the Property to be deleted. For a user property, the name must include the "user." prefix.

clearMessageProperties

void clearMessageProperties()
Delete all the Properties from the Message.

This method deletes all the modifyable properties from the message. Note that some of the system (SI_) and JMS properties are not modifyable and therefore not clearable.


getUserProperty

java.io.Serializable getUserProperty(java.lang.String name)
                                     throws java.io.IOException,
                                            java.lang.ClassNotFoundException
Return the User Property stored in the Message under the given name.

Message Properties are stored as name-value pairs where the value may be any Object which implements java.io.Serializable. This method may only be used to retrieve user properties, and not to retrieve system (SI_) or JMS properties. The property name passed into the method should not include the "user." prefix.

The reference returned is to a copy of the Object stored in the Message, so any changes made to it will not be reflected in the Message.

Parameters:
name - The name of the Property to be returned.
Returns:
Serializable A reference to the Message Property. Null is returned if there is no such item.
Throws:
java.io.IOException - De-serialization of the Property failed.
java.lang.ClassNotFoundException - De-serialization of the Property failed because a necessary Java Class could not be found.

setUserProperty

void setUserProperty(java.lang.String name,
                     java.io.Serializable item)
                     throws java.io.IOException
Add User Property to the message under the given name.

Message Properties are stored as name-value pairs where the value may be any Object which implements java.io.Serializable. This method may only be used to set user properties, and not to set system (SI_) or JMS properties. The property name passed into the method should not include the "user." prefix.

If a Property with the given name already exists in the Message, it will be replaced by the Object passed in to this method.

If the given name is null, no data will be stored. If the Object passed in is null, this will have the effect of deleting the Property completely.

Parameters:
name - A String value used to access the Property in future.
item - An Object which implements java.io.Serializable
Throws:
java.io.IOException - Serialization of the Property failed.

deleteUserProperty

void deleteUserProperty(java.lang.String name)
Delete the User Property with the given name from the Message.

This method may only be used to delete user properties, and not to delete system (SI_) or JMS properties. The property name passed into the method should not include the "user." prefix.

If the given name is null, no data will be deleted.

Parameters:
name - The String value of the Property to be deleted.

clearUserProperties

void clearUserProperties()
Delete all the User Properties from the Message.

This method deletes all the user properties from the message.


getUserPropertyNames

java.util.List getUserPropertyNames()
Get a list of the names of the User Properties in the message.

This method returns a list of the names of the User Properties in the message. The names do not include the "user." prefix.

Returns:
List A List containing the String names of the User Properties. An empty list is returned if there are no user properties.

getForwardRoutingPath

java.util.List getForwardRoutingPath()
Get the contents of the ForwardRoutingPath for this SIMessage. The List returned is a copy of the ForwardRoutingPath so changes to it will not affect the SIMessage itself.

Returns:
A List containing the ForwardRoutingPath which is a set of SIDestinationAddresses. Null is returned if the field was not set.

setForwardRoutingPath

void setForwardRoutingPath(java.util.List value)
Set the ForwardRoutingPath for this SIMessage.

Parameters:
value - A List containing the ForwardRoutingPath which is a set of SIDestinationAddresses.
Throws:
java.lang.IllegalArgumentException - The List contains one or more entries which are not SIDestinationAdddresses.
java.lang.NullPointerException - The List contains one or more null entries.

getReverseRoutingPath

java.util.List getReverseRoutingPath()
Get the contents of the ReverseRoutingPath for this SIMessage. The List returned is a copy of the ReverseRoutingPath so changes to it will not affect the SIMessage itself.

Returns:
A List containing the ReverseRoutingPath which is a set of SIDestinationAddresses. Null is returned if the field was not set.

setReverseRoutingPath

void setReverseRoutingPath(java.util.List value)
Set the ReverseRoutingPath for this SIMessage.

Parameters:
value - A List containing the ReverseRoutingPath which is a set of SIDestinationAddresses.
Throws:
java.lang.IllegalArgumentException - The List contains one or more entries which are not SIDestinationAdddresses.
java.lang.NullPointerException - The List contains one or more null entries.

getPriority

int getPriority()
Get the value of the Priority field from the message header.

Returns:
An int containing the Priority of the message.

setPriority

void setPriority(int value)
Set the value of the Priority field in the message header.

Parameters:
value - An int containing the Priority of the message.
Throws:
java.lang.IllegalArgumentException - The value given is outside the permitted range.

getReliability

Reliability getReliability()
Get the value of the Reliability field from the message header.

Returns:
The Reliability instance representing the Reliability of the message (i.e. Express, Reliable or Assured). Reliability.UNKNOWN is returned if the field is not set.

setReliability

void setReliability(Reliability value)
Set the value of the Reliability field in the message header.

Throws:
java.lang.NullPointerException - Null is not a valid Reliability.

getTimeToLive

long getTimeToLive()
Get the value of the TimeToLive field from the message header. The value represents the time in milliseconds for the message to live counting from when it was orginally sent. A value of 0 indicates that the message will never expire.

Returns:
A long containing the TimeToLive of the message. The default value of 0 is returned if the field was not set.

setTimeToLive

void setTimeToLive(long value)
Set the value of the TimeToLive field in the message header. The value represents the time in milliseconds for the message to live counting from when it was orginally sent. A value of 0 indicates that the message should never expire.

Parameters:
value - A long containing the TimeToLive of the message.
Throws:
java.lang.IllegalArgumentException - The value given is less than 0 or greater than 290,000,000 years.

getRemainingTimeToLive

long getRemainingTimeToLive()
Get the remaining time in milliseconds before the message expires.

Returns:
A long containing the remaining time, in milliseconds, before the message expires. A negative number indicates that the message will never expire.

setRemainingTimeToLive

void setRemainingTimeToLive(long value)
Set the remaining time in milliseconds before the message should expire.

Parameters:
value - A long containing the remaining time, in milliseconds, before the message should expire. A negative number indicates that the message should never expire.
Throws:
java.lang.IllegalArgumentException - The resulting Time To Live is less than 0 or greater than 290,000,000 years.

getReplyPriority

int getReplyPriority()
Get the value of the ReplyPriority field from the message header.

Returns:
An Integer containing the Priority for any reply. The default value of 4 is returned if the field was not set.

setReplyPriority

void setReplyPriority(int value)
Set the value of the ReplyPriority field in the message header.

Parameters:
value - An int containing the Priority for any reply.
Throws:
java.lang.IllegalArgumentException - The value given is outside the permitted range.

getReplyReliability

Reliability getReplyReliability()
Get the value of the ReplyReliability field from the message header.

Returns:
The Reliability instance representing the Reliability for any reply message (i.e. Express, Reliable or Assured). Reliability.UNKNOWN is returned if the field is not set.

setReplyReliability

void setReplyReliability(Reliability value)
Set the value of the ReplyReliability field in the message header.

Throws:
java.lang.NullPointerException - Null is not a valid Reliability.

getReplyTimeToLive

long getReplyTimeToLive()
Get the value of the ReplyTimeToLive field from the message header. A value of 0 indicates that the reply message will never expire.

Returns:
A Long containing the TimeToLive for any reply. The default value of 0 is returned if the field was not set.

setReplyTimeToLive

void setReplyTimeToLive(long value)
Set the value of the ReplyTimeToLive field in the message header. A value of 0 indicates that the reply message should never expire.

Parameters:
value - A long containing the TimeToLive for any reply.
Throws:
java.lang.IllegalArgumentException - The value given is less than 0 or greater than 290,000,000 years.

clearReplyFields

void clearReplyFields()
Clear the four ReplyXxxx fields in the message header.


getDiscriminator

java.lang.String getDiscriminator()
Get the contents of the topic Discriminator field from the message header.

Returns:
A String containing the Discriminator for Pub/Sub Null is returned if the field was not set.

setDiscriminator

void setDiscriminator(java.lang.String value)
Set the contents of the topic Discriminator field in the message header.

Parameters:
value - A String containing the Discriminator for Pub/Sub The Discriminator is a simplified XPATH expression without wild cards. It is considered valid if the following expression is true: java.util.regex.Pattern.matches("([^:./*][^:/*]*)(/[^:./*][^:/*]*)*",value);
Throws:
java.lang.IllegalArgumentException - The value given contains wild cards or is otherwise invalid.

getReplyDiscriminator

java.lang.String getReplyDiscriminator()
Get the contents of the ReplyDiscriminator field from the message header.

Returns:
A String containing the Discriminator for any reply. Null is returned if the field was not set.

setReplyDiscriminator

void setReplyDiscriminator(java.lang.String value)
Set the contents of the ReplyDiscriminator field in the message header.

Parameters:
value - A String containing the Discriminator for any reply. The Discriminator is a simplified XPATH expression without wild cards. It is considered valid if the following expression is true: java.util.regex.Pattern.matches("([^:./*][^:/*]*)(/[^:./*][^:/*]*)*",value);
Throws:
java.lang.IllegalArgumentException - The value given contains wild cards or is otherwise invalid.

getSystemMessageId

java.lang.String getSystemMessageId()
Get the unique System Message Id from the message header.

Returns:
A String containing the system message id. Null is returned if the field has not yet been set.

getRedeliveredCount

int getRedeliveredCount()
Get the value of the RedeliveredCount field from the message header.

Returns:
An int representation of the RedeliveredCount of the message.

getApiMessageId

java.lang.String getApiMessageId()
Get the contents of the ApiMessageId field from the message API Meta-Data.

Returns:
A String containing the ApiMessageId. Null is returned if the field has not been set.

setApiMessageId

void setApiMessageId(java.lang.String value)
Set the contents of the ApiMessageId field in the message API Meta-Data.

Parameters:
value - A String containing the ApiMessageId.
Throws:
java.lang.IllegalArgumentException - The value given must be of the form ID:xxxx where xxxx represents an even number of hexadecimal digits.

getCorrelationId

java.lang.String getCorrelationId()
Get the contents of the CorrelationId field from the message API Meta-Data.

Returns:
A String containing the CorrelationId. Null is returned if the field has not been set.

setCorrelationId

void setCorrelationId(java.lang.String value)
Set the contents of the CorrelationId field in the message API Meta-Data.

Parameters:
value - A String containing the CorrelationId.
Throws:
java.lang.IllegalArgumentException - The value given must be either be of the form ID:xxxx, where xxxx represents an even number of hexadecimal digits, or must be an arbitrary String which does not start with ID:.

getUserId

java.lang.String getUserId()
Get the contents of the UserId field from the message API Meta-Data.

Returns:
A String containing the UserId. Null is returned if the field has not been set.

setUserId

void setUserId(java.lang.String value)
Set the contents of the UserId field in the message API Meta-Data.

Parameters:
value - A String containing the UserId.

getFormat

java.lang.String getFormat()
Get the contents of the Format field from the message API Meta-Data.

Returns:
A String containing the Format. Null is returned if the field has not been set.

IBM WebSphere Application ServerTM
Release 7