## Contents

- Properties
- Methods

class solace.Message

This class is not exposed for construction by API users. Users should obtain an instance from solace.SolclientFactory.createMessage

A message is a container that can be used to store and send messages to and from the Solace Message Router.

Applications manage the lifecycle of a message; a message is created by calling solace.SolclientFactory.createMessage and is freed by dereferencing it.

API operations that cache or mutate messages always take a copy. A message may be created, mutated by the API user, and sent multiple times.

The Message Object provides methods to manipulate the common Solace message header fields that are optionally sent in the binary metadata portion of the Solace message.

Applications can also use the structured data API solace.Message#setSdtContainer to add containers (maps or streams) and their fields to the binary payload or to the User Property map contained within the binary metadata.

This does not prevent applications from ignoring these methods and sending payload in the binary payload as an opaque binary field for end-to-end communications

## Constructor Top

| Message ( ) |  |

## Properties Top

readonly | isAcknowledged |  |

## Methods Top

void | acknowledge ( ) |
String | dump ( Number flags ) |
String | getApplicationMessageId ( ) |
String | getApplicationMessageType ( ) |
String | getBinaryAttachment ( ) |
Number | getCacheRequestId ( ) |
solace.MessageCacheStatus | getCacheStatus ( ) |
String | getCorrelationId ( ) |
Object | getCorrelationKey ( ) |
solace.MessageDeliveryModeType | getDeliveryMode ( ) |
Destination | getDestination ( ) |
Number | getGMExpiration ( ) |
Long | getGuaranteedMessageId ( ) |
solace.MessageConsumer | getMessageConsumer ( ) |
Number | getPriority ( ) |
Number | getReceiverTimestamp ( ) |
solace.Destination | getReplyTo ( ) |
SDTField | null | getSdtContainer ( ) |
String | getSenderId ( ) |
Number | getSenderTimestamp ( ) |
Number | getSequenceNumber ( ) |
Number | getTimeToLive ( ) |
Long | getTopicSequenceNumber ( ) |
solace.MessageType | getType ( ) |
solace.MessageUserCosType | getUserCos ( ) |
String | getUserData ( ) |
solace.SDTMapContainer | getUserPropertyMap ( ) |
String | getXmlContent ( ) |
String | getXmlContentDecoded ( ) |
String | getXmlMetadata ( ) |
Boolean | isAcknowledgeImmediately ( ) |
Boolean | isDeliverToOne ( ) |
Boolean | isDiscardIndication ( ) |
Boolean | isDMQEligible ( ) |
Boolean | isElidingEligible ( ) |
Boolean | isRedelivered ( ) |
Boolean | isReplyMessage ( ) |
void | reset ( ) |
void | setAcknowledgeImmediately ( Boolean value ) |
void | setApplicationMessageId ( String value ) |
void | setApplicationMessageType ( String value ) |
void | setAsReplyMessage ( Boolean value ) |
void | setBinaryAttachment ( String value ) |
void | setCorrelationId ( String value ) |
void | setCorrelationKey ( Object value ) |
void | setDeliverToOne ( Boolean value ) |
void | setDeliveryMode ( solace.MessageDeliveryModeType value ) |
void | setDestination ( Destination value ) |
void | setDMQEligible ( Boolean value ) |
void | setElidingEligible ( Boolean value ) |
void | setGMExpiration ( Number value ) |
void | setPriority ( Number value ) |
void | setReplyTo ( solace.Destination value ) |
void | setSdtContainer ( solace.SDTField container ) |
void | setSenderId ( String value ) |
void | setSenderTimestamp ( Number value ) |
void | setSequenceNumber ( Number value ) |
void | setTimeToLive ( Number value ) |
void | setUserCos ( solace.MessageUserCosType value ) |
void | setUserData ( String value ) |
void | setUserPropertyMap ( SDTMapContainer value ) |
void | setXmlContent ( String value ) |
void | setXmlMetadata ( String value ) |

## Constructor details Top

###
Message ( )

This class is not exposed for construction by API users. Users should obtain an instance from solace.SolclientFactory.createMessage

