XMLMessage (Solace Messaging API for Java v10.25.1)

All Known Subinterfaces:

BytesMessage, BytesXMLMessage, CacheEventMessage, EventMessage, MapMessage, Message, StreamMessage, StreamXMLMessage, TextMessage, TextXMLMessage, XMLContentMessage
```
@ProviderType
public interface XMLMessage
```
XMLMessage describes a message that is sent or received.
XMLMessage is a wrapper of a well-formed XML message content, and optionally a binary attachment.

Thread Safety
XMLMessage objects are not safe for use by multiple threads. For a discussion of multi-threading considerations when publishing messages, see XMLMessageProducer.

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`XMLMessage.MessageUserPropertyConstants` An interface contains the Solace-defined message user properties.
`static class`	`XMLMessage.Outcome` Represents the type for supported message settlement outcome

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`MSGDUMP_BRIEF` A flag to control output of `XMLMessage.dump(int)`; display only the length of the binary attachment, xml attachment, and user property maps.
`static int`	`MSGDUMP_FULL` A flag to control output of `XMLMessage.dump(int)`; display the entire message contents.

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`ackMessage()` Acknowledges the message.
`void`	`clearAttachment()` Deletes the attachment to the message.
`void`	`clearContent()` Clears the message content.
`String`	`dump()` Produces a human-readable dump of the message properties and its contents (can be quite large).
`String`	`dump(int flags)` Produces a human-readable dump of the message properties and its contents.
`String`	`getApplicationMessageId()` Gets the application message ID, a string for an application-specific message identifier.
`String`	`getApplicationMessageType()` Gets the application message type.
`String`	`getAppMessageID()` Deprecated. Renamed to `XMLMessage.getApplicationMessageId()`.
`String`	`getAppMessageType()` Deprecated. Renamed to `XMLMessage.getApplicationMessageType()`.
`ByteBuffer`	`getAttachmentByteBuffer()` Gets a `ByteBuffer` containing the message's binary attachment.
`int`	`getAttachmentContentLength()` Gets the length of the attachment.
`Long`	`getCacheRequestId()` Return the request ID set in the cache request.
`List<Long>`	`getConsumerIdList()` Gets a read-only list of consumer IDs set on this message.
`int`	`getContentLength()` The length of the message content.
`String`	`getCorrelationId()` Gets the correlation ID.
`Object`	`getCorrelationKey()` Gets the correlation key for the message.
`User_Cos`	`getCos()` Gets the Class of Service (CoS) value for this message.
`boolean`	`getDeliverToOne()` Deprecated.
`int`	`getDeliveryCount()` Get message delivery count.
`DeliveryMode`	`getDeliveryMode()` Gets the delivery mode of the message.
`Destination`	`getDestination()` Gets the destination this message was published to.
`String`	`getDestinationTopicSuffix()` Returns the string, without a leading delimiter, that is found after the session's default ReplyTo base topic in an incoming message.
`boolean`	`getDiscardIndication()` Returns `true` if one or more messages have been discarded prior to the current message, else `false`.
`long`	`getExpiration()` The UTC time (in milliseconds, from midnight, January 1, 1970 UTC) when the message is supposed to expire.
`String`	`getHTTPContentEncoding()` Gets the HTTP content encoding header value from interaction with an HTTP client.
`String`	`getHTTPContentType()` Gets the HTTP content type header value from interaction with an HTTP client.
`String`	`getMessageId()` Deprecated. Use `XMLMessage.ackMessage()` to acknowledge messages. The message ID is only to be used for the purpose of acknowledgements. No other meaning should be inferred from the value of the guaranteed message ID. Returns the message ID set by JCSMP during send or reception. The message ID is the String representation of a 64-bit unsigned integer value identifying the message. On the receiving side, if messages received do not have message ID set by the appliance, JCSMP automatically assigns one and guarantees its uniqueness for a particular `<subscriber; message type>`. Guaranteed messages delivered from the appliance have a appliance-assigned message ID. Messages sent or received over the `Direct` delivery mode are assigned a message ID by the API, but its value is not meaningful.
`long`	`getMessageIdLong()` Deprecated. Use `XMLMessage.ackMessage()` to acknowledge messages. The message ID is only to be used for the purpose of acknowledgements. No other meaning should be inferred from the value of the guaranteed message ID. Returns the message ID set by JCSMP during send or reception. For discussion of message ID assignment, see `XMLMessage.getMessageId()`.
`MessageType`	`getMessageType()` Deprecated. See `XMLMessage.getDeliveryMode()`. Gets the type of the message. Valid types are enumerated in `MessageType`: `MessageType.NON_PERSISTENT` `MessageType.PERSISTENT` `MessageType.DIRECT` (default)
`int`	`getPriority()` Returns priority value in the range of 0–255, or -1 if it is not set.
`SDTMap`	`getProperties()` Gets the user properties map.
`long`	`getReceiveTimestamp()` Gets the receive timestamp (in milliseconds, from midnight, January 1, 1970 UTC).
`boolean`	`getRedelivered()` Indicates if the message has been delivered by the appliance to the API before.
`ReplicationGroupMessageId`	`getReplicationGroupMessageId()` Get the Replication Group Message ID for the received message.
`Destination`	`getReplyTo()` Gets the replyTo destination
`String`	`getReplyToSuffix()` Returns the appended suffix to the session's default ReplyTo base topic set as part of this message's ReplyTo topic destination.
`String`	`getSenderId()` Returns the Sender's ID.
`String`	`getSenderID()` Deprecated. Renamed to `XMLMessage.getSenderId()`.
`Long`	`getSenderTimestamp()` Gets the send timestamp (in milliseconds, from midnight, January 1, 1970 UTC).
`Long`	`getSendTimestamp()` Deprecated. Renamed to `XMLMessage.getSenderTimestamp()`.
`Long`	`getSequenceNumber()` Gets the sequence number.
`long`	`getTimeToLive()` The number of milliseconds before the message is discarded or moved to Dead Message Queue.
`Long`	`getTopicSequenceNumber()` Gets the topic sequence number generated by the appliance.
`byte[]`	`getUserData()` When an application sends a message, it can optionally attach application-specific data along with the message, such as user data.
`boolean`	`hasAttachment()` Checks whether the message has an attachment.
`boolean`	`hasContent()` Checks whether the message has content.
`boolean`	`hasUserData()` Checks whether a received message includes user data.
`boolean`	`isAckImmediately()` Test if the ACK Immediately message property is set or not.
`boolean`	`isCacheMessage()` Returns `true` if this message was part of a cache reply.
`boolean`	`isDMQEligible()` The method returns whether the message is eligible to be moved to a Dead Message Queue (DMQ) upon expiration.
`boolean`	`isElidingEligible()` Checks whether the message is eligible for eliding.
`boolean`	`isReadOnly()` Tests if the message is read only.
`boolean`	`isReplyMessage()` Returns whether the message's reply field is set, indicating that this message is a reply.
`boolean`	`isSuspect()` Return `true` if this message was part of a cache reply that had the suspect flag set.
`int`	`readAttachmentBytes(byte[] byteOutputBuffer)` Reads bytes from an attachment, copying the data to the supplied byte array.
`int`	`readAttachmentBytes(byte[] byteOutputBuffer, int length)` Reads `length` bytes from an attachment, copying the data to the supplied byte array.
`int`	`readAttachmentBytes(int srcPos, byte[] byteOutputBuffer, int destPos, int length)` Reads `length` bytes from an attachment, copying the data to the supplied byte array.
`int`	`readContentBytes(byte[] byteOutputBuffer)` Reads from the message content, copying the data to the supplied byte array.
`int`	`readContentBytes(byte[] byteOutputBuffer, int length)` Reads `length` bytes from the message content, copying the data to the supplied byte array.
`int`	`readContentBytes(int srcPos, byte[] byteOutputBuffer, int destPos, int length)` Reads `length` bytes from the message content, copying the data to the supplied byte array.
`void`	`rejectMessage()` Deprecated. As of version 4.0, rejectMessage has no separate effect from ackMessage. Applications should avoid using this method as it will be removed in a future release.
`void`	`reset()` Resets the message, clearing all fields, preparing it for publishing again.
`void`	`rewindAttachment()` Deprecated. This method no longer has any effect.
`void`	`setAckImmediately(boolean ackImmediately)` Set the ACK Immediately message property.
`void`	`setApplicationMessageId(String msgId)` Sets the message ID (a string for an application-specific message identifier).
`void`	`setApplicationMessageType(String appMsgType)` Sets the application message type.
`void`	`setAppMessageID(String msgId)` Deprecated. Renamed to `XMLMessage.setApplicationMessageId(String)`.
`void`	`setAppMessageType(String appMsgType)` Deprecated. Renamed to `XMLMessage.setApplicationMessageType(String)`.
`void`	`setAsReplyMessage(boolean isReply)` Sets the reply field of the message.
`void`	`setCorrelationId(String id)` Sets the correlation ID.
`void`	`setCorrelationKey(Object key)` Sets the correlation key for the message.
`void`	`setCos(User_Cos cosValue)` Sets the Class of Service (CoS) value for this message.
`void`	`setDeliverToOne(boolean deliverToOne)` Deprecated.
`void`	`setDeliveryMode(DeliveryMode mode)` Sets the delivery mode of the message.
`void`	`setDMQEligible(boolean dmqEligible)` Set the message to be eligible to be moved to a Dead Message Queue.
`void`	`setElidingEligible(boolean eliding)` Sets whether the message is eligible for eliding.
`void`	`setExpiration(long expiration)` The UTC time (in milliseconds, from midnight, January 1, 1970 UTC) when the message is supposed to expire.
`void`	`setHTTPContentEncoding(String contentEncoding)` Sets the HTTP content type encoding value for interaction with an HTTP client.
`void`	`setHTTPContentType(String contentType)` Sets the HTTP content type header value for interaction with an HTTP client.
`void`	`setMessageType(MessageType msgType)` Deprecated. See `XMLMessage.setDeliveryMode(DeliveryMode)`. Sets the type of the message. Valid types are enumerated in `MessageType`: `MessageType.NON_PERSISTENT` `MessageType.PERSISTENT` `MessageType.DIRECT` (default)
`void`	`setPriority(int priority)` A message can optionally have priority set.
`void`	`setProperties(SDTMap props)` This method allows users to specify their own user properties to be carried in the message separate from the payload.
`void`	`setReadOnly()` The message can be set as read only.
`void`	`setReplyTo(Destination destination)` Sets the replyTo destination for the message.
`void`	`setReplyToSuffix(String suffix)` Appends a String to the session's default ReplyTo base topic and creates a ReplyTo Topic Destination.
`void`	`setSenderId(String senderId)` Sets the Sender ID for the message.
`void`	`setSenderID(String senderID)` Deprecated. Renamed to `XMLMessage.setSenderId(String)`.
`void`	`setSenderTimestamp(long ts)` Allows the application to set the send timestamp, if so the API will not generate a value.
`void`	`setSendTimestamp(long ts)` Deprecated. Renamed to `XMLMessage.setSenderTimestamp(long)`.
`void`	`setSequenceNumber(long seqNum)` Sets the sequence number.
`void`	`setTimeToLive(long ttl)` The number of milliseconds before the message is discarded or moved to a Dead Message Queue.
`void`	`settle(XMLMessage.Outcome outcome)` Settles a message in a requested way.
`void`	`setUserData(byte[] userData)` When an application sends a message, it can optionally attach application-specific data along with the message as user data.
`int`	`writeAttachment(byte[] byteInputBuffer)` Writes a new attachment to the message.
`int`	`writeAttachment(byte[] byteInputBuffer, int offset, int length)` Writes a new attachment to the message.
`int`	`writeAttachment(InputStream stream)` Writes a new attachment to the message.
`int`	`writeNewAttachment(byte[] byteInputBuffer)` Deprecated. Use `XMLMessage.writeAttachment(byte[])` instead
`int`	`writeNewAttachment(byte[] byteInputBuffer, int offset, int length)` Deprecated. Use `XMLMessage.writeAttachment(byte[],int,int)` instead.
`int`	`writeNewAttachment(InputStream stream)` Deprecated. Use `XMLMessage.writeAttachment(InputStream)` instead.
`int`	`writeNewAttachment(InputStream stream, int offset, int length)` Deprecated. Use `XMLMessage.writeAttachment(InputStream)` instead.

