Class Message

The Message interface is the root interface of all JMS messages. It defines the message header and the acknowledge method used for all messages.

Most message-oriented middleware (MOM) products treat messages as lightweight entities that consist of a header and a payload. The header contains fields used for message routing and identification; the payload contains the application data being sent.

Within this general form, the definition of a message varies significantly across products. It would be quite difficult for the JMS API to support all of these message models.

With this in mind, the JMS message model has the following goals:

JMS messages are composed of the following parts:

Message Bodies

The JMS API defines Text and Bytes as message body:

Message Headers

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

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

Message Properties

A Message object 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, or filter, messages on its behalf using application-specific criteria.

Property names must obey the rules for a message selector identifier. Property names must not be null, and must not be empty strings. If a property name is set and it is either null or an empty string, an IllegalArgumentException must be thrown.

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 now be both read from and written to. Note that header fields are distinct from properties. Header fields are never in read-only mode.

A property value may duplicate a value in a message's body, or it may not. Although JMS does not define a policy for what should or should not be made a property, application developers should note that JMS providers will likely handle data in a message's body more efficiently than data in a message's properties. For best performance, applications should use message properties only when they 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 must be supported. The unmarked cases must throw a JMSException. The String-to-primitive conversions may throw a runtime exception if the primitive's valueOf method does not accept the String as a valid representation of the primitive.

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 get 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. Attempting to read a null value as a primitive type must be treated as calling the primitive's corresponding valueOf(String) conversion method with a null value.

The JMS API reserves the JMSX property name prefix for JMS defined properties. The full set of these properties is defined in the Java Message Service specification. New JMS defined properties may be added in later versions of the JMS API. Support for these properties is optional. The String[] ConnectionMetaData.getJMSXPropertyNames method returns the names of the JMSX properties supported by a connection.

JMSX properties may be referenced in message selectors whether or not they are supported by a connection. If they are not present in a message, they are treated like any other absent property.

JMSX properties defined in the specification as "set by provider on send" are available to both the producer and the consumers of the message. JMSX properties defined in the specification as "set by provider on receive" are available only to the consumers.

JMSXGroupID and JMSXGroupSeq are standard properties that clients should 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.

The JMS API reserves the JMS_vendor_name property name prefix for provider-specific properties. Each provider defines its own value for vendor_name. This is the mechanism a JMS provider uses to make its special per-message services available to a JMS client.

The purpose of provider-specific properties is to provide special features needed to integrate JMS clients with provider-native clients in a single JMS application. They should not be used for messaging between JMS clients.

Provider Implementations of JMS Message Interfaces

The JMS API provides a set of message interfaces that define the JMS message model. It does not provide implementations of these interfaces.

Each JMS provider supplies a set of message factories with its Session object for creating instances of messages. This allows a provider to use message implementations tailored to its specific needs.

A provider must be prepared to accept message implementations that are not its own. They may not be handled as efficiently as its own implementation; however, they must be handled.

Note the following exception case when a provider is handling a foreign message implementation. If the foreign message implementation contains a JMSReplyTo header field that is set to a foreign destination implementation, the provider is not required to handle or preserve the value of this header field.


Field Summary
int DEFAULT_DELIVERY_MODE
          The message producer's default delivery mode is PERSISTENT.
int DEFAULT_PRIORITY
          The message producer's default priority is 4.
int DEFAULT_TIME_TO_LIVE
          The message producer's default time to live is unlimited; the message never expires.
 
Constructor Summary
Message()
            The Message interface is the root interface of all JMS messages.
 
