ionic.Msmq
Class Message

java.lang.Object
  extended by ionic.Msmq.Message

public class Message
extends java.lang.Object

The Message class models a message that is sent to or receive from an MSMQ queue. It exposes several properties that are known to MSMQ, including the message label, the message correlationId, and the message body.

The maximum size for an MSMQ 4.0 message is slightly less than 4 MB. If you try to send a message that exceeds the maximum size, you will receive a MessageQueueException, with hr = MQ_ERROR_INSUFFICIENT_RESOURCES (0xC00E0027).


Constructor Summary
Message(byte[] body)
          Creates a Message instance, using a byte array for the message body, and empty values for the label and correlation ID.
Message(byte[] body, java.lang.String label, byte[] correlationId)
          Creates a Message instance, using a byte array for the body the correlation ID, and a string for the label.
Message(byte[] body, java.lang.String label, java.lang.String correlationId)
          Creates a Message instance, using a byte array for the body, and a string for the label and correlation ID.
Message(java.lang.String body)
          Creates a Message instance, using a string argument for the contents of the body, and empty values for the label and correlation ID.
Message(java.lang.String body, java.lang.String label, byte[] correlationId)
          Creates a Message instance, using a string for the body and label, and a byte array for the correlation ID.
Message(java.lang.String body, java.lang.String label, java.lang.String correlationId)
          Creates a Message instance, using string arguments for the contents.
 
Method Summary
 byte[] getBody()
          Gets the message body.
 java.lang.String getBodyAsString()
          Gets the message body, as a string.
 byte[] getCorrelationId()
          Gets the correlation Id on the message.
 java.lang.String getCorrelationIdAsString()
          Gets the correlation Id on the message, in the form of a string.
 boolean getHighPriority()
          Gets whether the message will be treated with high priority.
 java.lang.String getLabel()
          Gets the message body.
 void setBody(byte[] value)
          Sets the message body.
 void setBodyAsString(java.lang.String value)
          Sets the message body, as a string.
 void setCorrelationId(byte[] value)
          Sets the correlation Id on the message.
 void setCorrelationIdAsString(java.lang.String value)
          Sets the correlation Id on the message.
 void setHighPriority(boolean value)
          Sets whether the message should be trated as high priority or not.
 void setLabel(java.lang.String value)
          Sets the message label.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Message

public Message(java.lang.String body)
        throws java.io.UnsupportedEncodingException

Creates a Message instance, using a string argument for the contents of the body, and empty values for the label and correlation ID.

Parameters:
body - the string to use for the Message body
Throws:
java.io.UnsupportedEncodingException

Message

public Message(java.lang.String body,
               java.lang.String label,
               java.lang.String correlationId)
        throws java.io.UnsupportedEncodingException

Creates a Message instance, using string arguments for the contents.

A Message contains byte array data in the body and correlation Id. This constructor allows the specification of those items as strings. The actual values of the body and correlation Id are set to the encoded form of the strings, using UTF-16LE for encoding.

If you use ASCII strings for the body and correlationId, the encoding will be very inefficient. Each character in the input will result in two bytes in output, one of which will be a zero. Therefore, if you're concerned about efficiency, consider encoding strings separately, before creating the Message instance.

Parameters:
body - the string to use for the Message body.
label - the string to use for the Message label. The maximum length of a message label is 250 bytes.
correlationId - the string to use for the Message correlation Id
Throws:
java.io.UnsupportedEncodingException

Message

public Message(java.lang.String body,
               java.lang.String label,
               byte[] correlationId)
        throws java.io.UnsupportedEncodingException

Creates a Message instance, using a string for the body and label, and a byte array for the correlation ID.

A Message contains byte array data in the body and correlation Id. This constructor allows the specification of the body as a string, and the correlation Id as a byte array. The actual value of the body will be set to the encoded form of the body string, using UTF-16LE.

Only the first 20 bytes of the correlationId will be used.

Parameters:
body - the string to use for the Message body
label - the string to use for the Message label
correlationId - the byte array to use for the Message correlation Id
Throws:
java.io.UnsupportedEncodingException

Message

public Message(byte[] body)
        throws java.io.UnsupportedEncodingException

Creates a Message instance, using a byte array for the message body, and empty values for the label and correlation ID.