- Field Detail
  - MSGDUMP_BRIEF
```
static final int MSGDUMP_BRIEF
```
    A flag to control output of XMLMessage.dump(int); display only the length of the binary attachment, xml attachment, and user property maps.
    
    See Also:
    
    Constant Field Values
  - MSGDUMP_FULL
```
static final int MSGDUMP_FULL
```
    A flag to control output of XMLMessage.dump(int); display the entire message contents.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getMessageId
```
@Deprecated
String getMessageId()
```
    Deprecated. Use XMLMessage.ackMessage() to acknowledge messages. The message ID is only to be used for the purpose of acknowledgements. No other meaning should be inferred from the value of the guaranteed message ID.
    Returns the message ID set by JCSMP during send or reception. The message ID is the String representation of a 64-bit unsigned integer value identifying the message.
    On the receiving side, if messages received do not have message ID set by the appliance, JCSMP automatically assigns one and guarantees its uniqueness for a particular <subscriber; message type>.
    Guaranteed messages delivered from the appliance have a appliance-assigned message ID. Messages sent or received over the Direct delivery mode are assigned a message ID by the API, but its value is not meaningful.
    
    Returns:
    
    The message ID.
  - getMessageIdLong
```
@Deprecated
long getMessageIdLong()
```
    Deprecated. Use XMLMessage.ackMessage() to acknowledge messages. The message ID is only to be used for the purpose of acknowledgements. No other meaning should be inferred from the value of the guaranteed message ID.
    Returns the message ID set by JCSMP during send or reception. For discussion of message ID assignment, see XMLMessage.getMessageId().
    
    Returns:
    
    The message ID.
  - getUserData
