Creating Messages

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

Solace Java RTO API

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

Solace C API

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

Solace .NET API

Creates an IMessage object to encapsulate a message.

Solace JavaScript API and Solace Node.js API

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

    The Solace JCSMP API 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 (see Sending Direct Messages).

To Create Session-Independent Messages
Solace Messaging API Call

Solace Java RTO API

Solclient.createMessageForHandle(...)

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

Solace C API

solClient_msg_alloc(...)

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

Solace .NET API

  • ContextFactory.CreateMessage()

  • ISession.CreateMessage()

    Creates an IMessage object to encapsulate a message.

Solace JavaScript API and Solace Node.js API

solace.SolclientFactory.createMessage()

Creates a solace.Message object to encapsulate a message.

Related Samples

For an example of how to create session‑independent messages, see the DirectPubSub samples for the Solace Java RTO API, Solace C API, and Solace .NET API, and the TopicPublisher sample for the Solace JavaScript API and Solace Node.js API.

To Create Session-Dependent Messages
Solace Messaging API Call

Solace Java RTO API

Not applicable

Solace C API

Not applicable

Solace .NET API

Not applicable

Solace JavaScript API and Solace Node.js API

Not applicable

Message Types

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

Solace Java RTO API

The following message types are provided for Solace Java RTO API.

Solace Java RTO API 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.

Solace C API, Solace JavaScript API, Solace Node.js API, and Solace .NET API

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 Solace 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
Solace Messaging API Call

Solace Java RTO API

Not applicable

Solace C API

solClient_msg_reset(...)

Solace .NET API

IMessage.reset()

Solace JavaScript API and Solace Node.js API

solace.Message.reset()