Missing topic notifications

The Diffusion server provides a feature to notify sessions about missing topic subscriptions. If a session registers itself as a handler for missing topics subscriptions, in a topic tree branch; then, the server will send notifications to such handlers, as soon as any other session subscribes using a topic selector that intersects the topic tree branch, but selects no existing topics. The handler can then do anything upon receiving such notification such as creating a topic at the notified path for which subscription occurred, or something else, as required.

Figure 1. Sequence diagram handling Missing topic notifications

The Gateway Framework supports the use of this feature with source services. A source service handler can register a handler to be notified of missing topic notifications for a specified topic tree branch. The handler can handle the notification as required.

Handling missing topic notifications

To register for missing topic notifications, the Publisher.addMissingTopicHandler method should be used.

This method requires:

  • a topicPath - which specifies a branch of a topic tree, for which the service should receive notifications, and

  • a MissingTopicNotificationHandler - which receives the notification, if any other session subscribes to a topic selector (matching the topic branch), which matches no existing topics in the server.

In the example of MissingTopicNotificationHandler implementation, a MissingTopicNotificationHandler is registered in the start method.

    public CompletableFuture<?> start() {

        return publisher

Example: Registering a missing topic notification handler with the publisher

Below is the sample implementation of MissingTopicNotificationHandler presented in the example. Here, on receiving the missing topic notification in onMissingTopic method, the publisher instance is used to publish to the missing topic.

    private static final class MissingTopicNotificationHandlerImpl implements MissingTopicNotificationHandler {

        private final Publisher publisher;

        private MissingTopicNotificationHandlerImpl(Publisher publisher) {
            this.publisher = publisher;

        public CompletableFuture<?> onMissingTopic(
            MissingTopicNotification missingTopicNotification) {

            final String missingTopicPath =

            LOG.info("{} topic is missing. Publishing to this topic",

            try {
                        "{\n" +
                            "    \"dummy\": \"data\"\n" +
                    .whenComplete((result, ex) -> {
                        if (ex != null) {
                                "Failed to publish to {} topic",
            catch (PayloadConversionException ex) {
                throw new IllegalStateException(ex);
            return CompletableFuture.completedFuture(null);

Multiple source services types can register multiple missing topic notification handlers for same topic path. In such cases, the Framework will route the notification to all registered handlers. It is up to the application to decide how to, or even whether, to handle the notification.

When a service is paused, the handler will not get any notifications, even if the application is still connected to the server, and the server sends notifications to the Framework.
The received notifications will be stored in an internal queue. If the service is resumed the list of notifications will be processed. This ensures that the notifications are not lost when a service is paused by a user, or due to application error.
On the other hand, it also means that the notifications could be stale, if a service is paused for a long time. This should be considered when handling the notifications.