```
byte[] getUserData()
```
    When an application sends a message, it can optionally attach application-specific data along with the message, such as user data. The user data is passed along with the message from the sender to the receiver. Use the hasUserData() method to check whether user data is present on a received message.
    NOTE: The maximum length of the user data is 36 bytes.
    
    Returns:
    
    Returns a reference to the user data array, or null if none is present.
  - setUserData
```
void setUserData(byte[] userData)
```
    When an application sends a message, it can optionally attach application-specific data along with the message as user data. This data is passed along with the message from the sender to the receiver and is not processed by the appliance network.
    NOTE: The maximum length of user data is 36 bytes.
    
    Parameters:
    
    userData - The user data - copied into the message object.
  - hasUserData
```
boolean hasUserData()
```
    Checks whether a received message includes user data.
    
    Returns:
    
    true if user data is present, false otherwise.
  - getContentLength
```
int getContentLength()
```
    The length of the message content. If content is not set, 0 is returned.
    
    Returns:
    
    The length of the message content, 0 when content is not set.
  - setReadOnly
```
void setReadOnly()
```
    The message can be set as read only. Once this flag is set, any write operation causes an IllegalAccessError to be raised.
  - isReadOnly
```
boolean isReadOnly()
```
    Tests if the message is read only.
    
    Returns:
    
    boolean true if set to read only, false otherwise
  - setMessageType
```
void setMessageType(MessageType msgType)
```
    Deprecated.
    See XMLMessage.setDeliveryMode(DeliveryMode). Sets the type of the message. Valid types are enumerated in MessageType:
    
    MessageType.NON_PERSISTENT
    MessageType.PERSISTENT
    MessageType.DIRECT (default)
    Parameters:
    
    msgType - An enumerated type (MessageType) representing one of the CSMP message types.
  - getMessageType
```
MessageType getMessageType()
```
    Deprecated.
    See XMLMessage.getDeliveryMode(). Gets the type of the message. Valid types are enumerated in MessageType:
    
    MessageType.NON_PERSISTENT
    
    MessageType.PERSISTENT
    
    MessageType.DIRECT (default)
    Returns:
    
    An enumerated type MessageType representing one of the four message types.
  - setDeliveryMode
```
void setDeliveryMode(DeliveryMode mode)
```
    Sets the delivery mode of the message.
    
    Parameters:
    
    mode - An enumerated type (DeliveryMode) representing one of the CSMP delivery modes.
  - getDeliveryMode
```
DeliveryMode getDeliveryMode()
```
    Gets the delivery mode of the message.
    
    Returns:
    
    An enumerated type (DeliveryMode) representing one of the CSMP delivery modes.
  - getPriority
```
int getPriority()
```
    Returns priority value in the range of 0–255, or -1 if it is not set.
    
    Returns:
    
    The message priority.
    
    Throws:
    
    IllegalArgumentException - priority is not set.
  - setPriority
```
void setPriority(int priority)
```
    A message can optionally have priority set.
    The valid priority value range is 0-255 with 0 as the lowest priority and 255 as the highest. Value -1 indicates the priority is not set and a default priority value is used instead.
    
    Parameters:
    
    priority - parameter
    
    Throws:
    
    IllegalArgumentException - an out-of-range value is passed in.
  - setCos
```
void setCos(User_Cos cosValue)
```
    Sets the Class of Service (CoS) value for this message. The Class of Service has different semantics for direct and guaranteed messages. For direct messaging, it determines the WRR weight for the message. For guaranteed messaging, it indicates the discard eligibility of the message when its destination endpoint is congested.
    
    Parameters:
    
    cosValue - Class of Service (CoS).
  - getCos
```
User_Cos getCos()
```
    Gets the Class of Service (CoS) value for this message.
    
    Returns:
    
    The Class of Service (CoS) set on this message.
  - getTimeToLive