A message is a container that can be used to store and send messages to and from the Solace Message Router.

Applications manage the lifecycle of a message; a message is created by calling solace.SolclientFactory.createMessage and is freed by dereferencing it.

API operations that cache or mutate messages always take a copy. A message may be created, mutated by the API user, and sent multiple times.

The Message Object provides methods to manipulate the common Solace message header fields that are optionally sent in the binary metadata portion of the Solace message.

Applications can also use the structured data API solace.Message#setSdtContainer to add containers (maps or streams) and their fields to the binary payload or to the User Property map contained within the binary metadata.

This does not prevent applications from ignoring these methods and sending payload in the binary payload as an opaque binary field for end-to-end communications

## Properties Detail Top

###
public readonly isAcknowledged

Returns whether acknowledge() has been called on this message.

## Methods Detail Top

###
public void acknowledge ( )

Acknowledges this message.

If the solace.MessageConsumer on which this message was received is configured to use solace.MessageConsumerAckMode.CLIENT, then when a message is received by an application, the application must call this method to explicitly acknowledge reception of the message. This frees local and router resources associated with an unacknowledged message.

The API does not send acknowledgments immediately. It stores the state for acknowledged messages internally and acknowledges messages, in bulk, when a threshold or timer is reached.

#### Return Value

void |

#### Throws

| solace.OperationError if this message was not received via Guaranteed Message; subcode: solace.ErrorSubcode.MESSAGE_DELIVERY_MODE_MISMATCH if the associated solace.Session is not connected; subcode: solace.ErrorSubcode.SESSION_NOT_CONNECTED if the associated solace.MessageConsumer is not connectedl subcode: solace.ErrorSubcode.INVALID_OPERATION

###
public String dump ( Number flags )

Produces a human-readable dump of the message's properties and contents. Applications must not parse the output, as its format is not a defined part of the API and subject to change.

Output can be controlled by the `flags` parameter. The values are:

- MessageDumpFlag.MSGDUMP_BRIEF Display only the length of the binary attachment, xml attachment, and user property map
- MessageDumpFlag.MSGDUMP_FULL Display the entire message.

#### Parameters

Number | flags Optional flags controlling the output, such as whether to include verbose (binary dump) information (Optional)

#### Return Value

String | A string representation of the message.

###
public String getApplicationMessageId ( )

Gets the application-provided message ID.

#### Return Value

String | The application provided message ID. (Optional)

###
public String getApplicationMessageType ( )

Gets the application message type. This value is used by applications only, and is passed through the API and Solace Message Router untouched.

#### Return Value

String | The application message type. (Optional)

###
public String getBinaryAttachment ( )

Gets the binary attachment part of the message. The binary attachment is returned as a string, wherein each character has a code in the range 0-255 representing the value of a single received byte at that position.

#### Return Value

String | A string representing the binary attachment. (Optional)

###
public Number getCacheRequestId ( )

Given a Message containing a cached message, return the cache Request Id that the application set in the call to solace.CacheSession#sendCacheRequest.

#### Return Value

Number | The request ID of the cache request associated with this message. (Optional)

###
public solace.MessageCacheStatus getCacheStatus ( )

Gets the cache status of this message.

#### Return Value

solace.MessageCacheStatus | The cache status of this message. The status will be MessageCacheStatus.LIVE unless the message was returned in a reply to a cache request. (Optional)

###
public String getCorrelationId ( )

Gets the correlation ID. The message Correlation Id is carried in the Solace message headers unmodified by the API and the Solace Message Router. This field may be used for peer-to-peer message synchronization and is commonly used for correlating a request to a reply. See solace.Session#sendRequest.

#### Return Value

String | The correlation ID associated with the message. (Optional)

###
public Object getCorrelationKey ( )

Gets the correlation Key. A correlation key is used to correlate a message with its acknowledgement or rejection. The correlation key is an object that is passed back to the client during the router acknowledgement or rejection.

The correlation key is a local reference used by applications generating Guaranteed messages. Messages that are sent in either solace.MessageDeliveryModeType.PERSISTENT or solace.MessageDeliveryModeType.NON_PERSISTENT mode may set the correlation key.

