org.huihoo.jfox.ms.jms.message
Class MessageHeader

java.lang.Object
  org.huihoo.jfox.ms.jms.message.MessageHeader

public class MessageHeader

extends java.lang.Object

This class implements message header fields for messages.

Version:

Revision: 1.1 Date: 2002-11-10 20:02:32

Author:

Peter.Cheng

Constructor Summary

MessageHeader()
Default Constructor without param

Method Summary

java.lang.String	getJMSCorrelationID() Gets the correlation ID for the message.
byte[]	getJMSCorrelationIDAsBytes() Gets the correlation ID as an array of bytes for the message.
int	getJMSDeliveryMode() Get the currently stored delivery mode.
javax.jms.Destination	getJMSDestination() The destination field contains the destination to which the message is being sent.
long	getJMSExpiration() Gets the message's expiration value.
java.lang.String	getJMSMessageID() Gets the message ID.
int	getJMSPriority() Gets the message defaultPriority level.
boolean	getJMSRedelivered() Gets an indication of whether this message is being redelivered.
javax.jms.Destination	getJMSReplyTo() Gets the Destination object to which a reply to this message should be sent.
long	getJMSTimestamp() Gets the message timestamp.
java.lang.String	getJMSType() Gets the message type identifier supplied by the client when the message was sent.
void	setJMSCorrelationID(java.lang.String correlationID) Sets the correlation ID for the message.
void	setJMSCorrelationIDAsBytes(byte[] correlationID) Sets the correlation ID as an array of bytes for the message.
void	setJMSDeliveryMode(int deliveryMode) Store the delivery mode associated with this message.
void	setJMSDestination(javax.jms.Destination destination) Store the destination associated with this message.
void	setJMSExpiration(long expiration) Sets the message's expiration value.
void	setJMSMessageID(java.lang.String id) Sets the message ID.
void	setJMSPriority(int priority) Sets the defaultPriority level for this message.
void	setJMSRedelivered(boolean redelivered) Specifies whether this message is being redelivered.
void	setJMSReplyTo(javax.jms.Destination replyTo) Sets the Destination object to which a reply to this message should be sent.
void	setJMSTimestamp(long timestamp) Sets the message timestamp.
void	setJMSType(java.lang.String type) Sets the message type.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MessageHeader

public MessageHeader()

Default Constructor without param

Method Detail

setJMSDestination

public void setJMSDestination(javax.jms.Destination destination)
                       throws javax.jms.JMSException

Store the destination associated with this message.

Parameters:

destination - The destination value to store (null is not valid).

Throws:

javax.jms.JMSException - if an error occurs while storing the value.

See Also:

Message

getJMSDestination

public javax.jms.Destination getJMSDestination()
                                        throws javax.jms.JMSException

The destination field contains the destination to which the message is being sent.

Returns:

The destination which the message is being delivered to (after a send) or has been received from (after a receive).

Throws:

javax.jms.JMSException - an error occurred while retreiving the data.

setJMSDeliveryMode

public void setJMSDeliveryMode(int deliveryMode)
                        throws javax.jms.JMSException

Store the delivery mode associated with this message. This value determines the persistence of a message and is set by a client prior to sending a message. This implements the javax.jms.Message function.

Parameters:

deliveryMode - The defaultDeliveryMode to store.

Throws:

javax.jms.JMSException - if an error occurs while storing the value.

See Also:

DeliveryMode

getJMSDeliveryMode

public int getJMSDeliveryMode()
                       throws javax.jms.JMSException

Get the currently stored delivery mode.

Returns:

defaultDeliveryMode

Throws:

javax.jms.JMSException - if an error occurs while retrieve the value.

See Also:

DeliveryMode

setJMSMessageID

public void setJMSMessageID(java.lang.String id)
                     throws javax.jms.JMSException

Sets the message ID.

JMS providers set this field when a message is sent. This method can be used to change the value for a message that has been received.

Parameters:

id - the ID of the message

Throws:

javax.jms.JMSException - if the JMS provider fails to set the message ID due to some internal error.

See Also:

Message.getJMSMessageID()

getJMSMessageID

public java.lang.String getJMSMessageID()
                                 throws javax.jms.JMSException

Gets the message ID.

The JMSMessageID header field contains a value that uniquely identifies each message sent by a provider.

When a message is sent, JMSMessageID can be ignored. When the send or publish method returns, it contains a provider-assigned value.

A JMSMessageID is a String value that should function as a nique key for identifying messages in a historical repository.

All JMSMessageID values must start with the prefix 'ID:'. Uniqueness of message ID values across different providers is not required.

Returns:

the message ID