```
long getTimeToLive()
```
    The number of milliseconds before the message is discarded or moved to Dead Message Queue. A value of 0 means the message will never expire. The default value is 0.
    
    Returns:
    
    The number of milliseconds before the message is discarded or moved to Dead Message Queue.
  - setTimeToLive
```
void setTimeToLive(long ttl)
```
    The number of milliseconds before the message is discarded or moved to a Dead Message Queue.
    A value of 0 means the message never expires. The default value is 0.
    Note: Calling this method with a value of 0 explicitly resets previously set message expiration to 0.
    This property is only valid for Guaranteed messages (Persistent and Non-Persistent). It has no effect when used in conjunction with other message types unless the message is promoted by the appliance to a Guaranteed message.
    
    Parameters:
    
    ttl - The number of milliseconds the Guaranteed message is allowed to live before delivery to a subscriber.
    
    Throws:
    
    IllegalArgumentException - If a negative value is passed in, or a value greater than 10 years.
  - getExpiration
```
long getExpiration()
```
    The UTC time (in milliseconds, from midnight, January 1, 1970 UTC) when the message is supposed to expire. This field only serves as a reference as to when the message may expire.
    A value of 0 means the message never expires. The default value is 0.
    If TimeToLive is set to a value greater than 0 before sending, getExpiration() will have one of the following values:
    - On the publishing side, if JCSMPProperties.CALCULATE_MESSAGE_EXPIRATION is set to true, getExpiration() returns the sum of the message's TimeToLive and UTC value after the message is sent at the first send attempt. Otherwise, getExpiration() returns 0.
    - On the receiving side, if JCSMPProperties.CALCULATE_MESSAGE_EXPIRATION is set to true, getExpiration() returns the sum of TimeToLive and the UTC value when the message is received. Otherwise, getExpiration returns 0.
    This setting is only valid for Guaranteed messages (Persistent and Non-Persistent). It has no effect when used for a Direct message unless the message is promoted by the appliance to a Guaranteed message.
    Returns:
    
    The UTC time when the message is discarded or moved to a Dead Message Queue.
  - setExpiration
```
void setExpiration(long expiration)
```
    The UTC time (in milliseconds, from midnight, January 1, 1970 UTC) when the message is supposed to expire. Setting this property has no effect if the TimeToLive is set in the same message. It is carried to clients that receive the message, unmodified and does not effect the life cycle of the message. Use setTimeToLive() to enforce message expiry in the network.
    This field only serves as a reference as to when the message may expire. A value of 0 means the message never expires. The default value is 0.
    Note: If TimeToLive is set to zero explicitly by application, any previously set Expiration is reset to 0.
    This setting is only valid for Guaranteed messages (Persistent and Non-Persistent). It has no effect when used for a Direct message unless the message is promoted by the appliance to a Guaranteed message.
    
    Parameters:
    
    expiration - parameter
    
    Throws:
    
    IllegalArgumentException - If a negative value is passed in.
  - isDMQEligible
```
boolean isDMQEligible()
```
    The method returns whether the message is eligible to be moved to a Dead Message Queue (DMQ) upon expiration. If the value is false, the message is discarded upon expiration. The default value is false.
    This setting is only valid for Guaranteed messages (Persistent and Non-Persistent). It has no effect when used for a Direct message unless the message is promoted by the appliance to a Guaranteed message.
    
    Returns:
    
    A boolean indicating whether the message is eligible to be moved to a Dead Message Queue.
  - setDMQEligible
```
void setDMQEligible(boolean dmqEligible)
```
    Set the message to be eligible to be moved to a Dead Message Queue. The default value is false.
    This setting is only valid for Guaranteed messages (Persistent and Non-Persistent). It has no effect when used for a Direct message unless the message is promoted by the appliance to a Guaranteed message.
    
    Parameters:
    
    dmqEligible - Whether the message is eligible to be moved to a DMQ upon expiration.
  - getRedelivered
```
boolean getRedelivered()
```
    Indicates if the message has been delivered by the appliance to the API before.
    
    Returns:
    
    A boolean indicating if the message has been delivered before.
  - getDiscardIndication
```
boolean getDiscardIndication()
```
    Returns true if one or more messages have been discarded prior to the current message, else false. This indicates congestion discards only and is not affected by message eliding.
    
    Returns:
    
    True if prior messages have been discarded, else false.
    
    See Also:
    
    XMLMessage.isElidingEligible()
  - ackMessage
```
void ackMessage()
```
    Acknowledges the message.
    If a JCSMPSession is configured to use SUPPORTED_MESSAGE_ACK_CLIENT, when a message is successfully received by an application, the application must call this method to explicitly acknowledge reception of the message in order to free system resources associated with an unacknowledged message.
    Note: If a JCSMPSession is configured to use JCSMPProperties.SUPPORTED_MESSAGE_ACK_AUTO (the default behaviour), the call to this method is ignored and a warning log is generated.
    
    Acknowledged messages are removed from the appliance's message spool.
    
    Throws:
    
    IllegalStateException - If the consumer that received this message is closed. (A runtime exception.)
  - settle
```
void settle(XMLMessage.Outcome outcome)
     throws JCSMPException
```
    Settles a message in a requested way.
    NOTE: Ignored on transacted flows
    
    Parameters:
    
    outcome - type of the settlement outcome.
    
    Throws:
    
    InvalidOperationException - can be thrown when settlementOutcome is null or the broker does not support specified outcome option.
    
    JCSMPException - can be thrown for some other internal reason
    
    IllegalStateException - If the consumer that received this message is closed. (A runtime exception.)
  - rejectMessage
```
@Deprecated
void rejectMessage()
```
    Deprecated. As of version 4.0, rejectMessage has no separate effect from ackMessage. Applications should avoid using this method as it will be removed in a future release.
    
    Throws:
    
    JCSMPException
  - clearContent
```
void clearContent()
```
    Clears the message content. This method can only be called on a message that is not read-only. An incoming message from the appliance is read-only, as is an outgoing producer-dependent message after being sent.
    
    Throws:
    
    IllegalAccessError - If called on a read-only message.
  - hasContent
