To subscribe to a topic, a client must have the select_topic permission and the read_topic permission for that topic. For more information, see Permissions.
The rest of this section assumes that the client has the required permissions to
complete the described actions.
The prerequisite conditions for subscribing to a topic are met:
The client selects a set of topics to subscribe to, or that
selection is made on the client's behalf by another client or by a publisher.
A client can
select multiple topics using a topic selector. This subscription
can be to topics that match a particular regular expression or
to topics in a particular branch of the topic tree. For more
information, see Topic selectors.
The selection made by the subscribe request is persistent and is
stored on the Diffusion server. Because selections
are stored, the client can subscribe, pre-emptively, to topics
that do not currently exist.
The topic exists on the Diffusion server.
can be created before or after any subscribe request that
selects it. In both cases, the client that makes the request is
subscribed to the topic when both the selection and the topic
Both prerequisite conditions for a subscription are met and the client is
subscribed to the topic.
The intersection of the topic paths that the
client has selected for subscription and the topics that exist on the Diffusion server defines the list of subscriptions that
client has made.
For each client that connects to the Diffusion server, the Diffusion server stores a separate list of
When the subscription is made, the value of the subscribed topic is sent to
Subsequent updates are sent as values or as deltas, depending
on the topic specification and the nature of the update.
Client handling of data from subscribed topics
When the client makes a subscription to a topic, the value of the topic is
sent to the client.
Subsequent updates are sent as values or as
Values for each subscribed topic are stored in the subscribed topic cache on
The client registers streams against a topic selector. A list of
streams is maintained in the stream registry.
If one or more streams exists that matches a topic, the value for that topic
is received through the matching streams.
Considerations when subscribing
The subscriptions a client has, which are defined by the intersection of the topics
that exist on the Diffusion server with the selections made by the
client, determine what data is sent to the client from the Diffusion server. To reduce the amount of data sent between the Diffusion server and the client, only subscribe to those topics
that the client uses.
The streams a client registers determine what topic values are available for the
client to work with. Adding and removing streams as they are needed by the client
enables your application to access topic values stored in the subscribed topic cache
in real time.
When a client subscribes to a stateless topic, the values received are not stored in
the subscribed topic cache. If a stream is created after the topic is subscribed,
the stream does not receive a value until the next time the topic is
Considerations when using legacy record topics
When a client subscribes to a topic that uses the deprecated
record type, the values received are not stored in the
subscribed topic cache. If a stream is created after the topic is subscribed, the
stream might only receive delta values. In this case, the client has no value to
apply the deltas to and the data is incorrect. When subscribing to record topics,
always create the stream before requesting a subscription.