JMSMessage

 

public abstract class JMSMessage
extends Object
implements MessageSerializable 

java.lang.Object
   |
   +----com.ibm.jms.JMSMessage

The Message interface is the root interface of all JMS messages. It defines the JMS header and the acknowledge() method used for all messages. The header contains fields used for message routing and identification. The payload contains the application data being sent.

JMS Messages are composed of the following parts:

JMS defines five types of message body:

The JMSCorrelationID header field is used to link one message with another. It typically links a reply message with its requesting message.

JMSCorrelationID can hold either a provider-specific message ID, an application-specific String, or a provider-specific byte[] value.

A Message contains a built-in facility for supporting application-defined property values. In effect, this provides a mechanism for adding application-specific header fields to a message.

Properties allow an application, via message selectors, to have a JMS provider select and filter messages on its behalf using application-specific criteria.

Property names must obey the rules for the selector identifier of a message.

Property values can be boolean, byte, short, int, long, float, double, and String.

Property values are set prior to sending a message. When a client receives a message, its properties are in read-only mode. If a client attempts to set properties at this point, a MessageNotWriteableException is thrown. If clearProperties() is called, the properties can then be both read from and written to.

A property value might duplicate a value in a message's body or it might not. Although JMS does not define a policy for what should or should not be made a property, JMS handles data in a message's body more efficiently than data in a message's properties. For best performance, only use message properties when we need to customize a message's header. The primary reason for doing this is to support customized message selection.

Message properties support the following conversion table. The marked cases are supported. The unmarked cases throw a JMSException. The String to primitive conversions might 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
 -------------------------------------------------------------

In addition to the type-specific set and get methods for properties, JMS provides the setObjectProperty() and getObjectProperty() methods. These support the same set of property types using the 'objectified' primitive values. Their purpose is to allow the property type to be decided at execution time rather than at compile time. They support the same property value conversions.

The setObjectProperty() method accepts values of class Boolean, Byte, Short, Integer, Long, Float, Double and String. An attempt to use any other class throws a JMSException.

The getObjectProperty() method only returns values of class Boolean, Byte, Short, Integer, Long, Float, Double and String.

The order of property values is not defined. To iterate through a message's property values, use getPropertyNames() to retrieve a property name Enumeration and then use the various property getter methods to retrieve their values.

A message's properties are deleted by the clearProperties() method. This leaves the message with an empty set of properties.

Getting a property value for a name which has not been set returns a null value. Only the getStringProperty() and getObjectProperty() methods can return a null value. The other property get methods throw a java.lang.NullPointerException if they are used to get a nonexistent property.

JMS reserves the `JMSX' property name prefix for JMS defined properties. The full set of these properties is defined in the Java Message Service specification. The String[] ConnectionMetaData.getJMSXPropertyNames() method returns the names of the JMSX properties supported by a connection.

JMSX properties can be referenced in message selectors whether or not they are supported by a connection. They are treated like any other absent property.

JSMX properties `set by provider on send' are available to both the producer and the consumers of the message. JSMX properties `set by provider on receive' are only available to the consumers.

JMSXGroupID and JMSXGroupSeq are simply standard properties that clients can use if they want to group messages. All providers must support them. Unless specifically noted, the values and semantics of the JMSX properties are undefined.

JMS reserves the `JMS_' property name prefix.

If an application tries to set a message property with a name that commences JMS, but the name is not one of the names in the following list, WebSphere MQ JMS throws an exception:


uj26410_