org.apache.qpid.jms.message.facade

Interface JmsMessageFacade

All Superinterfaces:

TraceableMessage

All Known Subinterfaces:

JmsBytesMessageFacade, JmsMapMessageFacade, JmsObjectMessageFacade, JmsStreamMessageFacade, JmsTextMessageFacade

All Known Implementing Classes:

AmqpJmsBytesMessageFacade, AmqpJmsMapMessageFacade, AmqpJmsMessageFacade, AmqpJmsObjectMessageFacade, AmqpJmsStreamMessageFacade, AmqpJmsTextMessageFacade

public interface JmsMessageFacade
extends TraceableMessage

The Message Facade interface defines the required mapping between a Provider's own Message type and the JMS Message types. A Provider can implement the Facade interface and offer direct access to its message types without the need to copy to / from a more generic JMS message instance.

Method Summary

Modifier and Type	Method and Description
void	clearBody() Clears the contents of this Message.
void	clearProperties() Clears any Message properties that exist for this Message instance.
JmsMessageFacade	copy() Create a new instance and perform a deep copy of this object's contents.
Object	encodeMessage() Encodes the protocol level Message instance for transmission.
String	getCorrelationId() Returns the correlation ID set on this message if one exists, null otherwise.
byte[]	getCorrelationIdBytes() Gets the set correlation ID of the message in raw bytes form.
int	getDeliveryCount() Returns the current delivery count of the Message as set in the underlying message instance.
long	getDeliveryTime() Returns the set delivery time for this message.
JmsDestination	getDestination() Gets the Destination value that was assigned to this message at the time it was sent.
long	getExpiration() Returns the set expiration time for this message.
String	getGroupId() Gets the Group ID that this message is assigned to.
int	getGroupSequence() Gets the assigned group sequence of this message.
String	getMessageId() Returns the message ID set on this message if one exists, null otherwise.
int	getPriority() Returns the assigned priority value of this message in JMS ranged scoping.
Object	getProperty(String key) Returns the property stored in the message accessed via the given key/
Set<String>	getPropertyNames() Returns the property names for this Message instance.
Object	getProviderMessageIdObject() Returns the underlying providers message ID object for this message if one exists, null otherwise.
int	getRedeliveryCount() Returns the current redelivery count of the Message as set in the underlying message instance.
JmsDestination	getReplyTo() Gets the Destination where replies for this Message are to be sent to.
long	getTimestamp() Gets the time stamp assigned to the message when it was sent.
String	getType() Returns the JMSType value as defined by the provider or set by the sending client.
String	getUserId() Returns the ID of the user that sent this message if available.
byte[]	getUserIdBytes() Gets the set user ID of the message in raw bytes form.
boolean	hasBody() Returns true if the underlying message has a body, false if the body is empty.
boolean	isDeliveryTimeTransmitted() Returns whether the delivery time is being transmitted, i.e.
boolean	isPersistent()
boolean	isRedelivered() Used to quickly check if a message has been redelivered.
void	onDispatch() Called before a message is dispatched to its intended consumer to allow for any necessary processing of message data such as setting read-only state etc.
void	onSend(long producerTtl) Called before a message is sent to allow a Message instance to move the contents from a logical data structure to a binary form for transmission, or other processing such as setting proper message headers etc.
boolean	propertyExists(String key)
void	setCorrelationId(String correlationId) Sets the correlation ID for this message.
void	setCorrelationIdBytes(byte[] correlationId) Sets the correlation ID of the message in raw byte form.
void	setDeliveryCount(int deliveryCount) Sets the delivery count on the message.
void	setDeliveryTime(long deliveryTime, boolean transmit) Sets an desired delivery time on this message.
void	setDestination(JmsDestination destination) Sets the Destination that this message is being sent to.
void	setExpiration(long expiration) Sets an expiration time on this message.
void	setGroupId(String groupId) Sets the Group ID to use for this message.
void	setGroupSequence(int groupSequence) Sets the group sequence value for this message.
void	setMessageId(String messageId) Sets the message ID for this message.
void	setPersistent(boolean value) Sets the persistent flag on this message.
void	setPriority(int priority) Sets the message priority for this message using a JMS priority scoped value.
void	setProperty(String key, Object value) Sets the message property value using the supplied key to identify the value that should be set or updated.
void	setProviderMessageIdObject(Object messageId) Sets the underlying providers message ID object for this message, or clears it if the provided value is null.
void	setRedelivered(boolean redelivered) Used to set the redelivered state of a message.
void	setRedeliveryCount(int redeliveryCount) Used to update the message redelivery after a local redelivery of the Message has been performed.
void	setReplyTo(JmsDestination replyTo) Sets the Destination where replies to this Message are to be sent.
void	setTimestamp(long timestamp) Sets the time stamp value of this message.
void	setType(String type) Sets the String value used to define the Message JMSType by the client.
void	setUserId(String userId) Sets the User ID for the connection that is being used to send this message.
void	setUserIdBytes(byte[] userId) Sets the user ID of the message in raw byte form.

