JMS Connect User's Guide
APPENDIX C
In JMS, all messages support the same set of predefined header fields, which are described below. Note that most header fields will have their values set automatically at runtime either by exteNd Composer or the MOM vendor.
A JMS client can use the JMSCorrelationID header to associated one message with another (for request/response situations). This field can hold an arbitrary string value, obtained by mapping a node value from an Input DOM, or perhaps created dynamically with the aid of ECMAScript, etc. Use of this field is not mandatory.
This header field contains the delivery mode (PERSISTENT or NON_PERSISTENT) specified when the message was sent. At the start of a send session, this header field is ignored; after the send has been accomplished, it holds the delivery mode specified by the sending method.
This field will be filled out for you, using the persistency value you chose in the Send Message setup wizard. (See next chapter.)
The JMSDestination header field is ignored at the time a message is sent; after the send, it contains the destination object specified by the sending message.
You do not need to enter anything manually in this field, since the necessary connection information (i.e., choice of destination queue) was automatically set when you first created the JMS Component.
You will not need to enter anything manually into this field. The Send Message setup wizard will prompt you for (among other things) a Time-to-Live for the outgoing message. During the "send" session, when the message is actually ready to be sent, exteNd will calculate the message's expiration time as the sum of the Time-to-Live value and the current UTC time (both values in milliseconds). After the send is completed, the message's JMSExpiration header field will contain this sum. If the Time-to-Live value was zero when the Send Message action was created, the message will have no expiration value (which means it will not expire).
NOTE: In most JMS-based MOMs, clients never receive expired messages.
The JMSMessageID value uniquely identifies a message in the MOM environment. It is set automatically by the JMS provider and is read-only (and only after a message has been sent).
The JMSPriority field holds a string value containing one of ten values (`0' through `9') reflecting the message's priority. This field value is filled out automatically with the value you supplied in the Send Message setup wizard. A value of `0' to `4' indicates a range of normal priorities (with `4' being the default); `5' to `9' are gradations of expedited priority.
NOTE: The manner by which priority settings determine message ordering in a queue is not defined by JMS. Consult your MOM vendor's documentation for information about how this feature might affect message ordering.
If a client application receives a message that has the JMSRedelivered marker set, it is possible that the queue manager tried to deliver the message earlier, but the message was not acknowledged by the client (perhaps due to a system failure). This field is under the control of the queue manager or message broker. It is not under application control.
The JMSReplyTo field is designed to contain a Destination supplied by a client when a message is sent. It represents the destination where a reply to the message (if any) should be sent.
NOTE: This header field is not currently exposed as a write-enabled item in exteNd Composer's JMS Component Editor.
This field contains the time that a message was handed off to a provider to be sent. It may or may not be the actual transmission time, depending on whether (for instance) the message's "send" session is under transactional control.
This user-settable field contains an arbitrary string supplied by a client when a message is created. The sender can assign any value to JMSType that a receiver might find useful. For example, application-defined JMSType values could facilitate message filtering by making it possible for various receivers to handle various specific message types.
NOTE: Some JMS providers store message type definitions in a repository and may expect runtime values in JMSType that correspond to these type definitions. If this is the case with your MOM environment, use symbolic values for JMSType that correspond to legal values defined in the applicable repository. (Consult your MOM documentation for details.)
Message properties serve, in effect, as extra header fields. JMS allows for three broad categories of properties: JMS-defined properties, provider-specific properties, and user-defined properties. JMS Connect supports all three categories, although JMS does not require applications to support properties (other than JMSXGroupID and JMSXGroupSeq; see below).
Property values (if not null) must be of type boolean, byte, short, int, long, float, double, or String. The allowable values for specific predefined properties are described further below.
Property values, if present, are set by the sender prior to sending a message. When a message is received by a client, all properties are read-only. Any attempt by the client to set a property value on a retrieved message will result in a MessageNotWriteableException being thrown.
JMS defines (and the JMS Connect exposes) a number of JMS-specific property fields that can optionally be populated by message clients and/or providers. These JMS-defined properties, which are prefixed with `JMSX', include:
JMSXUserID (String) — Arbitrary string identifying the user who is sending the message. (This is intended to be set by the provider during a send operation.)
JMSXAppID (String) — Identity of the sending application. (This is intended to be set by the provider during a send operation.)
JMSXDeliveryCount (int) — The number of message delivery attempts. (Set by provider.)
JMSXGroupID (String) — The (client-settable) identity of the message group that this message is a member of. Intended for use by clients who are sending messages in batches.
JMSXGroupSeq (int) — The (client-settable) sequence number of this message within a group.
JMSXProducerTXID (String) — Identifier of the transaction within which this message was produced (set by the provider).
JMSXConsumerTXID (String) — Identifier of the transaction within which this message was consumed (set by the provider).
JMSXRcvTimestamp (long) — The time when a message was delivered to its ultimate consumer (set by provider).
JMSXState (int) — One of 1 (waiting), 2 (ready), 3 (expired), 4 (retained). Not relevant to the client app; for internal use of the provider.
JMS allows providers to define their own public property names, with a prefix of "JMS_<vendor name>" (e.g., JMS_IBM is the prefix for IBM-defined properties). Although the JMS Connect exposes these fields in JMS message header tree views, they are really intended for the JMS provider's use.
When IBM's MQSeries is the provider, exteNd's JMS Connect exposes three vendor-specific properties: JMS_IBM_MsgType, JMS_IBM_PutApplType, and JMS_IBM_Format. After a message has been received by a JMS Component, these fields will typically be populated with MQSeries-specific control information. On outgoing messages, you can either supply appropriate values in these fields yourself, or leave them blank. See the MQSeries Application Programming Reference for information on the semantics of these fields.
JMS allows users to define their own custom properties, and the JMS Connect exposes this functionality in the JMS Component Editor as described further below. There is no restriction on the number or kinds of user-defined property fields that can be attached to a message, except that the names of user-defined properties must (like all headers and properties) obey the syntax rules for message selector identifiers.
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...