Using Structured Data

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 JCSMP, C, JavaScript, Node.js, and .NET messaging APIs support 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, refer to the RequestReply samples (RRDirectRequester, RRDirectReplier, RRGuaranteedRequester, and RRGuaranteedReplier) for the JCSMP, C, and .NET APIs, and the BasicRequestor and BasicReplier samples 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.
  • 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 Creating Structured Data Maps and Streams.

Supported Structured Data Types

The messaging APIs support the following SDTs.

Supported Structured Data Types

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. jcsmp.Destination	solClient_ destination_t	IDestination	solace.Destination
SMF message	com.solacesystems. jcsmp. RawSMFMessage	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_ opaqueContainer_pt	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_ opaqueContainer_pt	IStreamContainer	solace.SDTStreamContainer
Unknown (a validly formatted but unrecognized data type)	com.solacesystems. jcsmp. SDTUnknownType	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.

Possible Data Type Conversions in JCSMP, JavaScript, and Node.js

	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.

The table below lists how the supported SDTs in a received message can be read by the C and .NET APIs.

Possible Structured Data Type Conversions in C and .NET

	Read As
		Bool	Byte Array	Char	Dest	Dbl	Float	Integer	String	NULL
Written As	Bool	✓						✓
	Byte Array		✓
	Char			✓
	Dest				✓
	Dbl	2				✓
	Float	2					✓
	Integer	2						3
	String	1	✓	4		✓	✓	✓	✓
	NULL	5	5	5	5	5	5	5	5	✓
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” or 1. Returns boolean 0 or 1 if the integer byte is non‑zero. 8, 16, 32, and 64-bit signed and unsigned integers are supported structured data types. A client can receive one type of integer and read it as another as long the conversion will not result in a loss of information. When using the C API, if the string length is 1, getChar() returns the single character in the string. Any field can be skipped by reading it as a NULL.