```
boolean hasContent()
```
    Checks whether the message has content.
    
    Returns:
    
    True if the message has content, false otherwise.
  - readContentBytes
```
int readContentBytes(int srcPos,
                     byte[] byteOutputBuffer,
                     int destPos,
                     int length)
```
    Reads length bytes from the message content, copying the data to the supplied byte array.
    If the number of bytes to be read in the content is less than length, all content bytes are read into the array.
    
    Parameters:
    
    srcPos - The starting position in the source array.
    
    byteOutputBuffer - A destination byte array to fill.
    
    destPos - The starting position in the destination array.
    
    length - The number of bytes to read.
    
    Returns:
    
    The number of bytes read, or -1 if there is nothing to read.
  - readContentBytes
```
int readContentBytes(byte[] byteOutputBuffer)
```
    Reads from the message content, copying the data to the supplied byte array. The output array should be properly sized for the length of the content to read.
    
    Parameters:
    
    byteOutputBuffer - A destination byte array to fill.
    
    Returns:
    
    The number of bytes read, or -1 if there is nothing to read.
  - readContentBytes
```
int readContentBytes(byte[] byteOutputBuffer,
                     int length)
```
    Reads length bytes from the message content, copying the data to the supplied byte array.
    If the number of bytes to be read in the content is less than length, all content bytes are read into the array.
    
    Parameters:
    
    byteOutputBuffer - A destination byte array to fill.
    
    length - The number of bytes to read.
    
    Returns:
    
    The number of bytes read, or -1 if there is nothing to read.
  - clearAttachment
```
void clearAttachment()
```
    Deletes the attachment to the message. This method can only be called on a message that is not read-only. An incoming message from the appliance is read-only, as is an outgoing producer-dependent message after being sent.
    
    Throws:
    
    IllegalAccessError - If called on a read-only message.
  - hasAttachment
```
boolean hasAttachment()
```
    Checks whether the message has an attachment.
    
    Returns:
    
    True if the message has an attachment, false otherwise.
  - getAttachmentContentLength
```
int getAttachmentContentLength()
```
    Gets the length of the attachment.
    
    Returns:
    
    The number of bytes comprising the attachment content.
  - getAttachmentByteBuffer
```
ByteBuffer getAttachmentByteBuffer()
```
    Gets a ByteBuffer containing the message's binary attachment. The buffer's position is set to the beginning of the attachment, its limit set to the length of the attachment, and its mark is undefined.
    
    Returns:
    
    A new ByteBuffer view wrapping a byte array owned by this message. If no attachment is present in this message, returns null.
  - readAttachmentBytes
```
int readAttachmentBytes(byte[] byteOutputBuffer)
```
    Reads bytes from an attachment, copying the data to the supplied byte array.
    If the length of the array is less than the number of bytes remaining to be read, the array is filled.
    If the number of bytes to be read in the attachment is less than the length of the array, all attachment bytes are read into the array. Use XMLMessage.getAttachmentContentLength() to find the size of the attachment in order to provide a correctly-sized array.
    
    Parameters:
    
    byteOutputBuffer - A byte array to fill with bytes from the attachment.
    
    Returns:
    
    The number of bytes read.
  - readAttachmentBytes
```
int readAttachmentBytes(byte[] byteOutputBuffer,
                        int length)
```
    Reads length bytes from an attachment, copying the data to the supplied byte array.
    If the number of bytes to be read in the attachment is less than length, all attachment bytes are read into the array.
    
    Parameters:
    
    byteOutputBuffer - A byte array to fill with bytes from the attachment.
    
    length - The number of bytes to read.
    
    Returns:
    
    The number of bytes read.
  - readAttachmentBytes
```
int readAttachmentBytes(int srcPos,
                        byte[] byteOutputBuffer,
                        int destPos,
                        int length)
```
    Reads length bytes from an attachment, copying the data to the supplied byte array.
    If the number of bytes to be read in the attachment is less than length, all attachment bytes are read into the array.
    Parameter ordering mimics the semantics of System#arraycopy.
    
    Parameters:
    
    srcPos - The starting position in the source array.
    
    byteOutputBuffer - A destination byte array to fill.
    
    destPos - The starting position in the destination array.
    
    length - The number of bytes to read.
    
    Returns:
    
    The number of bytes read, or -1 if there is nothing to read.
  - rewindAttachment
```
void rewindAttachment()
```
    Deprecated. This method no longer has any effect.
    
    Resets the read mark for attachment to 0. The next call to XMLMessage.readAttachmentBytes(byte[]) or XMLMessage.readAttachmentBytes(byte[], int) reads from the beginning of the attachment.
  - writeNewAttachment
```
int writeNewAttachment(byte[] byteInputBuffer)
```
    Deprecated. Use XMLMessage.writeAttachment(byte[]) instead
    
    Writes a new attachment to the message. This operation causes a new Message ID to be generated when the message is sent. If called multiple times, the existing attachment is replaced.
    
    Parameters:
    
    byteInputBuffer - A byte array to copy as attachment content.
    
    Returns:
    
    The number of bytes written.
  - writeAttachment
```
int writeAttachment(byte[] byteInputBuffer)
```
    Writes a new attachment to the message. This operation causes a new Message ID to be generated when the message is sent. If called multiple times, the existing attachment is replaced.
    This method copies the input bytes into the message.
    
    Parameters:
    
    byteInputBuffer - A byte array to copy as attachment content.
    
    Returns:
    
    The number of bytes written.
  - writeNewAttachment
```
int writeNewAttachment(byte[] byteInputBuffer,
                       int offset,
                       int length)
                throws BufferUnderflowException
```
    Deprecated. Use XMLMessage.writeAttachment(byte[],int,int) instead.
    
    Writes a new attachment to the message. If called multiple times, the existing attachment is replaced. If offset or length are negative, an IllegalArgumentException is thrown. If length or offset result in an attempt to read past the end of the array, a BufferUnderflowException is thrown.
    
    Parameters:
    
    byteInputBuffer - A byte array to copy as attachment content.
    
    offset - The offset from which to read bytes from the input buffer.
    
    length - The number of bytes to copy.
    
    Returns:
    
    The number of bytes written.
    
    Throws:
    
    BufferUnderflowException
  - writeAttachment
