Creating Messages

Messages are explicitly created by client applications when publishing and are implicitly created by the messaging APIs on matching message delivery.

JCSMP

Creates an object of the specified class to encapsulate a message.

Java RTO API

Creates an object within the native library and provides a handle to the application.

C API

Allocates a memory buffer from heap storage to store and send and receive messages.

.NET API

Creates an IMessage object to encapsulate a message.

JavaScript and Node.js APIs

Creates a solace.Message object to encapsulate a message.

When creating messages, the following factors should be considered:

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 (refer to Sending Direct Messages).

    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
PubSub+ Messaging API Call

JCSMP

JCSMPFactory.createMessage(...)

Creates an object of the specified class (refer to Java Message Classes) to encapsulate a message.

Java RTO

Solclient.createMessageForHandle(...)

Allocates a new message that is bound to the given unbound MessageHandle.

C

solClient_msg_alloc(...)

Allocates a memory buffer from heap storage to store and send and receive messages.

.NET

  • ContextFactory.CreateMessage()

  • ISession.CreateMessage()

    Creates an IMessage object to encapsulate a message.

JavaScript and Node.js

solace.SolclientFactory.createMessage()

Creates a solace.Message object to encapsulate a message.

Related Samples

For an example of how to create Session‑independent messages, refer to the ADPubAck sample for JCSMP, the DirectPubSub samples for the Java RTO, C, and .NET APIs, and the TopicPublisher sample for the JavaScript and Node.js APIs.

To Create Session-Dependent Messages
PubSub+ Messaging API Call

JCSMP

producer.createBytesXMLMessage()

producer.createBytesMessage()

producer.createMapMessage()

producer.createStreamMessage()

producer.createTextMessage()

producer.createXMLContentMessage()

Java RTO

Not applicable

C

Not applicable

.NET

Not applicable

JavaScript and Node.js

Not applicable

Message Types

The messaging APIs support different message types as defined by the message payloads.

JCSMP

For programmers’ convenience, the following type‑safe message types/classes are provided.

Java 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.

StreamMessage

A structured class that can be used to send a message that contains a SDT stream. Refer to Using Structured Data.

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.

Java RTO API

The following message types are provided for Java RTO.

Java RTO Message Classes

Message Class Description

BytesMessage

A structured class that can be used to send a message that contains a stream of uninterpreted bytes in a binary attachment.

C, JavaScript, Node.js, and .NET APIs

These APIs define only a single message type. In these APIs, a message payload can contain any combination of the message types and classes listed above by way of message helper functions.

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.

The Java RTO API does not include a reset method. If a message is destroyed using MessageHandle.destroy(), you must call createMessageForHandle again to allocate a new message for the now-unbound handle.

To Reset a Message
PubSub+ Messaging API Call

JCSMP

XMLMessage.reset()

Java RTO

Not applicable

C

solClient_msg_reset(...)

.NET

IMessage.reset()

JavaScript and Node.js

solace.Message.reset()