Creating Messages in the PubSub+ JCSMP API

Messages are explicitly created by client applications when publishing and are implicitly created by the PubSub+ JCSMP API on matching message delivery. The PubSub+ JCSMP API creates an object of the specified class to encapsulate a message.

When creating messages, the following factors should be considered:

• Message Ownership
• Message Types
• Resetting Messages

Message Ownership

When creating messages for publishing, there are two message ownership models:

• Session-independent

  In a session‑independent message ownership model, client applications can reuse messages between send operations. Messages are allocated on demand and are disposed explicitly by client applications when they are done with the messages.

• Session-dependent

  JCSMP also supports a session-dependent message ownership model. In this model, message instances are pre-allocated into a producer message pool; client applications can ‘take’ a message instance from the message pool, populate it, and send it. When the send operation returns, the message instance is automatically reset and ‘put’ back into the message pool by the API. This is done through the Producer interface on the session. Session‑dependent messages cannot be used in a batch send.

  The session-dependent message ownership model is primarily maintained for backwards compatibility with existing applications that use JCSMP. It is recommended that new Java applications use the session‑independent messages. There is no performance penalty for using the session‑independent message ownership model if messages are pre‑allocated and reused, whenever possible.

To create session-independent Messages, use JCSMPFactory.createMessage(...). This method creates an object of the specified class (see JCSMP Message Classes) to encapsulate a message.

For an example of how to create session‑independent messages, see the ADPubAck sample on the Solace Developer Hub.

To Create session-dependent messages, use the following methods:

• producer.createBytesXMLMessage()
• producer.createBytesMessage()
• producer.createMapMessage()
• producer.createStreamMessage()
• producer.createTextMessage()
• producer.createXMLContentMessage()

Message Types

The PubSub+ messaging APIs support different message types as defined by the message payloads. For programmers’ convenience, the following type‑safe message types/classes are provided in the PubSub+ JCSMP API.

JCSMP Message Classes

Message Class	Description
BytesXMLMessage	An unstructured class that can be used to send a message containing an XML data payload.
BytesMessage	A structured class that can be used to send a message that contains a stream of uninterpreted bytes in a binary attachment.
MapMessage	A structured class that can be used to send a message that contains a structured data type (SDT) map. Refer to Using Structured Data in the PubSub+ JCSMP API.
StreamMessage	A structured class that can be used to send a message that contains a SDT stream. Refer to Using Structured Data in the PubSub+ JCSMP API.
TextMessage	A structured class that can be used to send a message that contains text.
XMLContentMessage	A structured class that can be used to send a message that contains XML data.

Resetting Messages

When reusing a message in the Session-independent message ownership model, you can release all memory associated with a message buffer so that the message buffer is reset to its original state (that is, as if it has just been allocated). All fields are reset to their default values.

To reset a message, use XMLMessage.reset().