Throws:

javax.jms.JMSException - if the JMS provider fails to get the message ID due to some internal error.

See Also:

Message.setJMSMessageID(String), MessageProducer.setDisableMessageID(boolean)

setJMSTimestamp

public void setJMSTimestamp(long timestamp)
                     throws javax.jms.JMSException

Sets the message timestamp.

JMS providers set this field when a message is sent. This method can be used to change the value for a message that has been received.

Parameters:

timestamp - the timestamp for this message

Throws:

javax.jms.JMSException - if the JMS provider fails to set the timestamp due to some internal error.

See Also:

Message.getJMSTimestamp()

getJMSTimestamp

public long getJMSTimestamp()
                     throws javax.jms.JMSException

Gets the message timestamp.

The JMSTimestamp header field contains the time a message was handed off to a provider to be sent. It is not the time the message was actually transmitted, because the actual send may occur later due to transactions or other client-side queueing of messages.

Returns:

the message timestamp

Throws:

javax.jms.JMSException - if the JMS provider fails to get the timestamp due to some internal error.

See Also:

Message.setJMSTimestamp(long), MessageProducer.setDisableMessageTimestamp(boolean)

setJMSCorrelationID

public void setJMSCorrelationID(java.lang.String correlationID)
                         throws javax.jms.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:

• A provider-specific message ID
• An application-specific String
• A provider-native byte[] value

Since each message sent by a JMS provider is assigned a message ID value, it is convenient to link messages via message ID. 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 instance, an application may 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 may need to assign specific JMSCorrelationID values to match those expected by clients that do not use the JMS API. 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 non-portable.

Parameters:

correlationID - the message ID of a message being referred to

Throws:

javax.jms.JMSException - if the JMS provider fails to set the correlation ID due to some internal error.

See Also:

Message.getJMSCorrelationID(), Message.getJMSCorrelationIDAsBytes(), Message.setJMSCorrelationIDAsBytes(byte[])

getJMSCorrelationID

public java.lang.String getJMSCorrelationID()
                                     throws javax.jms.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 String values.

Returns:

the correlation ID of a message as a String

Throws:

javax.jms.JMSException - if the JMS provider fails to get the correlation ID due to some internal error.

See Also:

Message.setJMSCorrelationID(String), Message.getJMSCorrelationIDAsBytes(), Message.setJMSCorrelationIDAsBytes(byte[])

setJMSCorrelationIDAsBytes

public void setJMSCorrelationIDAsBytes(byte[] correlationID)
                                throws javax.jms.JMSException

Sets the correlation ID as an array of bytes for the message.

The array is copied before the method returns, so future modifications to the array will not alter this message header.

If a provider supports the native concept of correlation ID, a JMS client may need to assign specific JMSCorrelationID values to match those expected by native messaging clients. JMS providers without native correlation ID values are not required to support this method and its corresponding get method; their implementation may throw a java.lang.UnsupportedOperationException.

The use of a byte[] value for JMSCorrelationID is non-portable.

Parameters:

correlationID - the correlation ID value as an array of bytes

Throws:

javax.jms.JMSException - if the JMS provider fails to set the correlation ID due to some internal error.

See Also:

Message.setJMSCorrelationID(String), Message.getJMSCorrelationID(), Message.getJMSCorrelationIDAsBytes()

getJMSCorrelationIDAsBytes

public byte[] getJMSCorrelationIDAsBytes()
                                  throws javax.jms.JMSException

Gets the correlation ID as an array of bytes for the message.

The use of a byte[] value for JMSCorrelationID is non-portable.

Returns:

the correlation ID of a message as an array of bytes

Throws:

javax.jms.JMSException - if the JMS provider fails to get the correlation ID due to some internal error.

See Also:

Message.setJMSCorrelationID(String), Message.getJMSCorrelationID(), Message.setJMSCorrelationIDAsBytes(byte[])

setJMSReplyTo

public void setJMSReplyTo(javax.jms.Destination replyTo)
                   throws javax.jms.JMSException

Sets the Destination object to which a reply to this message should be sent.

The JMSReplyTo header field contains the destination where a reply to the current message should be sent. If it is null, no reply is expected. The destination may be either a Queue object or a Topic object.

Messages sent with a null JMSReplyTo value may be a notification of some event, or they may just be some data the sender thinks is of interest.

Messages with a JMSReplyTo value typically expect a response. A response is optional; it is up to the client to decide. These messages are called requests. A message sent in response to a request is called a reply.

In some cases a client may wish to match a request it sent earlier with a reply it has just received. The client can use the JMSCorrelationID header field for this purpose.

Parameters:

