Headers

Correlation ID refers to a related message. For example, when a consumer responds to a request message by sending a reply, it can set the correlation ID of the reply to indicate the request message.

The JMS specification allows three categories of values for the correlation ID property:

• Message ID 

  A message ID is a unique string that the provider assigns to a message. Programs can use these IDs to correlate messages. For example, a program can link a response to a request by setting the correlation ID of a response message to the message ID of the corresponding request message.

  Message ID strings begin with the prefix ID: (which is reserved for this purpose).

• String

  Programs can also correlate messages using arbitrary strings, with semantics determined by the application.

  These strings must not begin with the prefix ID: (which is reserved for message IDs).

• Byte Array

  This implementation does not support byte array values for the correlation ID property. The JMS specification does not require support.

tibemsMsg_GetCorrelationID

tibemsMsg_SetCorrelationID

A producer can specify that a message must not be delivered until after a specified time interval, which directs the server to delay delivery of the message.

For detailed information on delivery delay, see the TIBCO Enterprise Message Service User’s Guide.

Sending calls can set the delivery delay for each message based on a property of the producer. To set the producer property, see tibemsMsgProducer_SetDeliveryDelay.

tibemsMsg_GetDeliveryTime

Delivery Mode instructs the server concerning persistent storage for the message. For detailed information on delivery modes, see the TIBCO Enterprise Message Service User’s Guide.

Sending calls set the delivery mode for each message, based on either a property of the producer, or on a parameter to the sending call. To set the producer property, see tibemsMsgProducer_SetDeliveryMode.

tibemsMsg_GetDeliveryMode

tibemsMsg_SetDeliveryMode

For values, see tibemsDeliveryMode.

Sending calls set the destination (queue or topic) of the message in this header and will overwrite any existing value. The value is based on either a property of the producer, or on a parameter to the send call.

Listeners that consume messages from wildcard destinations can use this property to determine the actual destination of a message.

tibemsMsg_GetDestination

tibemsMsg_SetDestination

Sending calls set the expiration time (in milliseconds) of the message in this field:

• If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT).
• If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.

  The server discards a message when its expiration time has passed. However, the JMS specification does not guarantee that clients do not receive expired messages.

tibemsMsg_GetExpiration

tibemsMsg_SetExpiration

Sending calls assign a unique ID to each message, and record it in this header.

All message ID values start with the 3-character prefix ID: (which is reserved for this purpose).

Applications that do not require message IDs can reduce overhead costs by disabling IDs; see tibemsMsgProducer_SetDisableMessageID. When the producer disables IDs, the value of this header is null.

tibemsMsg_GetMessageID

tibemsMsg_SetMessageID

Sending calls set the priority of a message in this header, based on either a property of the producer (tibemsMsgProducer_SetPriority), or on a parameter to the send call.

The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.

Priority affects the order in which the server delivers messages to consumers (higher values first). The JMS specification does not require all providers to implement priority ordering of messages. (EMS supports priorities, but other JMS providers might not.)

tibemsMsg_GetPriority

tibemsMsg_SetPriority

The server sets this header to indicate whether a message might duplicate a previously delivered message:

• false—The server has not previously attempted to deliver this message to the consumer.
• true—It is likely (but not guaranteed) that the server has previously attempted to deliver this message to the consumer, but the consumer did not return timely acknowledgment.

tibemsMsg_GetRedelivered

tibemsMsg_SetRedelivered

See also, tibemsAcknowledgeMode

Sending clients can set this header to request that recipients reply to the message:

• When the value is a destination object, recipients can send replies to that destination. Such a message is called a request.
• When the value is null, the sender does not expect a reply.

When sending a reply, clients can refer to the corresponding request by setting the Correlation ID.

tibemsMsg_GetReplyTo

tibemsMsg_SetReplyTo

Sending calls record a UTC timestamp in this header, indicating the approximate time that the server accepted the message.

The value is in milliseconds since January 1, 1970 (as in Java).

Applications that do not require timestamps can reduce overhead costs by disabling timestamps; see tibemsMsgProducer_SetDisableMessageTimestamp. When the producer disables timestamps, the value of this header is zero.

tibemsMsg_GetTimestamp

tibemsMsg_SetTimestamp

Some JMS providers use a message repository to store message type definitions. Client programs can store a value in this field to reference a definition in the repository. EMS support this header, but does not use it.

The JMS specification does not define a standard message definition repository, nor does it define a naming policy for message type definitions.

Some providers require message type definitions for each application message. To ensure compatibility with such providers, client programs can set this header, even if the client application does not use it.

To ensure portability, clients can set this header with symbolic values (rather than literals), and configure them to match the provider’s repository.

tibemsMsg_GetType

tibemsMsg_SetType