#### Return Value

Object | The correlation Key associated with the message, or `null`, if unset. (Optional)

###
public solace.MessageDeliveryModeType getDeliveryMode ( )

Gets the delivery mode of the message.

#### Return Value

solace.MessageDeliveryModeType | representing the delivery mode of the message.

###
public Destination getDestination ( )

Gets the destination to which the message was published.

#### Return Value

Destination | The destination to which a message was published. (Optional)

###
public Number getGMExpiration ( )

#### Return Value

Number | The Guaranteed Message expiration value. The expiration time is the UTC time (that is, the number of milliseconds from midnight January 1, 1970 UTC) when the message is to expire. (Optional)

###
public Long getGuaranteedMessageId ( )

Returns the Guaranteed Message MessageID for this message.

#### Return Value

Long | The Guaranteed Message MessageID assigned to this message by the router. (Optional)

###
public solace.MessageConsumer getMessageConsumer ( )

#### Return Value

solace.MessageConsumer | The associated Message Consumer, if received by a consumer (Optional)

###
public Number getPriority ( )

Gets the Message Priority Parameter (JMS Priority) value for the message. Numerical values between 0 and 255 are valid return values, undefined means the parameter is not present.

If destination queues and topic endpoints for this message are configured to respect message priority, the values 0 through 9 can be used to affect the priority of delivery to consumers of those queues or topic endpoints. For the purposes of prioritized message delivery, values larger than 9 are treated the same as 9.

#### Return Value

Number | The Message Priority Parameter value. (Optional)

###
public Number getReceiverTimestamp ( )

Gets the receive timestamp (in milliseconds, from midnight, January 1, 1970 UTC).

#### Return Value

Number | The receive timestamp, if set. (Optional)

###
public solace.Destination getReplyTo ( )

Gets the replyTo destination

#### Return Value

solace.Destination | The value of the replyTo destination, if set. (Optional)

###
public SDTField | null getSdtContainer ( )

Gets the message's structured data container, if this is a structured data message.

#### Return Value

SDTField | null | A field with a payload of {String}, SDTMapContainer, or SDTStreamContainer if one was set in the message; otherwise, null.

###
public String getSenderId ( )

Returns the Sender's ID.

#### Return Value

String | The Sender's ID, if set. (Optional)

###
public Number getSenderTimestamp ( )

Gets the send timestamp (in milliseconds, from midnight, January 1, 1970 UTC).

#### Return Value

Number | The send timestamp, if set. (Optional)

###
public Number getSequenceNumber ( )

Gets the sequence number.

This is an application-defined field, see `solace.Message#setSequenceNumber()`.

#### Return Value

Number | The sequence number, if set (Optional)

###
public Number getTimeToLive ( )

#### Return Value

Number | The Guaranteed Message TTL, in milliseconds.

###
public Long getTopicSequenceNumber ( )

Returns the Topic Sequence Number. If there is no topic sequence number undefined is returned.

#### Return Value

Long | The Topic Sequence number assigned to this message by the Message Router. (Optional)

###
public solace.MessageType getType ( )

Gets the payload type (solace.MessageType) of the message. A message has a structured payload if one was attached via solace.Message#setSdtContainer otherwise if the payload is attached via Message@setBinaryAttachment then it is unstructured ((@link solace.MessageType#BINARY})

#### Return Value

solace.MessageType | The structured payload type.

###
public solace.MessageUserCosType getUserCos ( )

Gets the Class of Service (CoS) value for the message. The Class of Service has different semantics for direct and guaranteed messages.

For messages published with solace.MessageDeliveryModeType.DIRECT, the class of service selects the weighted round-robin delivery queue when the message is forwarded to a consumer. solace.MessageUserCosType.COS1 are the lowest priority messages and will use the Solace Message Router D-1 delivery queues.

For messages published as guaranteed messages (solace.MessageDeliveryModeType.PERSISTENT or solace.solace.MessageDeliveryModeType.NON_PERSISTENT), messages published with solace.MessageUserCosType.COS1 can be rejected by the Solace Message Router if that message would cause any queue or topic-endpoint to exceed its configured low-priority-max-msg-count.