```
int writeAttachment(byte[] byteInputBuffer,
                    int offset,
                    int length)
             throws BufferUnderflowException
```
    Writes a new attachment to the message. If called multiple times, the existing attachment is replaced. If offset or length are negative, an IllegalArgumentException is thrown. If length or offset result in an attempt to read past the end of the array, a BufferUnderflowException is thrown.
    This method copies the input bytes into the message.
    
    Parameters:
    
    byteInputBuffer - A byte array to copy as attachment content.
    
    offset - The offset from which to read bytes from the input buffer.
    
    length - The number of bytes to copy.
    
    Returns:
    
    The number of bytes written.
    
    Throws:
    
    BufferUnderflowException - on error
  - writeNewAttachment
```
int writeNewAttachment(InputStream stream,
                       int offset,
                       int length)
                throws IOException
```
    Deprecated. Use XMLMessage.writeAttachment(InputStream) instead.
    
    Writes a new attachment to the message. If called multiple times, the existing attachment is replaced. If offset or length are negative, an IllegalArgumentException is thrown.
    
    Parameters:
    
    stream - A stream from which to read attachment content.
    
    offset - The offset from which to read bytes from the input stream.
    
    length - The number of bytes to read from the stream.
    
    Returns:
    
    The number of bytes written.
    
    Throws:
    
    IOException
  - writeNewAttachment
```
int writeNewAttachment(InputStream stream)
                throws IOException
```
    Deprecated. Use XMLMessage.writeAttachment(InputStream) instead.
    
    Writes a new attachment to the message. If called multiple times, it overwrites a previously set attachment.
    
    Parameters:
    
    stream - A stream from which to read attachment content.
    
    Returns:
    
    The number of bytes written.
    
    Throws:
    
    IOException
  - writeAttachment
```
int writeAttachment(InputStream stream)
             throws IOException
```
    Writes a new attachment to the message. If called multiple times, it overwrites a previously-set attachment.
    This method copies the input bytes into the message.
    
    Parameters:
    
    stream - A stream from which to read attachment content.
    
    Returns:
    
    The number of bytes written.
    
    Throws:
    
    IOException
  - isAckImmediately
```
boolean isAckImmediately()
```
    Test if the ACK Immediately message property is set or not. When it is set to true on an outgoing Guaranteed message, it indicates that the appliance should ACK this message immediately upon receipt. The default value is false.
    This setting is only valid for Guaranteed messages (Persistent and Non-Persistent). It has no effect when used for a Direct message.
    This property, when set by a publisher, may or may not be removed by the appliance prior to delivery to a consumer, so message consumers must not rely on this property being present.
    
    Returns:
    
    A boolean indicating whether the message should be ACKed by the appliance immediately upon receipt.
  - setAckImmediately
```
void setAckImmediately(boolean ackImmediately)
```
    Set the ACK Immediately message property. When it is set to true on an outgoing Guaranteed message, it indicates that the appliance should ACK this message immediately upon receipt. The default value is false.
    This setting is only valid for Guaranteed messages (Persistent and Non-Persistent). It has no effect when used for a Direct message.
    This property, when set by a publisher, may or may not be removed by the appliance prior to delivery to a consumer, so message consumers must not rely on this property being present.
    
    Parameters:
    
    ackImmediately - Whether the message should be ACKed by the appliance immediately upon receipt.
  - getConsumerIdList
```
List<Long> getConsumerIdList()
```
    Gets a read-only list of consumer IDs set on this message. A consumer ID is an integer in the range 0x00000000 - 0xFFFFFFFE, and each one indicates that the received message matched at least one subscription with that consumer ID on the appliance.
    Consumer IDs are only present once, even if multiple subscriptions with that consumer ID each have caused a match.
    The return value is null if no consumer IDs are set on the message.
    
    Returns:
    
    Read-only list of consumerIDs on this message.
  - getDestination
```
Destination getDestination()
```
    Gets the destination this message was published to. The destination is returned as a Queue or Topic instance.
    
    Returns:
    
    The destination this message was published to, or null if unavailable.
  - getCorrelationKey
```
Object getCorrelationKey()
```
    Gets the correlation key for the message. A correlation key is used for asynchronous message acknowledgement notification by JCSMPStreamingPublishCorrelatingEventHandler.
    
    Returns:
    
    The correlation key associated with this message, or null if unset.
  - setCorrelationKey
```
void setCorrelationKey(Object key)
```
    Sets the correlation key for the message. A correlation key is used for asynchronous message acknowledgement notification by JCSMPStreamingPublishCorrelatingEventHandler. Only effective for PERSISTENT and NON-PERSISTENT messages (that is, Guaranteed Delivery).
    
    Parameters:
    
    key - The correlation key to associate with this message.
  - getSenderID
```
String getSenderID()
```
    Deprecated. Renamed to XMLMessage.getSenderId().
  - getSenderId
```
String getSenderId()
```
    Returns the Sender's ID. This field can be set automatically during message publishing, but existing values are not overwritten if non-null, as when a message is sent multiple times.
    
    Returns:
    
    The Sender's ID; null, if it is not set.
  - setSenderID
```
void setSenderID(String senderID)
```
    Deprecated. Renamed to XMLMessage.setSenderId(String).
  - setSenderId
```
void setSenderId(String senderId)
```
    Sets the Sender ID for the message. This field can be set automatically during message publishing, but existing values are not overwritten if non-null, as when a message is sent multiple times.
    
    Parameters:
    
    senderId - The Sender ID for the message.
  - getSendTimestamp
```
@Deprecated
Long getSendTimestamp()
```
    Deprecated. Renamed to XMLMessage.getSenderTimestamp().
  - setSendTimestamp
```
@Deprecated
void setSendTimestamp(long ts)
```
    Deprecated. Renamed to XMLMessage.setSenderTimestamp(long).
  - getSenderTimestamp
