Expand Collapse
Just a second...

Managing topics

A client can use the TopicControl feature of the Unified API to add and remove topics at the server.

Currently all topics created using a client have a lifespan the same as the Diffusion™ server. The topics remain at the Diffusion server even after the client session that created them has closed unless you explicitly specify that the topic is removed with the session.

Adding topics by initial value

Required permissions: modify_topic

A client can add a topic and define its type by providing an initial value. Diffusion uses the initial value to derive the topic type and to set the initial value of the topic.

The following table lists the topic types derived from different types of provided values:
Value type Topic type Metadata Initial value
JSON JSON Not applicable The supplied value
Binary Binary Not applicable The supplied value
Content created using a builder method Record The metadata of the content is derived from the records and fields in the content with the following assumptions:
  • Numeric values are assumed to be MIntegerString
  • Numeric values that contain a decimal point (.) are assumed to be MDecimalString with a scale equal to the number of places after the decimal point
  • All other values are assumed to be MString
 The supplied content
Content not created using a builder method Single value MString The supplied content as a string
Integer, Long, Short, Byte, BigInteger, AtomicInteger, AtomicLong Single value MIntegerString A value derived from the string representation of the supplied value
BigDecimal Single value MDecimalString with scale from supplied value A value derived from the string representation of the supplied value
Double, Float Single value MDecimalString with scale 2 A value derived from the string representation of the supplied value
Note: We do not recommend using floating point numbers. If used, the number is converted to decimal using half even rounding.
Other Single value MString A string representation of the supplied value

The addTopicFromValue operation is asynchronous and calls back to notify of either successful creation of the topic or failure to create the topic. If the topic add fails at the Diffusion server, the reason for failure is returned.

A client can create topics subordinate to topics created by another client.

Note: It is not currently possible to add new topics under branches of the topic tree that have been created by internal publishers.

Adding topics with topic specifications

Required permissions: modify_topic

Supported platforms: JavaScript®, Android™, Java™

To create a JSON or binary topic, you can either create the topic by defining just the topic type or use the more complex topic specification to specify other attributes of the topic.

You can use the same instance of topic specification to create many topics.

The addTopic operation is asynchronous and calls back to notify of either successful creation of the topic or failure to create the topic. If the topic add fails at the Diffusion server, the reason for failure is returned.

A client can create topics subordinate to topics created by another client.

Note: It is not currently possible to add new topics under branches of the topic tree that have been created by internal publishers.

Adding other topics

Required permissions: modify_topic

For a client to create a topic it must first define the topic details that describe the topic. Builders of topic details can be created using the TopicControl feature.

You can use the same instance of topic details to create many topics. This is recommended when many topics with the same definition are to be created, because caching optimizations occur that prevent complex definitions from being transmitted to the Diffusion server many times.

For some types of topic, setting up metadata is part of the task of describing the topic.

The client can use the TopicControl feature to supply the initial state of the topic to the Diffusion server, as content, when the topic is created.

The addTopic operation is asynchronous and calls back to notify of either successful creation of the topic or failure to create the topic. If the topic add fails at the Diffusion server, the reason for failure is returned. Possible reasons for failure include the following:
  • The topic already exists at the Diffusion server
  • The name of the supplied topic is not valid
  • The supplied details are not valid. This can occur only if properties are supplied.
  • A user-supplied class cannot be found or instantiated. This can occur if you try to create a routing, paged, custom, or service topic and you have defined server-side classes to instantiate the topic.
  • A referenced topic cannot be found
  • Permission to create the topic was denied
  • An error occurred trying to initialize the newly created topic with the supplied content, possibly because it was not validly formatted

A client can create topics subordinate to topics created by another client.

Note: It is not currently possible to add new topics under branches of the topic tree that have been created by internal publishers.

Removing topics

Required permissions: modify_topic

A client can remove topics anywhere in the topic tree. The remove operation takes a topic selector, which enables the client to remove many topics at once.

You can also opt to remove all topics beneath a selected topic path by appending the descendant pattern qualifiers, / and //. For more information, see Topic selectors in the Unified API.

This page last modified: 2017/05/24