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.

The PubSub+ Java RTO API does not support the use of structured data types.

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

  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” or 1.
  2. Returns Boolean 0 or 1 if the integer byte is non‑zero.
  3. 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.
  4. When using the C API, if the string length is 1, getChar() returns the single character in the string.
  5. Any field can be skipped by reading it as a NULL.