#### Return Value

solace.MessageUserCosType | The COS value.

###
public String getUserData ( )

Gets the user data part of the message.

#### Return Value

String | The user data part of the message, if set.

###
public solace.SDTMapContainer getUserPropertyMap ( )

Gets the user property map carried in the message binary metadata.

#### Return Value

solace.SDTMapContainer | The user properties map, if set. (Optional)

###
public String getXmlContent ( )

Gets the XML content part of the message. Notice that the content is encoded as UTF-8 characters, it needs to be decoded as JavaScript surrogate pair: decodeURIComponent(escape(value))

#### Return Value

String | The XML content part of the message, if set. (Optional)

###
public String getXmlContentDecoded ( )

Gets the XML content part of the message decoded from UTF-8 encoding of the characters.

#### Return Value

String | The XML content part of the message. Returns `null` if not present. (Optional)

###
public String getXmlMetadata ( )

Gets the message's XML metadata section.

#### Return Value

String | The XML metadata, if set. (Optional)

###
public Boolean isAcknowledgeImmediately ( )

Test if the Acknowledge Immediately message property is set or not. When the Acknowledge Immediately property is set to true on an outgoing Guaranteed Message, it indicates that the Solace Message Router should Acknowledge this message immediately upon receipt.

This property, when set by a publisher, may or may not be removed by the Solace Message Router prior to delivery to a consumer, so message consumers must not expect the property value indicates how the message was originally published

#### Return Value

Boolean | Whether this message was set to acknowledge immediately.

###
public Boolean isDeliverToOne ( )

Gets whether the message is configured for delivering to one client only.

#### Return Value

Boolean | indicates whether the message is configured for delivering to one client only.

###
public Boolean isDiscardIndication ( )

Indicates whether one or more messages have been discarded prior to the current message. This indicates congestion discards only and is not affected by message eliding.

#### Return Value

Boolean | Returns true if one or more messages have been discarded prior to the current message; otherwise, it returns false.

###
public Boolean isDMQEligible ( )

#### Return Value

Boolean | Whether this message is Guaranteed Message DMQ eligible

###
public Boolean isElidingEligible ( )

Returns whether the message is eligible for eliding.

Message eliding enables filtering of data to avoid transmitting every single update to a subscribing client.

This property does not indicate whether the message was elided.

#### Return Value

Boolean | indicates whether the message is eligible for eliding.

###
public Boolean isRedelivered ( )

Indicates whether the message has been marked as redelivered by the Solace Message Router.

#### Return Value

Boolean | Indicates whether the redelivered flag is set.

###
public Boolean isReplyMessage ( )

Returns whether the message's reply field is set, indicating that this message is a reply to a previous request. See solace.Session#sendRequest.

#### Return Value

Boolean | Indicates the state of the reply field.

###
public void reset ( )

Releases all memory associated with this message. All values are reinitialized to defaults. The message is no longer associated with any session or consumer.

#### Return Value

void |

###
public void setAcknowledgeImmediately ( Boolean value )

Set the optional Acknoweledge Immediately message property. When the Acknowledge Immediately property is set to true on an outgoing Guaranteed Message, it indicates that the Solace Message Router should acknoweledge this message immediately upon receipt. By default the property is set to false on newly created messages.

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 expect the property value indicates how the message was originally published. Therefore if a received message is forwarded by the application, the Acknowledge Immediately property should be explicitly set to the desired value (true or false).

Setting this property on an outgoing direct message has no effect.

#### Parameters

Boolean | value Whether to acknowledge this message immediately.

#### Return Value

void |

###
public void setApplicationMessageId ( String value )

Sets the application-provided message ID.

#### Parameters

String | value The new value for the application-provided message ID. (Optional)

#### Return Value

void |

###
public void setApplicationMessageType ( String value )

Sets the application message type. This value is used by applications only, and is passed through the API and Solace Message Router untouched.

#### Parameters

String | value The application message type. (Optional)

#### Return Value

void |

###
public void setAsReplyMessage ( Boolean value )

Sets the reply field of the message.

#### Parameters

