Creating Structured Data Maps and Streams in the PubSub+ JCSMP API

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).

Message-independent maps and streams are available for all of the PubSub+ messaging APIs.

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.

For the PubSub+ JCSMP 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

To create structured data maps, use the following:

  • XMLMessageProducer.createMap()
  • JCSMPFactory.createMap()

Creating Structured Data Streams

To create structured data streams, use the following:

  • XMLMessageProducer.createStream()
  • JCSMPFactory.createStream()

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 call a method or function listed in the table below and 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.

To add content from containers by reference, use the following:

  • MapMessage.setMap(SDTMap map)
  • StreamMessage.setStream(SDTStream stream)

Adding Containers to Existing Containers

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

To add containers to existing containers, use the following:

  • SDTMap.putMap(String key, SDTMap value)—Associates the specified key with the value in the map.
  • SDTMap.putStream(String key, SDTStream value)—Associates the specified key with the value in the map.
  • SDTStream.writeMap(SDTMap value)—Writes a map to a stream.
  • SDTStream.writeStream(SDTStream value)—Writes a stream to a stream.