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 you 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.
public void acknowledge() throws JMSException;
Acknowledges this and all previous messages received. Calling this method also acknowledges all other messages received by the session that received this message.
public void clearProperties() throws JMSException;
Clears a message's properties.
public boolean getBooleanProperty(String name) throws JMSException;
Gets the boolean property value with the given name.
public byte getByteProperty(String name) throws JMSException;
Gets the byte property value with the given name.
public double getDoubleProperty(String name) throws JMSException;
Gets the double property value with the given name.
public float getFloatProperty(String name) throws JMSException;
Gets the float property value with the given name.
public int getIntProperty(String name) throws JMSException;
Gets the integer property value with the given name.
public String getJMSCorrelationID() throws JMSException;
Gets the correlation ID for the message.
This method is used to return correlation ID values that are either provider-specific message IDs or application-specific Strings.
public byte[] getJMSCorrelationIDAsBytes() throws JMSException;
Gets the correlation ID as an array of bytes for the message.
The use of a byte[] value for JMSCorrelationID is not portable.
public int getJMSDeliveryMode() throws JMSException;
Gets the delivery mode for this message.
public Destination getJMSDestination() throws JMSException;
Gets the destination for this message.
The destination field contains the destination to which the message is being sent.
When a message is sent, this value is ignored. After completion of the send method it holds the destination specified by the send.
When a message is received, its destination value must be equivalent to the value assigned when it was sent.
public long getJMSExpiration() throws JMSException;
Gets the message's expiration value.
When a message is sent, expiration is left unassigned. After completion of the send method, it holds the expiration time of the message. This is the time-to-live value specified by the client added to the time (GMT) when the message was sent.
If the time-to-live is specified as zero, expiration is set to zero which indicates the message does not expire.
When a message's expiration time is reached, a provider will discard it. JMS does not define any form of notification of message expiration.
Clients should not receive messages that have expired, although JMS does not guarantee that this will not happen.
public String getJMSMessageID() throws JMSException;
Gets the message ID.
The messageID header field contains a value that uniquely identifies each message sent by a provider.
When a message is sent, messageID can be ignored. When the send() method returns, it contains a provider-assigned value.
A JMSMessageID is a String value which functions as a unique key for identifying messages in a historical repository. The exact scope of uniqueness is provider defined. It must at least cover all messages for a specific installation of a provider where an installation is some connected set of message routers.
All JMSMessageID values must start with the prefix `ID:'. Uniqueness of message ID values across different providers is not required.
There is an overhead in creating a message ID and it also increases a message's size. Some JMS providers can optimize this overhead if they are given a hint that the message ID is not used by an application. JMS message Producers provide a hint to disable the message ID. When a client sets a Producer to disable the message ID it indicates they are saying that they do not depend on the value of the message ID for the messages it produces. These messages must either have message ID set to null or, if the hint is ignored, the messageID must be set to its normal unique value.
public int getJMSPriority() throws JMSException;
Gets the message priority.
JMS defines ten levels of priority with 0 as the lowest and 9 as the highest. In addition, clients should consider priorities 0-4 as gradations of normal priority and priorities 5-9 as gradations of expedited priority.
JMS does not require that a provider strictly implement priority ordering of messages; however, it must do its best to deliver expedited messages ahead of normal messages.
public boolean getJMSRedelivered() throws JMSException;
Gets an indication of whether this message is being re-delivered.
If a client receives a message with the re-delivered indicator set, it is likely, but not guaranteed, that this message was delivered to the client earlier but the client did not acknowledge its receipt at that earlier time.
public Destination getJMSReplyTo() throws JMSException;
Gets the destination to which a reply to this message can be sent.
public long getJMSTimestamp() throws JMSException;
Gets the message timestamp.
The JMSTimestamp header field contains the time a message was handed to a provider to be sent. It is not the time the message was actually transmitted because that might occur later due to transactions or other client-side queueing of messages.
When a message is sent, JMSTimestamp is ignored. When the send method returns, it contains a time somewhere between the call and the return. It is in the format of a normal Java millisecond time value.
public String getJMSType() throws JMSException;
Gets the message type.
public long getLongProperty(String name) throws JMSException;
Gets the long property value with the given name.
public Object getObjectProperty(String name) throws JMSException;
Gets the Java object property value with the given name.
This method can be used to return, in objectified format, an object that had been stored as a property in the Message with the equivalent setObject() method call, or its equivalent primitive setter method.
public Enumeration getPropertyNames() throws JMSException;
Gets an Enumeration of all the property names.
public short getShortProperty(String name) throws JMSException;
Gets the short property value with the given name.
public String getStringProperty(String name) throws JMSException;
Gets the String property value with the given name.
public boolean propertyExists(String name) throws JMSException;
Indicates whether a named property exists in the message properties Hashtable.
public void setBooleanProperty(String name, boolean value) throws JMSException;
Sets a boolean property value with the given name in the message.
public void setByteProperty(String name, byte value) throws JMSException;
Sets a byte property value with the given name in the message.
public void setDoubleProperty(String name, double value) throws JMSException;
Sets a double property value with the given name in the message.
public void setFloatProperty(String name, float value) throws JMSException;
Sets a float property value with the given name in the message.
public void setIntProperty(String name, int value) throws JMSException;
Sets an integer property value with the given name in the message.
public void setJMSCorrelationID(String correlationID) throws JMSException;
Sets the correlation ID for the message.
A client can use the JMSCorrelationID header field to link one message with another. A typical use is to link a response message with its request message.
JMSCorrelationID can hold one of the following:
Since each message sent by a JMS provider is assigned a message ID, it is convenient to link messages using their message IDs. All message ID values must start with the 'ID:' prefix.
In some cases, an application (made up of several clients) needs to use an application-specific value for linking messages. For example, an application might use JMSCorrelationID to hold a value referencing some external information. Application-specified values must not start with the 'ID:' prefix; this is reserved for provider-generated message ID values.
If a provider supports the native concept of correlation ID, a JMS client might need to assign specific JMSCorrelationID values to match those expected by non-JMS clients. A byte[] value is used for this purpose. JMS providers without native correlation ID values are not required to support byte[] values. The use of a byte[] value for JMSCorrelationID is not portable.
public void setJMSCorrelationIDAsBytes(byte[] correlID) throws JMSException;
Sets the correlation ID as an array of bytes for the message.
If a provider supports the native concept of correlation id, a JMS client might need to assign specific JMSCorrelationID values to match those expected by non-JMS clients. JMS providers without native correlation ID values are not required to support this (and the corresponding get) method and the corresponding get method Their implementation might throw java.lang.UnsupportedOperationException.
A client can use this call to set the correlationID either to a messageID from a previous message, or to an application-specific string. Application-specific strings must not start with the characters 'ID:'.
The use of a byte[] value for JMSCorrelationID is not portable.
public void setJMSDeliveryMode(int deliveryMode) throws JMSException;
Sets the delivery mode for this message.
Any value set using this method is ignored when the message is sent, but this method can be used to change the value in a received message.
To alter the delivery mode when a message is sent, use the setDeliveryMode() method on the QueueSender or TopicPublisher (this method is inherited from MessageProducer).
public void setJMSDestination(Destination destination) throws JMSException;
Sets the destination for this message.
Any value set using this method is ignored when the message is sent, but this method can be used to change the value in a received message.
public void setJMSExpiration(long expiration) throws JMSException;
Sets the message's expiration value.
Any value set using this method is ignored when the message is sent, but this method can be used to change the value in a received message.
public void setJMSMessageID(String id) throws JMSException;
Sets the message ID.
Any value set using this method is ignored when the message is sent, but this method can be used to change the value in a received message.
public void setJMSPriority(int priority) throws JMSException;
Sets the priority for this message.
Providers set this field when a message is sent. This operation can be used to change the value of a message that has been received.
JMS defines a ten levels of priority with 0 as the lowest and 9 as the highest. In addition, clients must consider priorities 0-4 as gradations of normal priority, and priorities 5-9 as gradations of expedited priority.
public void setJMSRedelivered(boolean redelivered) throws JMSException;
Sets a boolean to indicate whether this message is being re-delivered.
This field is set at the time the message is delivered. This operation can be used to change the value of a message that has been received.
public void setJMSReplyTo(Destination replyTo) throws JMSException;
Sets the destination to which a reply to this message can be sent.
The replyTo header field contains the destination where a reply to the current message can be sent. If it is null, no reply is expected. The destination can be either a Queue or a Topic.
Messages with a null replyTo value are called JMS datagrams. Datagrams might contain a notification of some change in the sender (i.e. they signal a sender event) or they might just contain some data the sender thinks is of interest.
Messages with a replyTo value are typically expecting a response. A response is optional: it is up to the client to decide. These messages are called JMS requests. A message sent in response to a request is called a reply.
In some cases a client might wish to match a request it sent earlier with a reply it has just received. This can be done using the correlationID.
public void setJMSTimestamp(long timestamp) throws JMSException;
Sets the message timestamp.
Providers set this field when a message is sent. This operation can be used to change the value of a message that has been received.
public void setJMSType(String type) throws JMSException;
Sets the message type.
Some JMS providers use a message repository that contains the definition of messages sent by applications. The type header field contains the name of a message's definition.
JMS does not define a standard message definition repository nor does it define a naming policy for the definitions it contains. JMS clients should use symbolic values for types that can be configured at installation time which correspond to the values defined in the current provider's message repository.
JMS clients should assign a value whether the application makes use of it or not. This insures that it is properly set for those providers that require it.
public void setLongProperty(String name, long value) throws JMSException;
Sets a long property value with the given name in the message.
public void setObjectProperty(String name, Object value) throws JMSException;
Sets a Java object property value with the given name into the message.
This method only works for the 'objectified' primitive object types (Integer, Double, Long...) and for Strings.
public void setShortProperty(String name, short value) throws JMSException;
Sets a short property value with the given name in the message.
public void setStringProperty(String name, String value) throws JMSException;
Sets a String property value with the given name in the message.
public String toString();
Gets a String containing a formatted version of the Message header.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
csqzaw1384 |