Methods inherited from interface org.apache.qpid.jms.tracing.TraceableMessage

filterTracingAnnotations, getTracingAnnotation, getTracingContext, removeTracingAnnotation, removeTracingContext, setTracingAnnotation, setTracingContext

Method Detail

getPropertyNames

Set<String> getPropertyNames()
                      throws javax.jms.JMSException

Returns the property names for this Message instance. The Set returned may be manipulated by the receiver without impacting the facade, and an empty set will be returned if there are no matching properties.

Returns:

a set containing the property names of this Message

Throws:

javax.jms.JMSException - if an error occurs while accessing the Message properties.

propertyExists

boolean propertyExists(String key)
                throws javax.jms.JMSException

Parameters:

key - The property name that is being searched for.

Returns:

true if the given property exists within the message.

Throws:

javax.jms.JMSException - if an error occurs while accessing the Message properties.

getProperty

Object getProperty(String key)
            throws javax.jms.JMSException

Returns the property stored in the message accessed via the given key/

Parameters:

key - the key used to access the given property.

Returns:

the object that is stored under the given key or null if none found.

Throws:

javax.jms.JMSException - if an error occurs while accessing the Message properties.

setProperty

void setProperty(String key,
                 Object value)
          throws javax.jms.JMSException

Sets the message property value using the supplied key to identify the value that should be set or updated.

Parameters:

key - the key that identifies the message property.

value - the value that is to be stored in the message.

Throws:

javax.jms.JMSException - if an error occurs while accessing the Message properties.

onSend

void onSend(long producerTtl)
     throws javax.jms.JMSException

Called before a message is sent to allow a Message instance to move the contents from a logical data structure to a binary form for transmission, or other processing such as setting proper message headers etc. The method allows for passing through producer configuration details not explicitly mapped into the JMS Message allowing the facade to create the most correct and compact message on the wire.

Parameters:

producerTtl - the time to live value configured on the producer when sent.

Throws:

javax.jms.JMSException - if an error occurs while preparing the message for send.

onDispatch

void onDispatch()
         throws javax.jms.JMSException

Called before a message is dispatched to its intended consumer to allow for any necessary processing of message data such as setting read-only state etc.

Throws:

javax.jms.JMSException - if an error occurs while preparing the message for dispatch.

clearBody

void clearBody()

Clears the contents of this Message.

clearProperties

void clearProperties()
              throws javax.jms.JMSException

Clears any Message properties that exist for this Message instance.

Throws:

javax.jms.JMSException - if an error occurs while accessing the message properties.

copy

JmsMessageFacade copy()
               throws javax.jms.JMSException

Create a new instance and perform a deep copy of this object's contents.

Returns:

a copy of this JmsMessageFacade instance.

Throws:

javax.jms.JMSException - if an error occurs while copying the message.

getTimestamp

long getTimestamp()

Gets the time stamp assigned to the message when it was sent.

Returns:

the message time stamp value.

setTimestamp