Boolean | value Sets whether to flag the message as a reply.

#### Return Value

void |

###
public void setBinaryAttachment ( String value )

Sets the binary attachment part of the message. The binary attachment must be a string, wherein each character has a code in the range 0-255 representing exactly one byte in the attachment. When this method is used, the message payload type is solace.MessageType#BINARY See {solace.Message#getType}.

Applications may set the binary attachment to NULL or undefined to remove the binary attachment and create a message with no payload.

#### Parameters

String | value Sets the binary attachment part of the message. (Optional)

#### Return Value

void |

###
public void setCorrelationId ( String value )

Sets the correlation ID. The message Correlation Id is carried in the Solace message headers unmodified by the API and the Solace Message Router. This field may be used for peer-to-peer message synchronization and is commonly used for correlating a request to a reply. See solace.session#sendRequest.

#### Parameters

String | value The correlation ID to associate with the message. (Optional)

#### Return Value

void |

###
public void setCorrelationKey ( Object value )

Sets the correlation Key. A correlation key is used to correlate a message with its acknowledgement or rejection. The correlation key is an object that is passed back to the client during the router acknowledgement or rejection.

The correlation key is a local reference used by applications generating Guaranteed Messages. Messages that are sent in either solace.MessageDeliveryModeType.PERSISTENT or solace.MessageDeliveryModeType.NON_PERSISTENT mode may set the correlation key. If this method is used, the correlation information is returned when the solace.SessionEventCode#event:ACKNOWLEDGED_MESSAGE event is later received for an acknowledged message or when the solace.SessionEventCode#event:REJECTED_MESSAGE_ERROR is received for a rejected message.

The API only maintains a reference to the passed object. If the application requires the contents are unmodified for proper correlation, then it is the application's responsibility to ensure the contents of the object are not modified.

Important: The Correlation Key is not included in the transmitted message and is only used with the local API

#### Parameters

Object | value The correlation Key to associate with the message.

#### Return Value

void |

###
public void setDeliverToOne ( Boolean value )

Sets whether the message is configured for delivering to one client only.

#### Parameters

Boolean | value whether the message is configured for delivering to one client only.

#### Return Value

void |

###
public void setDeliveryMode ( solace.MessageDeliveryModeType value )

Sets the delivery mode of the message.

#### Parameters

solace.MessageDeliveryModeType | value The message delivery mode.

#### Return Value

void |

###
public void setDestination ( Destination value )