A Message contains byte array data in the body and correlation Id. This constructor allows the specification of the body as a byte array. The label and correlation ID of the Message are set to empty values.

Parameters:
body - the string to use for the Message body
Throws:
java.io.UnsupportedEncodingException

Message

public Message(byte[] body,
               java.lang.String label,
               java.lang.String correlationId)
        throws java.io.UnsupportedEncodingException

Creates a Message instance, using a byte array for the body, and a string for the label and correlation ID.

A Message contains byte array data in the body and correlation Id. This constructor allows the specification of the body as a byte array, and the correlation Id as a string. The actual value of the correlation Id will be the encoded form of the body string, using UTF-16LE.

Only the first 20 bytes of the correlationId will be used.

Parameters:
body - the string to use for the Message body
label - the string to use for the Message label
correlationId - the byte array to use for the Message correlation Id
Throws:
java.io.UnsupportedEncodingException

Message

public Message(byte[] body,
               java.lang.String label,
               byte[] correlationId)

Creates a Message instance, using a byte array for the body the correlation ID, and a string for the label.

A Message contains byte array data in the body and correlation Id. This constructor allows the specification of the body and correlation ID as byte arrays. Applications may wish to use this constructor when close control of the contents of the message is desired.

Only the first 20 bytes of the correlationId will be used.

Parameters:
body - the string to use for the Message body
label - the string to use for the Message label
correlationId - the byte array to use for the Message correlation Id
Method Detail

setBodyAsString

public void setBodyAsString(java.lang.String value)
                     throws java.io.UnsupportedEncodingException

Sets the message body, as a string.

The string will be encoded as UTF-16LE, with no byte-order-mark. This information may be useful if you use different libraries on the the receiving and sending side.

Parameters:
value - the string to use for the Message body
Throws:
java.io.UnsupportedEncodingException
See Also:
setBody(byte[])

getBodyAsString

public java.lang.String getBodyAsString()
                                 throws java.io.UnsupportedEncodingException

Gets the message body, as a string.

The string will be decoded as UTF-16LE, with no byte-order-mark. This is mostly useful after receiving a message.

If the message body is not a legal UTF-16LE bytestream, then this method will return a rubbish string.

Returns:
the message body, as a string.
Throws:
java.io.UnsupportedEncodingException
See Also:
getBody()

setCorrelationIdAsString

public void setCorrelationIdAsString(java.lang.String value)
                              throws java.io.UnsupportedEncodingException

Sets the correlation Id on the message.

MSMQ specifies that the ID should be a byte array, of 20 bytes in length. But callers can use this convenience method to use a string as a correlationId. It will be encoded as UTF-8, and limited to 20 bytes.

Parameters:
value - the string to use as the correlation ID on the message.
Throws:
java.io.UnsupportedEncodingException

getCorrelationIdAsString

public java.lang.String getCorrelationIdAsString()
                                          throws java.io.UnsupportedEncodingException

Gets the correlation Id on the message, in the form of a string.

The behavior is undefined if the correlation ID is not a UTF-8 bytestream.

Returns:
the correlation ID on the message, as a string.
Throws:
java.io.UnsupportedEncodingException

setBody

public void setBody(byte[] value)
Sets the message body.

Parameters:
value - the byte array to use for the Message body
See Also:
getBody(), setBodyAsString(String)

getBody

public byte[] getBody()
Gets the message body.

Returns:
the message body, as a byte array.

setLabel

public void setLabel(java.lang.String value)
Sets the message label.

Parameters:
value - the string to use as the label on the message.

getLabel

public java.lang.String getLabel()
Gets the message body.

Returns:
the message label.

setCorrelationId

public void setCorrelationId(byte[] value)

Sets the correlation Id on the message.

The ID should be a byte array, a maximum of 20 bytes.

Parameters:
value - the byte array to use as the correlation ID on the message.

getCorrelationId

public byte[] getCorrelationId()

Gets the correlation Id on the message.

The ID will be a byte array, of length 20.

Returns:
the correlation ID on the message.

setHighPriority

public void setHighPriority(boolean value)
Sets whether the message should be trated as high priority or not.

Parameters:
value - true if the message should be delivered with high priority.

getHighPriority

public boolean getHighPriority()

Gets whether the message will be treated with high priority.

This only makes sense for outgoing messages.

Returns:
true if the message will be trated with high priority.