replyTo - Destination to which to send a response to this message

Throws:

javax.jms.JMSException - if the JMS provider fails to set the JMSReplyTo destination due to some internal error.

See Also:

Message.getJMSReplyTo()

getJMSReplyTo

public javax.jms.Destination getJMSReplyTo()
                                    throws javax.jms.JMSException

Gets the Destination object to which a reply to this message should be sent.

Returns:

Destination to which to send a response to this message

Throws:

javax.jms.JMSException - if the JMS provider fails to get the JMSReplyTo destination due to some internal error.

See Also:

Message.setJMSReplyTo(Destination)

setJMSRedelivered

public void setJMSRedelivered(boolean redelivered)
                       throws javax.jms.JMSException

Specifies whether this message is being redelivered.

This field is set at the time the message is delivered. This method can be used to change the value for a message that has been received.

Parameters:

redelivered - an indication of whether this message is being redelivered

Throws:

javax.jms.JMSException - if the JMS provider fails to set the redelivered state due to some internal error.

See Also:

Message.getJMSRedelivered()

getJMSRedelivered

public boolean getJMSRedelivered()
                          throws javax.jms.JMSException

Gets an indication of whether this message is being redelivered.

If a client receives a message with the JMSRedelivered field set, it is likely, but not guaranteed, that this message was delivered earlier but that its receipt was not acknowledged at that time.

Returns:

true if this message is being redelivered

Throws:

javax.jms.JMSException - if the JMS provider fails to get the redelivered state due to some internal error.

See Also:

Message.setJMSRedelivered(boolean)

getJMSType

public java.lang.String getJMSType()
                            throws javax.jms.JMSException

Gets the message type identifier supplied by the client when the message was sent.

Returns:

the message type

Throws:

javax.jms.JMSException - if the JMS provider fails to get the message type due to some internal error.

See Also:

Message.setJMSType(String)

setJMSType

public void setJMSType(java.lang.String type)
                throws javax.jms.JMSException

Sets the message type.

The JMS API does not define a standard message definition repository, nor does it define a naming policy for the definitions it contains.

Some messaging systems require that a message type definition for each application message be created and that each message specify its type. In order to work with such JMS providers, JMS clients should assign a value to JMSType, whether the application makes use of it or not. This ensures that the field is properly set for those providers that require it.

To ensure portability, JMS clients should use symbolic values for JMSType that can be configured at installation time to the values defined in the current provider's message repository. If string literals are used, they may not be valid type names for some JMS providers.

Parameters:

type - the message type

Throws:

javax.jms.JMSException - if the JMS provider fails to set the message type due to some internal error.

See Also:

Message.getJMSType()

setJMSExpiration

public void setJMSExpiration(long expiration)
                      throws javax.jms.JMSException

Sets the message's expiration value.

Parameters:

expiration - the message's expiration time

Throws:

javax.jms.JMSException - if the JMS provider fails to set the message expiration due to some internal error.

See Also:

Message

getJMSExpiration

public long getJMSExpiration()
                      throws javax.jms.JMSException

Gets the message's expiration value.

When a message is sent, the JMSExpiration header field is left unassigned. After completion of the send or publish method, it holds the expiration time of the message. This is the sum of the time-to-live value specified by the client and the GMT at the time of the send or publish.

If the time-to-live is specified as zero, JMSExpiration is set to zero to indicate that the message does not expire.

When a message's expiration time is reached, a provider should discard it. The JMS API does not define any form of notification of message expiration.

Clients should not receive messages that have expired; however, the JMS API does not guarantee that this will not happen.

Returns:

the time the message expires, which is the sum of the time-to-live value specified by the client and the GMT at the time of the send

Throws:

javax.jms.JMSException - if the JMS provider fails to get the message expiration due to some internal error.

See Also:

Message

setJMSPriority

public void setJMSPriority(int priority)
                    throws javax.jms.JMSException

Sets the defaultPriority level for this message.

Parameters:

priority - the defaultPriority of this message

Throws:

javax.jms.JMSException - if the JMS provider fails to set the message defaultPriority due to some internal error.

See Also:

Message

getJMSPriority

public int getJMSPriority()
                   throws javax.jms.JMSException

Gets the message defaultPriority level.

The JMS API defines ten levels of defaultPriority value, with 0 as the lowest defaultPriority and 9 as the highest. In addition, clients should consider priorities 0-4 as gradations of normal defaultPriority and priorities 5-9 as gradations of expedited defaultPriority.

Returns:

the default message defaultPriority

Throws:

javax.jms.JMSException - if the JMS provider fails to get the message defaultPriority due to some internal error.

See Also:

Message