Sets the destination (solace.DestinationType#topic or solace.DestinationType#queue) to publish the message to.

#### Parameters

Destination | value The destination to publish the message to.

#### Return Value

void |

###
public void setDMQEligible ( Boolean value )

#### Parameters

Boolean | value The new value for Guaranteed Message DMQ (Dead Message Queue) Eligible. When this property is set, when the message expires in the network the message is saved on a appliance dead message queue. Otherwise the expired message is discarded. See solace.Message#setTimeToLive.

#### Return Value

void |

###
public void setElidingEligible ( Boolean value )

Sets whether the message is eligible for eliding.

Message eliding enables filtering of data to avoid transmitting every single update to a subscribing client.

This property does not indicate whether the message was elided.

#### Parameters

Boolean | value sets whether the message is eligible for eliding.

#### Return Value

void |

###
public void setGMExpiration ( Number value )

Set the expiration time field. The expiration time is the UTC time (that is, the number of milliseconds from midnight January 1, 1970 UTC) when the message is to expire. The expiration time is carried in the message when set to a non-zero value. Expiration time is not included when this value is set to zero or undefined

The message expiration time is carried to clients that receive the message unmodified and does not effect the life cycle of the message. Use solace.Message#setTimeToLive to enforce message expiry in the network.

#### Parameters

Number | value The new Guaranteed Message expiration value (Optional)

#### Return Value

void |

###
public void setPriority ( Number value )

Sets the Message Priority Parameter (JMS Priority) value for the message. Numerical values between 0 and 255 are accepted, use undefined to unset.

If destination queues and topic endpoints for this message are configured to respect message priority, the values 0 through 9 can be used to affect the priority of delivery to consumers of those queues or topic endpoints. For the purposes of prioritized message delivery, values larger than 9 are treated the same as 9.

#### Parameters

Number | value The priority value. (Optional)

#### Return Value

void |

###
public void setReplyTo ( solace.Destination value )

Sets the replyTo destination

#### Parameters

solace.Destination | value The replyTo destination.

#### Return Value

void |

###
public void setSdtContainer ( solace.SDTField container )

Makes this message a strutured data message by assigning it a structured data type (SDT) container payload (such as a solace.SDTMapContainer, solace.SDTStreamContainer or a solace.SDTFieldType.String, which is transported in the binary attachment field.

Assigning a SDT container updates the message's Type property to the appropriate value.

The container argument must be a solace.SDTField with a type of solace.SDTFieldType.MAP, solace.SDTFieldType.STREAM, or solace.SDTFieldType.STRING.

#### Parameters

solace.SDTField | container The SDTField container to send in this message. (Optional)

#### Return Value

void |

###
public void setSenderId ( String value )

Sets the Sender ID for the message

#### Parameters

String | value The Sender ID for the message.

#### Return Value

void |

###
public void setSenderTimestamp ( Number value )

Sets the send timestamp (in milliseconds, from midnight, January 1, 1970 UTC). This field can be generated automatically during message publishing, but it will not be generated if previously set to a non-null value by this method. See solace.SessionProperties#generateSendTimestamps.

An application that publishes the same solace.Messsage multiple times and also wants generted timestamps on each messages, should set the sender timestamp to undefined after each call to solace.Session#send.

#### Parameters

Number | value The value to set as the send timestamp. (Optional)

#### Return Value

void |

###
public void setSequenceNumber ( Number value )

Sets the application-defined sequence number. If the sequence number is not set, or set to undefined, and solace.SessionProperties#generateSequenceNumber is true, then a sequence number is automatically generated for each sent message.

#### Parameters

Number | value The sequence number. (Optional)

#### Return Value

void |

###
public void setTimeToLive ( Number value )

#### Parameters

Number | value The Guaranteed Message TTL to set, in milliseconds. The time to live is the number of milliseconds the message may be stored on the Solace Message Router before the message is discarded or moved to a Dead Message Queue. See solace.Message.setDMQEligible. Setting the Time To Live to zero disables TTL for the message. 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. The maxium allowed time to live is 3.1536E11 (315360000000) which is approximately 10 years.

#### Return Value

void |

###
public void setUserCos ( solace.MessageUserCosType value )

Sets the Class of Service (CoS) value for the message.

The Class of Service has different semantics for direct and guaranteed messages.

For messages published with solace.MessageDeliveryModeType.DIRECT, the class of service selects the weighted round-robin delivery queue when the message is forwarded to a consumer. solace.MessageUserCosType#COS1 are the lowest priority messages and will use the Solace Message Router D-1 delivery queues.

For messages published as guaranteed messages (solace.MessageDeliveryModeType.PERSISTENT or solace.solace.MessageDeliveryModeType.NON_PERSISTENT), messages published with solace.MessageUserCosType#COS1 can be rejected by the Solace Message Router if that message would cause any queue or topic-endpoint to exceed its configured low-priority-max-msg-count.

#### Parameters

solace.MessageUserCosType | value The COS value.

#### Return Value

void |

###
public void setUserData ( String value )

Sets the user data part of the message.

#### Parameters

String | value The user data part of the message.

#### Return Value

void |

###
public void setUserPropertyMap ( SDTMapContainer value )

Allows users to specify their own user properties to be carried in the message binary metadata separate from the payload.

#### Parameters

SDTMapContainer | value The user property map. (Optional)

#### Return Value

void |

###
public void setXmlContent ( String value )

Sets the XML content part of the message. The content is encoded by replacing each instance of certain characters by one, two, three, or four escape sequences representing the UTF-8 encoding of the character.

#### Parameters

String | value The XML content part of the message.

#### Return Value

void |

###
public void setXmlMetadata ( String value )

Sets the message's XML metadata section.

#### Parameters

String | value The XML metadata.

#### Return Value

void |