Expand Collapse
Just a second...

Subscribing to topics

Consider the following information when deciding how clients subscribe to topics.

For a client to receive a stream of updates from a topic, the following conditions must be met:
  • The client must subscribe using a selector that matches the topic.
  • The topic must exist on Diffusion™ Cloud .
  • The client must register at least one stream that matches the topic.

When all these conditions are met, the stream receives a subscription notification and an initial value for the topic. The client receives subsequent updates to the topic through the stream.

The order in which these conditions are met does not affect the receipt of the subscription notification and the initial value of the topic.

Permissions

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.

Subscription flow

Client on the left of the image. An arrow labelled 1a goes from the client to the server, which is on the left of the image. Inside the server are two intersecting circles. The top circle represents the set of selections that the client has made to indicate the topics it is interested in subscribing to. The bottom circle represents the set of topics that exist on the server (this is labelled 1b). The intersection of the circles represent the subscriptions that client has made; this is labelled 2. From the subscriptions section an arrow labelled 3, goes back to the client.
  1. The prerequisite conditions for subscribing to a topic are met:
    1. The client selects a set of topics to subscribe to, or that selection is made on the client's behalf by another client.

      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 Diffusion Cloud . Because selections are stored, the client can subscribe, pre-emptively, to topics that do not currently exist.

    2. The topic exists on Diffusion Cloud .

      The topic 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 exist.

  2. 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 Diffusion Cloud defines the list of subscriptions that client has made.

    For each client that connects to Diffusion Cloud , Diffusion Cloud stores a separate list of subscriptions.

  3. When the subscription is made, the value of the subscribed topic is sent to the client.

    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

An arrow labelled 1 comes in from the right side of the image. This is the subscribed values sent from the server. The arrow goes to a large box labelled 'client' and to a smaller box within that labelled 'subscribed topic cache'. The subscribed topic cache is labelled 2. Inside it are squares representing topics, each containing a value. An arrow leads from the subscribed topic cache to another box within the client named 'stream registry' and labelled 3. The stream registry contains circles representing streams. An arrow leads from the stream registry to another box within the client named 'subscription notification' and labelled 4.
  1. 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 deltas.

  2. Values for each subscribed topic are stored in the subscribed topic cache on the client.

    This is not the case for stateless or record topics, see Considerations when subscribing.

  3. The client registers streams against a topic selector. A list of streams is maintained in the stream registry.
  4. 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 Diffusion Cloud with the selections made by the client, determine what data is sent to the client from Diffusion Cloud . To reduce the amount of data sent between Diffusion Cloud 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 updated.