Creating Structured Data Maps and Streams

The memory that must be allocated to create maps and streams can either be allocated by the client application to create message-independent maps and streams (see Message-Independent Maps and Streams), or it can be automatically allocated by the API to create message‑dependent maps and streams (see Message-Dependent Maps and Streams).

The Solace .NET API supports both message-independent and message-dependent maps and streams.

Message-Independent Maps and Streams

Typically, a map or stream is created in application memory that is independent of a particular message. This allows a container to be added to other containers or to the binary message parts of more than just one message. Using a message‑independent container can be useful if you want to add it repeatedly to different messages or to existing containers as a common container.

In the Solace .NET API, when a container is created, memory is allocated for it from the heap.

The following sections discuss how to use containers that are message‑independent:

• Creating Structured Data Maps
• Creating Structured Data Streams
• Copying Content from Containers to Messages
• Adding Content from Containers to Messages by Reference
• Adding Containers to Existing Containers

Creating Structured Data Maps

To Create Structured Data Maps

In the Solace .NET API, use:

SDTUtils.CreateMap(...)

Once the application is done with the map, explicitly call Dispose() to ensure that allocated memory is freed.

Creating Structured Data Streams

To Create Structured Data Streams use:

SDTUtils.CreateStream(...) and pass in the maximum size (in bytes) for the stream.

Once the application is done with the stream, explicitly call Dispose() to ensure that allocated memory is freed.

Copying Content from Containers to Messages

To copy data from a container into a message's binary attachment, call the method listed below. Pass in the message the content is for and the container with the content to be copied in.

If a binary attachment is present before the method is called, it is removed before the new data is copied in.

After the method is called, any further changes to the container contents are not propagated to the referenced message.

To Copy Container Content to Messages, use:

SDTUtils.SetSDTContainer(...)

Adding Content from Containers to Messages by Reference

To add data from a map or a stream into a message's binary attachment through a container reference, pass a reference to the message to receive the contents and the container with the contents that are to be added.

If the message already has a binary attachment, it is removed and only the referenced map is transmitted.

This feature is not applicable in the Solace .NET API.

Adding Containers to Existing Containers

To add an existing container to a map or stream, call one of the methods listed below and pass in the parent container and the subcontainers that you want to add to it.

To Add Containers to Existing Containers

In the Solace .NET API, use:

• IMapContainer.AddSDTContainer(...)

• IStreamContainer.AddSDTContainer(...)

Message-Dependent Maps and Streams

In the Solace .NET API, containers can also be created directly in the binary attachment of a message using the memory block managed by the messaging API; the container is then dependent on that particular message and cannot be reused by other messages.

Creating Message-Dependent Maps and Streams

In the Solace .NET API, a client can create a map or stream of structured data directly in the binary attachment of a message. Structured data added in this manner is not created in an application memory-based container that can be reused. However, it does avoid a memory copy operation, and it off-loads the task of memory management from the application so that the messaging API is responsible for managing the memory allocated for the container.

To create message-dependent maps or streams, call one of the methods listed below to create a map or stream directly in the binary attachment of a specific message.

To Create Message-Dependent Maps and Streams

In the Solace .NET API, use:

• SDTUtils.CreateMap(...)

• SDTUtils.CreateStream(...)

When using one of these methods, you must specify the size (in bytes) of the datablock to allocate for the creation of the map or stream.

If a specific datablock size is set, and it is too small for the subsequently created map or stream, a larger datablock is allocated when data is added, and the existing structured data is copied into the new buffer. This reallocation can negatively affect performance.

If you want to use the smallest amount of messaging API memory, set a value of 0 for the size parameter. In this case, the API uses the smallest possible datablock (by default 10,240 bytes) to build the containers. If this is not enough, a reallocation occurs, and all existing data is copied into the new, larger buffer.

Data fields, submaps, and substreams can be created using SDT add methods. Applications that receive messages can also do this before retransmitting or forwarding the data. For a comprehensive list of the available container methods, see the Solace .NET API documentation.