```
Long getSenderTimestamp()
```
    Gets the send timestamp (in milliseconds, from midnight, January 1, 1970 UTC). This field can be set automatically during message publishing or it may have been set explicitly by the sending application.
    
    Returns:
    
    The send timestamp. Null if it was not set on send.
  - setSenderTimestamp
```
void setSenderTimestamp(long ts)
```
    Allows the application to set the send timestamp, if so the API will not generate a value. This field can be generated automatically during message publishing, but only if the senderTimestamp is not set.
    
    Parameters:
    
    ts - The value to set as the send timestamp.
  - getReceiveTimestamp
```
long getReceiveTimestamp()
```
    Gets the receive timestamp (in milliseconds, from midnight, January 1, 1970 UTC).
    
    Returns:
    
    The receive timestamp, or 0, if unset.
  - getAppMessageType
```
String getAppMessageType()
```
    Deprecated. Renamed to XMLMessage.getApplicationMessageType().
  - setAppMessageType
```
void setAppMessageType(String appMsgType)
```
    Deprecated. Renamed to XMLMessage.setApplicationMessageType(String).
  - getApplicationMessageType
```
String getApplicationMessageType()
```
    Gets the application message type. This value is used by applications only, and is passed through the API untouched.
    
    Returns:
    
    The application message type.
  - setApplicationMessageType
```
void setApplicationMessageType(String appMsgType)
```
    Sets the application message type. This value is used by applications only and is passed through the API untouched.
    
    Parameters:
    
    appMsgType - The application message type.
  - getSequenceNumber
```
Long getSequenceNumber()
```
    Gets the sequence number. This field can be set automatically during message publishing, but existing values are not overwritten if non-null, as when a message is sent multiple times.
    
    Returns:
    
    The sequence number. Null if it was not set on send.
  - setSequenceNumber
```
void setSequenceNumber(long seqNum)
```
    Sets the sequence number. If sequence number generation is enabled, this method's argument overrides the generated value. This field can be set automatically during message publishing, but existing values are not overwritten if set, as when a message is sent multiple times.
    
    Parameters:
    
    seqNum - The sequence number.
  - getAppMessageID
```
String getAppMessageID()
```
    Deprecated. Renamed to XMLMessage.getApplicationMessageId().
  - setAppMessageID
```
void setAppMessageID(String msgId)
```
    Deprecated. Renamed to XMLMessage.setApplicationMessageId(String).
  - getApplicationMessageId
```
String getApplicationMessageId()
```
    Gets the application message ID, a string for an application-specific message identifier.
    
    Returns:
    
    the message ID. null if it was not set on send.
  - setApplicationMessageId
```
void setApplicationMessageId(String msgId)
```
    Sets the message ID (a string for an application-specific message identifier).
    
    Parameters:
    
    msgId - The message ID.
  - getProperties
```
SDTMap getProperties()
```
    Gets the user properties map. For a received message the user properties can be retrieved from this map. For a message to be sent, the user properties can be added to this map.
    
    Returns:
    
    The user properties map, or null if no user properties map has been set on this message.
  - setProperties
```
void setProperties(SDTMap props)
```
    This method allows users to specify their own user properties to be carried in the message separate from the payload. This enable users to supplement the Solace-defined properties (correlation id, send timestamp, sequence number, etc.). To create an SDTMap see Producer
    
    Parameters:
    
    props - The user properties map.
  - setAsReplyMessage
```
void setAsReplyMessage(boolean isReply)
```
    Sets the reply field of the message.
    
    Parameters:
    
    isReply - Whether to set or clear the reply attribute.
  - isReplyMessage
```
boolean isReplyMessage()
```
    Returns whether the message's reply field is set, indicating that this message is a reply.
    
    Returns:
    
    A boolean indicating the state of the reply field.
  - getReplyTo
```
Destination getReplyTo()
```
    Gets the replyTo destination
    
    Returns:
    
    The replyTo destination or NULL if not set.
  - setReplyTo
```
void setReplyTo(Destination destination)
```
    Sets the replyTo destination for the message.
    
    Parameters:
    
    destination - The replyTo destination.
    
    Throws:
    
    IllegalArgumentException - If topic is invalid.
  - setReplyToSuffix
```
void setReplyToSuffix(String suffix)
```
    Appends a String to the session's default ReplyTo base topic and creates a ReplyTo Topic Destination. If the string does not start with a topic delimiter ('/'), then a delimiter is inserted as well.
    
    Parameters:
    
    suffix - The suffix to append when setting a new ReplyTo destination on this message.
  - getReplyToSuffix
```
String getReplyToSuffix()
```
    Returns the appended suffix to the session's default ReplyTo base topic set as part of this message's ReplyTo topic destination.
    
    Returns:
    
    The suffix, or null if unset or ReplyTo is not a Topic.
  - getDestinationTopicSuffix
```
String getDestinationTopicSuffix()
```
    Returns the string, without a leading delimiter, that is found after the session's default ReplyTo base topic in an incoming message. This is intended to allow a receiving application to demultiplex incoming replies addressed to several ReplyTo topics. If the Destination in the message (as returned by getDestination()) does not begin with the session's default ReplyTo base topic, then null is returned.
    
    Returns:
    
    The suffix appended to the incoming message's topic destination.
  - getDeliverToOne
```
boolean getDeliverToOne()
```
    Deprecated.
    
    Gets whether this message is configured for delivering to one client only. Deliver to one is False by default.
    
    Returns:
    
    true if this message was configured to deliver to one client only.
  - setDeliverToOne
```
void setDeliverToOne(boolean deliverToOne)
```
    Deprecated.
    
    Configures this message to be delivered to one client only. Deliver to one is False by default.
    When a direct message has the DeliverToOne property set to true , it can be delivered only to one client. For a Guaranteed Delivery message, this behavior only applies to the "demoted" direct copy of this message.
    
    Parameters:
    
    deliverToOne - True to enable delivering to one client only.
  - getCorrelationId