void setTimestamp(long timestamp)

Sets the time stamp value of this message.

Parameters:

timestamp - the time that the message was sent by the provider.

getCorrelationId

String getCorrelationId()

Returns the correlation ID set on this message if one exists, null otherwise. The returned value will include the JMS mandated 'ID:' prefix if the value represents a JMSMessageID rather than an application-specific string.

Returns:

the set correlation ID or null if not set.

setCorrelationId

void setCorrelationId(String correlationId)
               throws javax.jms.JMSException

Sets the correlation ID for this message.

Parameters:

correlationId - The correlation ID to set on this message, or null to clear.

Throws:

javax.jms.JMSException - if an error occurs while setting the correlation ID.

getCorrelationIdBytes

byte[] getCorrelationIdBytes()
                      throws javax.jms.JMSException

Gets the set correlation ID of the message in raw bytes form. If no ID was set then this method may return null or an empty byte array.

Returns:

a byte array containing the correlation ID value in raw form.

Throws:

javax.jms.JMSException - if an error occurs while accessing the property.

setCorrelationIdBytes

void setCorrelationIdBytes(byte[] correlationId)

Sets the correlation ID of the message in raw byte form. Setting the value as null or an empty byte array will clear any previously set value. If the underlying protocol cannot convert or map the given byte value to it's own internal representation it should throw a JMSException indicating the error.

Parameters:

correlationId - the byte array to use to set the message correlation ID.

getMessageId

String getMessageId()

Returns the message ID set on this message if one exists, null otherwise. The returned value will include the JMS mandated 'ID:' prefix.

Returns:

the set message ID or null if not set.

setMessageId

void setMessageId(String messageId)
           throws javax.jms.JMSException

Sets the message ID for this message.

Parameters:

messageId - The message ID to set on this message, or null to clear.

Throws:

javax.jms.JMSException - if an error occurs while setting the message ID.

isPersistent

boolean isPersistent()

Returns:

true if this message is tagged as being persistent.

setPersistent

void setPersistent(boolean value)

Sets the persistent flag on this message.

Parameters:

value - true if the message is to be marked as persistent.

getDeliveryCount

int getDeliveryCount()

Returns the current delivery count of the Message as set in the underlying message instance.

Returns:

the current delivery count.

setDeliveryCount

void setDeliveryCount(int deliveryCount)

Sets the delivery count on the message.

Parameters:

deliveryCount - the new delivery count to assign the Message.

getRedeliveryCount

int getRedeliveryCount()

Returns the current redelivery count of the Message as set in the underlying message instance.

Returns:

the current redelivery count.

setRedeliveryCount

void setRedeliveryCount(int redeliveryCount)

Used to update the message redelivery after a local redelivery of the Message has been performed.

Parameters:

redeliveryCount - the new redelivery count to assign the Message.

isRedelivered

boolean isRedelivered()

Used to quickly check if a message has been redelivered.

Returns:

true if the message was redelivered, false otherwise.

setRedelivered

void setRedelivered(boolean redelivered)

Used to set the redelivered state of a message. This can serve to clear the redelivery counter or set its initial value to one.

Parameters:

redelivered - true if the message is to be marked as redelivered, false otherwise.

getType

String getType()

Returns the JMSType value as defined by the provider or set by the sending client.

Returns:

a String value that defines the message JMSType.

setType

void setType(String type)

Sets the String value used to define the Message JMSType by the client.

Parameters:

type - the JMSType value the client assigns to this message.

getPriority

int getPriority()

Returns the assigned priority value of this message in JMS ranged scoping. If the provider does not define a message priority value in its message objects or the value is not set in the message this method should return the JMS default value of 4.

Returns:

the priority value assigned to this message.

setPriority

void setPriority(int priority)

Sets the message priority for this message using a JMS priority scoped value.

Parameters:

priority - the new priority value to set on this message.

getExpiration

long getExpiration()

Returns the set expiration time for this message. The value should be returned as an absolute time given in GMT time.

Returns:

the time that this message expires or zero if it never expires.

setExpiration

void setExpiration(long expiration)

Sets an expiration time on this message. The expiration time will be given as an absolute time in GMT time.

Parameters:

expiration - the time that this message should be considered as expired.

getDeliveryTime

long getDeliveryTime()

Returns the set delivery time for this message. The value should be returned as an absolute time given in GMT time.

Returns:

the earliest time that the message should be made available for delivery.

setDeliveryTime

void setDeliveryTime(long deliveryTime,
                     boolean transmit)

Sets an desired delivery time on this message. The delivery time will be given as an absolute time in GMT time.

Parameters:

deliveryTime - the earliest time that the message should be made available for delivery.

transmit - whether to transmit an annotation containing the value (if non-zero)

getDestination

JmsDestination getDestination()

Gets the Destination value that was assigned to this message at the time it was sent.

Returns:

the destination to which this message was originally sent.

setDestination

void setDestination(JmsDestination destination)

Sets the Destination that this message is being sent to.

Parameters:

destination - the destination that this message is being sent to.

getReplyTo

JmsDestination getReplyTo()

Gets the Destination where replies for this Message are to be sent to.

Returns:

the reply to destination for this message or null if none set.

setReplyTo

void setReplyTo(JmsDestination replyTo)

Sets the Destination where replies to this Message are to be sent.

Parameters:

replyTo - the Destination where replies should be sent, or null to clear.

getUserId

String getUserId()

Returns the ID of the user that sent this message if available.

Returns:

the user ID that was in use when this message was sent or null if not set.

setUserId

void setUserId(String userId)

Sets the User ID for the connection that is being used to send this message.

Parameters:

userId - the user ID that sent this message or null to clear.

getUserIdBytes

byte[] getUserIdBytes()
               throws javax.jms.JMSException

Gets the set user ID of the message in raw bytes form. If no ID was set then this method may return null or an empty byte array.

Returns:

a byte array containing the user ID value in raw form.

Throws:

javax.jms.JMSException - if an error occurs while accessing the property.

setUserIdBytes

void setUserIdBytes(byte[] userId)

Sets the user ID of the message in raw byte form. Setting the value as null or an empty byte array will clear any previously set value. If the underlying protocol cannot convert or map the given byte value to it's own internal representation it should throw a JMSException indicating the error.

Parameters:

userId - the byte array to use to set the message user ID.

getGroupId

String getGroupId()

Gets the Group ID that this message is assigned to.

Returns:

the Group ID this message was sent in.

setGroupId

void setGroupId(String groupId)

Sets the Group ID to use for this message.

Parameters:

groupId - the Group ID that this message is assigned to.

getGroupSequence

int getGroupSequence()

Gets the assigned group sequence of this message.

Returns:

the assigned group sequence of this message.

setGroupSequence

void setGroupSequence(int groupSequence)

Sets the group sequence value for this message.

Parameters:

groupSequence - the group sequence value to assign this message.

getProviderMessageIdObject

Object getProviderMessageIdObject()

Returns the underlying providers message ID object for this message if one exists, null otherwise. In the case the returned value is a String, it is not defined whether the JMS mandated 'ID:' prefix will be present.

Returns:

the set provider message ID or null if not set.

setProviderMessageIdObject

void setProviderMessageIdObject(Object messageId)

Sets the underlying providers message ID object for this message, or clears it if the provided value is null.

Parameters:

messageId - The message ID to set on this message, or null to clear.

hasBody

boolean hasBody()

Returns true if the underlying message has a body, false if the body is empty.

Returns:

true if the underlying message has a body, false if the body is empty.

encodeMessage

Object encodeMessage()

Encodes the protocol level Message instance for transmission.

Returns:

an Object that represents the encoded form of the message for the target provider.

isDeliveryTimeTransmitted

boolean isDeliveryTimeTransmitted()

Returns whether the delivery time is being transmitted, i.e. incorporates an actual delivery delay.

Returns:

true if delivery time is being transmitted as an annotation