Method Summary
 void acknowledge()
           Acknowledges all consumed messages of the session of this consumed message.
 void clearBody()
           Clears out the message body.
 void clearProperties()
           Clears a message's properties.
 Boolean getBooleanProperty(name)
           Returns the value of the Boolean property with the specified name.
 Number getByteProperty(name)
           Returns Number representing byte value with the specified name.
 Number getDoubleProperty(name)
           Returns Number representing double value with the specified name.
 Number getFloatProperty(name)
           Returns the value of the float property with the specified name.
 Number getIntProperty(name)
           Returns Number representing int value with the specified name.
 String getJMSCorrelationID()
           Gets the correlation ID for the message.
 Number getJMSDeliveryMode()
           Gets the DeliveryMode value specified for this message.
 Destination getJMSDestination()
           Gets the Destination object for this message.
 Number getJMSExpiration()
           Gets the message's expiration value.
 String getJMSMessageID()
           Gets the message ID.
 Number getJMSPriority()
           Gets the message priority level.
 boolean getJMSRedelivered()
           Gets an indication of whether this message is being redelivered.
 Destination getJMSReplyTo()
           Gets the Destination object to which a reply to this message should be sent.
 Number getJMSTimestamp()
           Gets the message timestamp.
 String getJMSType()
           Gets the message type identifier supplied by the client when the message was sent.
 Number getLongProperty(name)
           Returns Number representing long value with the specified name.
 void  getObjectProperty(name)
           Returns the value of the object property with the specified name.
 Enumeration getPropertyNames()
           Returns an Enumeration of all the property names.
 Number getShortProperty(name)
           Returns Number representing short value with the specified name.
 String getStringProperty(name)
           Returns the value of the String property with the specified name.
 boolean propertyExists(name)
           Indicates whether a property value exists.
 void setBooleanProperty(name, value)
           Sets a Boolean property value with the specified name into the message.
 void setByteProperty(name, value)
           Sets a Number representing byte value with the specified name into the message.
 void setDoubleProperty(name, value)
           Sets a Number representing double value with the specified name into the message.
 void setFloatProperty(name, value)
           Sets a Number representing float value with the specified name into the message.
 void setIntProperty(name, value)
           Sets a Number representing int value with the specified name into the message.
 void setJMSCorrelationID(correlationID)
           Sets the correlation ID for the message.
 void setJMSDeliveryMode(deliveryMode)
           Sets the DeliveryMode value for this message.
 void setJMSDestination(destination)
           Sets the Destination object for this message.
 void setJMSExpiration(expiration)
           Sets the message's expiration value.
 void setJMSMessageID(id)
           Sets the message ID.
 void setJMSPriority(priority)
           Sets the priority level for this message.
 void setJMSRedelivered(redelivered)
           Specifies whether this message is being redelivered.
 void setJMSReplyTo(replyTo)
           Sets the Destination object to which a reply to this message should be sent.
 void setJMSTimestamp(timestamp)
           Sets the message timestamp.
 void setJMSType(type)
           Sets the message type.
 void setLongProperty(name, value)
           Sets a Number representing long value for a property.
 void setObjectProperty(name, value)
           Sets a object property value with the specified name into the message.
 void setShortProperty(name, value)
           Sets a Number representing short value with the specified name into the message.
 void setStringProperty(name, value)
           Sets a String property value with the specified name into the message.
 
Field Detail

DEFAULT_DELIVERY_MODE

int DEFAULT_DELIVERY_MODE

DEFAULT_PRIORITY

int DEFAULT_PRIORITY

DEFAULT_TIME_TO_LIVE

int DEFAULT_TIME_TO_LIVE

Constructor Detail

Message

Message()

Method Detail

acknowledge

void acknowledge()

clearBody

void clearBody()

clearProperties

void clearProperties()

getBooleanProperty

Boolean getBooleanProperty(name)

getByteProperty

Number getByteProperty(name)

getDoubleProperty

Number getDoubleProperty(name)

getFloatProperty

Number getFloatProperty(name)

getIntProperty

Number getIntProperty(name)

getJMSCorrelationID

String getJMSCorrelationID()

getJMSDeliveryMode

Number getJMSDeliveryMode()

getJMSDestination

Destination getJMSDestination()

getJMSExpiration

Number getJMSExpiration()

getJMSMessageID

String getJMSMessageID()

getJMSPriority

Number getJMSPriority()

getJMSRedelivered

boolean getJMSRedelivered()

getJMSReplyTo

Destination getJMSReplyTo()

getJMSTimestamp

Number getJMSTimestamp()

getJMSType

String getJMSType()

getLongProperty

Number getLongProperty(name)

getObjectProperty

void  getObjectProperty(name)

getPropertyNames

Enumeration getPropertyNames()

getShortProperty

Number getShortProperty(name)

getStringProperty

String getStringProperty(name)

propertyExists

boolean propertyExists(name)

setBooleanProperty

void setBooleanProperty(name, value)

setByteProperty

void setByteProperty(name, value)

setDoubleProperty

void setDoubleProperty(name, value)

setFloatProperty

void setFloatProperty(name, value)

setIntProperty

void setIntProperty(name, value)

setJMSCorrelationID

void setJMSCorrelationID(correlationID)

setJMSDeliveryMode

void setJMSDeliveryMode(deliveryMode)

setJMSDestination

void setJMSDestination(destination)

setJMSExpiration

void setJMSExpiration(expiration)

setJMSMessageID

void setJMSMessageID(id)

setJMSPriority

void setJMSPriority(priority)

setJMSRedelivered

void setJMSRedelivered(redelivered)

setJMSReplyTo

void setJMSReplyTo(replyTo)

setJMSTimestamp

void setJMSTimestamp(timestamp)

setJMSType

void setJMSType(type)

setLongProperty

void setLongProperty(name, value)

setObjectProperty

void setObjectProperty(name, value)

setShortProperty

void setShortProperty(name, value)

setStringProperty

void setStringProperty(name, value)