A special type of topic, which can map to a different real topic for every client
that subscribes to it. In this way, different clients can see different values for what is
effectively the same topic from the client point of view.
When a client subscribes to a routing topic, the request is either passed to a client
that has registered as a routing subscription handler for the topic or handled by a server-side routing handler. The
routing handler assigns a linked topic to represent it to that client.
The routing handler can assign a different linked topic to each client that
subscribes to the routing topic.
When updates are received on the linked topic, those updates are propagated through
the routing topic to the subscribing clients.
The subscribing client is not aware of the linked topic. It is subscribed to the
routing topic and all the updates that the client receives contain only the routing
topic path and not the linked topic path.
Why use a routing topic?
Use routing topics when you want your subscribing clients to all have the same
subscription behavior, but the data they receive to be decided by a routing handler
depending on criteria about that client.
For example, your subscribing clients can subscribe to a routing topic called
Price, but the routing handler
assigns each client a different linked topic depending on the client's geographic
location. This way, clients in different countries can act in the same way, but
receive localized information.
Properties of a routing topic
When you create a routing topic you can specify the following properties in the topic specification:
- If set to true, when a session unsubscribes from
the topic, any updates for the topic that are still queued for the session are
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.
Considerations when using a routing topic
Using routing topics requires that you write a routing handler that is either hosted on the server or registered by a
client with the required permissions. The following client APIs can register a
routing handler: Java™, .NET, or Android™
A subscribing client only needs permission to subscribe to the routing topic.
Permission to subscribe to the linked topic is not required.
If the linked topic is removed, subscribing clients are automatically unsubscribed
from the routing topic.
If you attempt to fetch from a routing topic that routes to a stateless topic, no
data is returned.
You cannot use topic replication to replicate routing topics between Diffusion™ servers.
When using automatic fan-out to propagate topics from a primary server to one or more
secondary servers, the routing subscription handlers for a routing topic must be
registered at the primary and all secondary servers. The routing logic provided by
the handlers on the primary and secondary server must be identical.