JSON topics

A topic that provides data in JSON format. The data is transmitted in a binary form for increased efficiency and can be transmitted as a structural delta to reduce the amount of data sent. JSON topics are stateful: each topic stores a JSON value the Diffusion™ server .

Why use a JavaScript Object Notation (JSON) topic?

JSON is a human-readable, industry-standard format for your data. JSON is natively supported by JavaScript^® and there are third-party libraries available for other platforms. For more information about JSON , see http://www.json.org/.

A JSON topic enables multiple fields to be maintained in the same topic as part of a composite data type. All updates made at the same time to parts of a JSON topic are sent out to the client together. This enables a set of parts to be treated as a transactional group.

Deltas of change are calculated at the Diffusion server such that only those parts that have changed since the last update are sent out to the subscribed clients. These structural deltas ensure that the minimum amount of data is sent to clients.

The current value of the topic is cached on the client. When deltas are sent, the client can automatically apply these deltas to the value to calculate the new value.

As of Diffusion 6.4, JSON topics support partial updates using the JSON Patch standard. This enables a client to update part of the data within a topic, without needing to know the full value. In addition, a partial update can provide performance benefits if the JSON value is large.

If your data structure is too complex to be represented by a topic tree or might make the topic tree structure difficult to manage, it might be more appropriate to represent part of the data structure inside a JSON topic as JSON objects.

The value of the topic is transmitted as Concise Binary Object Representation (CBOR) . For more information about CBOR , see http://cbor.io/.

The value of the topic is accessible both as JSON and CBOR .

Properties of a JSON topic

When you create a JSON topic you can specify the following properties in the topic specification:

PUBLISH_VALUES_ONLY

By default, delta streaming is enabled. If this property is set to true, delta streaming is disabled and all values are published in full.

If there is little or no relationship between one value published to a topic and the next, delta streams will not reduce the amount of data transmitted. For such topics, it is better to set PUBLISH_VALUES_ONLY.

DONT_RETAIN_VALUE

If set to true, the latest value of the topic is not retained by the Diffusion server or the client that publishes it. New clients that subscribe do not receive an initial value. No value will be returned for fetch operations that select the topic.

For time series topics, if DONT_RETAIN_VALUE is set to true, time series events are still retained, but the latest value is not stored separately.

The DONT_RETAIN_VALUE property is useful for applications like a feed of news items, or for values that are only valid at the moment of publication. You can combine this with VALIDATE_VALUES.

Using DONT_RETAIN_VALUE reduces the topic memory footprint, but disables delta streaming. Using an update stream will send complete values to the server, instead of deltas. Disabling delta streaming is likely to increase the bandwidth used unless subsequent values are unrelated.

This property replaces the obsolete stateless topic type which was removed in Diffusion 6.2.

TIDY_ON_UNSUBSCRIBE

If set to true, when a session unsubscribes from the topic, any updates for the topic that are still queued for the session are removed.

There is a performance overhead to using this option as the client queue must be scanned to find topic updates to remove, however it may prove useful for preventing unwanted data being sent to sessions. This property is disabled by default.

VALIDATE_VALUES

If set to true, the topic rejects updates that would create invalid instances of the topic's data type.

If set to anything other than true, no validation is performed and all values are streamed to subscribing clients whether they are valid data or not.

Validation has a performance overhead and is disabled by default.

Note: If validation is disabled and the value provided is not valid, the client might produce errors or other unexpected behavior. The exact error varies depending on the client platform. To avoid this, use the client-side validation method provided by the Diffusion API.

CONFLATION

Used to set a conflation policy for the topic. Conflation can merge or discard topic updates to reduce server memory and network data usage.

The supported values are:

off
conflate
unsubscribe
always

The default is "conflate".

Note: Time series topics do not allow a conflation policy of 'conflate' or 'always'. They default to 'off'. You can set a conflation policy of 'unsubscribe'.

See Using conflation for details of the policies.

OWNER

Used to set a security principal as the owner of the topic. The principal receives READ_TOPIC, MODIFY_TOPIC and UPDATE_TOPIC privileges.

The format of the property value is:

$Principal is "name"

where name is the name of the principal.

REMOVAL

Used to set a topic removal policy.

The property is an expression which defines the conditions which will trigger automatic removal of the topic or of a set of topics specified with an optional selector.

See Removing topics automatically for details of the expression format.

PERSISTENT

Used to disable persistence for a topic.

If set to "false", the topic will not be persisted, even if persistence is enabled for the server.

Considerations when using a JSON topic

It is possible to store any data in a JSON topic, even if it is not valid JSON. However, this can cause problems when clients receive unexpected values.

You can validate JSON in the client, or on the server by setting VALIDATE_VALUES to true.

All languages parse JSON as text. Only JavaScript has native support for parsing JSON. Other languages must use third-party libraries. The JavaScript clients provide facilities for converting JSON text to and from a Diffusion JSON value.

Only JSON topics support partial updates.

The topic view expansion feature can only be used with JSON topics.

Diffusion JSON values are transmitted as a CBOR representation. Applications can also access the CBOR binary data directly, and it is often more efficient to do so than to first convert the data to JSON text. For example, Java™ applications can use the third party Jackson library to map the CBOR data directly to Java objects.