Adding Data Payloads

You can add the following types of payloads to a message:

  • XML content—XML data can be added to the XML content part of a message.
  • Binary content—Binary data can be added to a message as a binary attachment. A message can only contain a single attachment.

    When this attachment is sent through the event broker, it is not processed, transformed, or considered in subscription matching or filtering operations. This provides an efficient means for sending data that does not require processing by the platform before it reaches receiving applications.

    Structured data can also be added as a payload in the binary attachment (refer to Using Structured Data).

  • User Property Map—Structured data can be added to user-defined message header fields.
  • User Data—Up to 36 bytes of application‑specific binary data, known as user data, can be added to the User Data message header field.

The maximum total size permitted for a published Direct message is 64 MiB (67,108,864 bytes). This is an event broker-imposed limit, and it takes into consideration the message header field data, XML metadata, XML payload, and any attachments.

To Add Data Payloads to a Message
PubSub+ Messaging API Data Type To Add Set Through

JCSMP

XML Data

  • setXMLContent(...)

    Sets the XML data payload content for an XMLContentMessage.

  • writeBytes(...)

    Sets the XML data payload content for an unstructured XML message.

Binary Data

writeAttachment(...)

You can also use the structured BytesMessage message class to create a message that contains a data payload in the binary attachment.

User Data

setUserData(...)

MessageProducer does not validate the values of user data.

Java RTO

XML Data

Not applicable

Binary Data

MessageHandle.setBinaryAttachment(...)

User Data

MessageHandle.setUserData(...)

C

XML Data

  • solClient_msg_setXml(...)

    Copies content from a given pointer and size into the XML message part. This uses memory allocated from heap storage.

  • solClient_msg_setXmlPtr(...)

    Sets the contents of the XML message part to a given pointer and size. This references data that already exists in the application; no memory copies are involved.

Binary Data
  • solClient_msg_setBinaryAttachment(...)

    Copies content from a given pointer and size into the binary attachment message part. This uses memory allocated from heap storage.

  • solClient_msg_setBinaryAttachmentPtr(...)

    Set the contents of the binary attachment message part to a given pointer and size. This references data that already exists in the application; no memory copies are involved.

You can also add structured data to the payload in the binary attachment; refer to Using Structured Data.

User Data
  • solClient_msg_setUserData(...)

    Copies content from a given pointer and size into the User Data message part. This uses memory allocated from heap storage.

  • solClient_msg_setUserDataPtr(...)

    Sets the contents of the User Data message part to a given pointer and size. This references data that already exists in the application; no memory copies are involved.

.NET

XML Data

IMessage.XmlContent

Binary Data

IMessage.BinaryAttachment

User Data

IMessage.UserData

JavaScript and Node.js

XML Data

solace.Message.setXmlContent(...)

Binary Data

  • solace.Message.setBinaryAttachment(...)

  • solace.Message.setSdtContainer(...)

    To transport SDT container payload in the binary.

User Data

solace.Message.setUserData(...)

Related Samples

  • For an example of how to add a binary data payload to a message, refer to DirectPubSub for the JCSMP, Java RTO, C, and .NET APIs, and the TopicPublisher sample for the JavaScript and Node.js APIs.
  • For an example of how to add SDT payloads to a message, refer to the SDTPubSubMsgIndep or SDTPubSubMsgDep samples for the JCSMP, Java RTO, C, and .NET APIs, and the BasicRequestor and BasicReplier samples for the JavaScript and Node.js APIs.
    • In the SDTPubSubMsgIndep sample, SDT containers are created using application memory (allowed by the JCSMP, C, and .NET APIs).
    • In the SDTPubSubMsgDep sample, SDT containers are created using API-controlled memory (allowed only by the C and .NET APIs).

    For more information on creating SDT containers with application memory or API-controlled memory, refer to Using Structured Data.