```
String getCorrelationId()
```
    Gets the correlation ID. The correlation ID is used for correlating a request to a reply.
    
    Returns:
    
    The correlation ID associated with this message, or null, if unset.
  - setCorrelationId
```
void setCorrelationId(String id)
```
    Sets the correlation ID. The correlation ID is used for correlating a request to a reply.
    
    Parameters:
    
    id - The correlation ID to associate with this message.
  - isCacheMessage
```
boolean isCacheMessage()
```
    Returns true if this message was part of a cache reply.
    
    Returns:
    
    true if this message was part of a cache reply.
  - isSuspect
```
boolean isSuspect()
```
    Return true if this message was part of a cache reply that had the suspect flag set.
    
    Returns:
    
    true if this message was part of a cache reply that had the suspect flag set.
  - getCacheRequestId
```
Long getCacheRequestId()
```
    Return the request ID set in the cache request. Always null if isCacheMessage() is false.
    
    Returns:
    
    The request ID set in the cache request.
  - setElidingEligible
```
void setElidingEligible(boolean eliding)
```
    Sets whether the message is eligible for eliding.
    
    Parameters:
    
    eliding - Whether the message is eligible for eliding.
    
    See Also:
    
    isElidingEligible() for more information about this feature.
  - isElidingEligible
```
boolean isElidingEligible()
```
    Checks whether the message is eligible for eliding.
    Message eliding enables filtering of data to avoid transmitting every single update to a subscribing client. It can be used to overcome slow consumers or any situation where a slower message rate is desired. Eliding can be applied to messages delivered to subscribers in DIRECT delivery mode.
    Time-based eliding ensures that subscriber applications always receive only the most current update of a published topic at a rate that they can manage. By limiting the incoming message rate, a subscriber application is able to avoid a message backlog filled with outdated messages. This property does not indicate whether messages were elided or provide information about the subscriber profile eliding configuration.
    
    Returns:
    
    Whether this message is eligible for eliding.
  - reset
```
void reset()
```
    Resets the message, clearing all fields, preparing it for publishing again. For use with session-independent messages acquired from JCSMPFactory.
  - dump
```
String dump()
```
    Produces a human-readable dump of the message properties and its contents (can be quite large). Applications must not parse the output as its format is undefined. This method is the equivalent of calling dump(MSGDUMP_FULL).
    
    Returns:
    
    A String representation of the message, to be used for debugging.
  - dump
```
String dump(int flags)
```
    Produces a human-readable dump of the message properties and its contents. Applications must not parse the output as its format is undefined.
    
    Flags
    Output can be controlled by the flags:
    - XMLMessage.MSGDUMP_BRIEF
    - XMLMessage.MSGDUMP_FULL
    Parameters:
    
    flags - Flags controlling the output, such as whether to include verbose (binary dump) information
    
    Returns:
    
    A String representation of the message, to be used for debugging.
  - getTopicSequenceNumber
```
Long getTopicSequenceNumber()
```
    Gets the topic sequence number generated by the appliance.
    
    Returns:
    
    The topic sequence number. Null if it was not generated by the appliance.
  - getHTTPContentType
```
String getHTTPContentType()
```
    Gets the HTTP content type header value from interaction with an HTTP client.
    
    Returns:
    
    The HTTP content type header value, or null if it is not set.
  - setHTTPContentType
```
void setHTTPContentType(String contentType)
```
    Sets the HTTP content type header value for interaction with an HTTP client.
    
    Parameters:
    
    contentType - The HTTP content type header value.
  - getHTTPContentEncoding
```
String getHTTPContentEncoding()
```
    Gets the HTTP content encoding header value from interaction with an HTTP client.
    
    Returns:
    
    The HTTP content encoding header value, or null if it is not set.
  - setHTTPContentEncoding
```
void setHTTPContentEncoding(String contentEncoding)
```
    Sets the HTTP content type encoding value for interaction with an HTTP client.
    
    Parameters:
    
    contentEncoding - The HTTP content encoding header value.
  - getDeliveryCount
```
int getDeliveryCount()
              throws UnsupportedOperationException
```
    Get message delivery count.
    
    Returns:
    
    The number of times the message has been delivered.
    
    Throws:
    
    UnsupportedOperationException
  - getReplicationGroupMessageId
```
ReplicationGroupMessageId getReplicationGroupMessageId()
```
    Get the Replication Group Message ID for the received message. This object may be used as a ReplayStartLocation in a later flow to create a request replay of all messages after this one.
    
    Returns:
    
    a ReplicationGroupMessageId or null if not present.

Interface XMLMessage

Thread Safety

Nested Class Summary

Field Summary

Method Summary

Field Detail

MSGDUMP_BRIEF

MSGDUMP_FULL

Method Detail

getMessageId

getMessageIdLong

getUserData

setUserData

hasUserData

getContentLength

setReadOnly

isReadOnly

setMessageType

getMessageType

setDeliveryMode

getDeliveryMode

getPriority

setPriority

setCos

getCos

getTimeToLive

setTimeToLive

getExpiration

setExpiration

isDMQEligible

setDMQEligible

getRedelivered

getDiscardIndication

ackMessage

settle

rejectMessage

clearContent

hasContent

readContentBytes

readContentBytes

readContentBytes

clearAttachment

hasAttachment

getAttachmentContentLength

getAttachmentByteBuffer

readAttachmentBytes

readAttachmentBytes

readAttachmentBytes

rewindAttachment

writeNewAttachment

writeAttachment

writeNewAttachment

writeAttachment

writeNewAttachment

writeNewAttachment

writeAttachment

isAckImmediately

setAckImmediately

getConsumerIdList

getDestination

getCorrelationKey

setCorrelationKey

getSenderID

getSenderId

setSenderID

setSenderId

getSendTimestamp

setSendTimestamp

getSenderTimestamp

setSenderTimestamp

getReceiveTimestamp

getAppMessageType

setAppMessageType

getApplicationMessageType

setApplicationMessageType

getSequenceNumber

setSequenceNumber

getAppMessageID

setAppMessageID

getApplicationMessageId