Using Structured Data in the PubSub+ JCSMP API
SDTs are structured, language-independent, and architecture-independent data types. SDTs can be used in messages to facilitate the exchange of binary data in a heterogeneous network that has clients that use different hardware architectures and programming languages.
The PubSub+ JCSMP API supports the ability to carry structured data in the binary attachment of the message or as user-defined message header fields.
All structured data must be added to or read from complex data structures (maps and streams), generically called containers. Containers themselves are structured data types. Therefore, a map or stream can contain simple SDT types or other maps or streams.
Related Samples
- For an example of how to work with SDTs when publishing and receiving messages, see the RequestReply samples (
RRDirectRequester, RRDirectReplier, RRGuaranteedRequester, and RRGuaranteedReplier) in the Solace Developer Hub. - For an example of how to add SDT payloads to a message, see the
SDTPubSubMsgIndeporSDTPubSubMsgDepsamples in the Solace Developer Hub..- In the
SDTPubSubMsgIndepsample, SDT containers are created using application memory, allowed by the PubSub+ JCSMP API. - For more information on creating SDT containers with application memory, see the Creating Structured Data Maps and Streams in the PubSub+ JCSMP API.
- In the
Supported Structured Data Types
The PubSub+ Messaging APIs support the following SDTs.
| Data Type | JCSMP | C API | .NET API | JavaScript and Node.js API |
|---|---|---|---|---|
|
Boolean |
java.lang.Boolean |
solClient_bool_t |
System.Boolean |
boolean |
|
8-bit signed integer |
java.lang.Byte |
solClient_int8_t |
System.Int16 |
number |
|
8-bit unsigned integer |
Not applicable |
solClient_uint8_t |
System.Byte |
number |
|
16-bit signed integer |
java.lang.Short |
solClient_int16_t |
System.Int16 |
number |
|
16-bit unsigned integer |
Not applicable |
solClient_uint16_t |
System.Int16 |
number |
|
32-bit signed integer |
java.lang.Integer |
solClient_int32_t |
System.Int32 |
number |
|
32-bit unsigned integer |
Not applicable |
solClient_uint32_t |
System.Int64 |
number |
|
64-bit signed integer |
java.lang.Long |
solClient_int64_t |
Int64 |
number Supports 48-bit integers (range: 0 to 2^48-1). When encoding, only the lower 48 bits are considered significant. |
|
64-bit unsigned integer |
Not applicable |
solClient_uint64_t |
Int64 (when there is no loss of precision) |
number Supports 48-bit integers (range: 0 to 2^48-1). When encoding, only the lower 48 bits are considered significant. |
|
32-bit floating point |
float |
float |
float |
number Single-precision float. |
|
64-bit floating point |
double |
double |
double |
number Double-precision float. |
|
character (16-bit unicode) |
java.lang.Character |
solClient_wchar_t |
System.Char |
string Single character. |
|
byte array |
byte[] |
solClient_uint8_t |
byte[] |
Int8Array |
|
string (UTF-8 encoded) |
java.lang.String |
const char * |
System.string |
string |
|
destination (Topic or Queue physical names) |
com.solacesystems. |
solClient_ |
IDestination |
solace.Destination |
|
SMF message |
com.solacesystems. |
solclient_uint8_t * |
IMessage |
solace.Message |
|
Map (a structured data container of a sequence of named fields. Each field must be one of the supported data types.) |
SDTMap |
solClient_ |
IMapContainer |
solace.SDTMapContainer |
|
Stream (a structured data container of a sequence of unnamed fields. Each field must be one of the supported data types.) |
SDTStream |
solClient_ |
IStreamContainer |
solace.SDTStreamContainer |
|
Unknown (a validly formatted but unrecognized data type) |
com.solacesystems. |
solClient_uint8_t |
IUnknownSDTField |
Using solace.SDTFieldType.UNKNOWN |
|
Null or unspecified |
null |
Supports add and get operations for the NULL data in structured data. By definition there is no ‘C’ type or size for NULL. |
null |
null |
Structured Data Type Conversion
The table below lists how the supported SDTs in a received message can be read by the JCSMP, JavaScript and Node.js APIs.
| Read As | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Bool | Byte | Byte[ ] | Char | Dest | Dbl | Float | Int | Long | Map | Msg | Short | Stream | String | ||
|
Written As |
Bool |
✓ |
|
|
|
|
|
|
|
|
|
|
|
|
✓ |
|
Byte |
|
✓ |
|
|
|
|
|
✓ |
✓ |
|
|
✓ |
|
✓ |
|
|
Byte[ ] |
|
|
✓ |
|
|
|
|
|
|
|
|
|
|
|
|
|
Char |
|
|
|
✓ |
|
|
|
|
|
|
|
|
|
✓ |
|
|
Dest |
|
|
|
|
✓ |
|
|
|
|
|
|
|
|
|
|
|
Dbl |
|
|
|
|
|
✓ |
|
|
|
|
|
|
|
✓ |
|
|
Float |
|
|
|
|
|
✓ |
✓ |
|
|
|
|
|
|
✓ |
|
|
Int |
|
2 |
|
|
|
|
|
✓ |
✓ |
|
|
2 |
|
✓ |
|
|
Long |
|
2 |
|
|
|
|
|
2 |
✓ |
|
|
2 |
|
✓ |
|
|
Map |
|
|
|
|
|
|
|
|
|
✓ |
|
|
|
|
|
|
Msg |
|
|
|
|
|
|
|
|
|
|
✓ |
|
|
|
|
|
Short |
|
2 |
|
|
|
|
|
2 |
2 |
|
|
✓ |
|
✓ |
|
|
Stream |
|
|
|
|
|
|
|
|
|
|
|
|
✓ |
|
|
|
String |
1 |
✓ |
|
|
|
✓ |
✓ |
✓ |
✓ |
|
|
✓ |
|
✓ |
|
|
1. Returns a Boolean with a value represented by the specified string. The Boolean returned represents a true value if the string argument is not null and is equal, ignoring case, to the string “true”. 2. If a lossless conversion. |
|||||||||||||||