Managing Messages in the PubSub+ Messaging APIs

The following sections discuss how you can manage messages when you use the PubSub+ messaging APIs.

Getting Message Properties

A client can obtain message properties from a created message before it is published or from a message the API receives from the event broker.

For a complete list of message properties that can be retrieved, see the appropriate API in the PubSub+ Messaging APIs section.

Some message properties, such as expiration, TTL and dead message queue eligibility, are only valid when used with guaranteed messages. See the relevant API reference documentation for more information.

To Get Message Properties
PubSub+ Messaging API Use

Java RTO

All MessageHandle.get*() methods. For example:

  • MessageHandle.getApplicationMessageType()

  • MessageHandle.getDeliveryCount()

  • MessageHandle.getSenderId()

For a complete list of methods, see the PubSub+ Messaging API Java RTO reference.

C

All solClient_msg_get*(...)functions. For example:

  • solClient_msg_getApplicationMsgType (solClient_opaqueMsg_pt msg_p, const char **msgType_p)

  • solClient_msg_getDeliveryMode (solClient_opaqueMsg_pt msg_p, solClient_uint32_t *mode_p)

  • solClient_msg_getSenderId (solClient_opaqueMsg_pt msg_p, const char **buf_p)

For a complete list of methods, see the PubSub+ Messaging API C reference.

.NET

All IMessage.Get*() methods. For example:

  • IMessage.GetBinaryAttachment()

  • IMessage.GetDestinationTopicSuffix()

  • IMessage.GetUserData()

For a complete list of methods, see the PubSub+ Messaging API .NET reference.

JavaScript and Node.js

All solace.Message.get*() functions. For example:

Examples:

  • solace.Message.getApplicationMessageType ( )

  • solace.Message.getDeliveryMode ( )

  • solace.Message.getSenderId ( )

For a complete list of methods, see the PubSub+ Messaging API JavaScript reference.

Setting Message Properties

A client can set message properties on a created message before it is published or on a message the API receives from the event broker.

For a complete list of message properties that can be set, see the appropriate API in the PubSub+ Messaging APIs section.

Some message properties, such as expiration, TTL and dead message queue eligibility, are only valid when used with guaranteed messages. See the relevant API reference documentation for more information.

To set message properties
PubSub+ Messaging API Use

Java RTO

All MessageHandle.set*() methods. For example:

  • MessageHandle.setApplicationMessageType(java.lang.String appMsgType)

  • MessageHandle.setCorrelationId(java.lang.String correlationId)

  • MessageHandle.setSenderId(java.lang.String senderId)

For a complete list of methods, see the PubSub+ Messaging API Java RTO reference.

C

All solClient_msg_set*() functions. For example:

  • solClient_msg_setApplicationMsgType (solClient_opaqueMsg_pt msg_p, const char *msgType)

  • solClient_msg_setDeliveryMode (solClient_opaqueMsg_pt msg_p, solClient_uint32_t mode)

  • solClient_msg_setSenderId (solClient_opaqueMsg_pt msg_p, const char *buf_p)

For a complete list of methods, see the PubSub+ Messaging API C reference.

.NET

All IMessage.Set*() methods. For example:

  • IMessage.SetBinaryAttachment (sbyte[] binaryAttachment)

  • IMessage.SetUserData (sbyte[] userData)

  • IMessage.SetXmlContent (sbyte[] xmlContent)

For a complete list of methods, see the PubSub+ Messaging API .NET reference.

JavaScript and Node.js

All solace.Message.set*() functions. For example:

  • solace.Message.setApplicationMessageType ( String value )

  • solace.Message.setDeliveryMode ( solace.MessageDeliveryModeType value )

  • solace.Message.setSenderId ( String value )

For a complete list of methods, see the PubSub+ Messaging API JavaScript reference.

Duplicating Messages

When using the C API, a client can duplicate a message buffer, which allocates a new message that references the same data as the original. You can duplicate a created message or a received message.

The data is reference counted to indicate that two message buffers have pointers to the data.

To Duplicate Messages
PubSub+ Messaging API Use

Java RTO

Not applicable

C

solClient_msg_dup(...)

.NET

Not applicable

JavaScript and Node.js

Not applicable

Displaying Messages

You can use the message dump utility to display the contents of a message in a human‑readable form. This utility method or function is provided as a programming aid to facilitate the development and testing of messaging applications. You can display the contents of a created message or a received message.

To Display Message Contents
PubSub+ Messaging API Use

Java RTO

MessageHandle.dump(...)

C

solClient_msg_dump(...)

.NET

IMessage.Dump()

Javascript and Node.js

Solace.Message.dump()

The format of the generated output is:

<field>:                              <value>

For example, a message part, such as a message header field like SenderId, is displayed as:

SenderId:                             mySenderID

If a message part is present in the message, but it contains NULL or an empty string, the field is displayed (in this case, SenderID:) but no value is present. If a message part is not present, then no output is generated for that part. For example, if there is no SenderId header field, then no SenderId field or value is generated.

Freeing Messages

When using the Java RTO, C, or .NET APIs, a client should free a message when it is finished it so that the memory allocated to the message is freed. Clients should free outbound messages after publishing them, and free inbound messages after they finish processing them.

When one of the calls listed below successfully return, the memory that was referenced by the freed message is no longer valid.

To Free Messages
PubSub+ Messaging API Use

Java RTO

A client may call MessageHandle.takeRxMessage() to take ownership of messages received in a callback. When this happens, the client must free the message when it is no longer needed.

MessageHandle.destroy()

C

In general, a client does not need to free any message received from the C API in a callback. However, to take ownership of messages received in a callback, a client can return SOLCLIENT_CALLBACK_TAKEMSG to the API. In this latter case, a client must free the message when it no longer needs it.

solClient_msg_free(solClient_opaqueMsg_pt * msg_p)

.NET

Dispose()

JavaScript and Node.js

Not applicable