Removing topics

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

Required permissions: modify_topic

Currently all topics created using a client have a lifespan the same as Diffusion Cloud (unless persistence is enabled). The topics remain at Diffusion Cloud even after the client session that created them has closed unless you explicitly specify that the topic is removed with the session. The lifespan of a topic can also be defined on creation using automatic topic removal

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 remove all topics beneath a selected topic path by appending the descendant pattern qualifiers, / and //.

Only topics for which the client has modify_topic permission are removed.

If there are topics for which the client does not have modify_topic permission, they are unaffected and the operation completes without throwing an exception.

For more information, see Topic selectors.

JavaScript

const result = await session.topics.remove('topic_selector');
console.log(`Removed ${result.removedCount} topics.`);

.NET

await session.TopicControl.RemoveTopicsAsync(topic);

Java and Android

final TopicControl topicControl = session.feature(TopicControl.class);
topicControl.removeTopics("?my/topic/path//");

/**
 * Copyright © 2021 - 2023 DiffusionData Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#include <stdio.h>
#include <stdlib.h>
#ifndef WIN32
        #include <unistd.h>
#else
        #define sleep(x) Sleep(1000 * x)
#endif

#include "diffusion.h"


static int on_topic_removed(
        SESSION_T *session,
        const DIFFUSION_TOPIC_REMOVAL_RESULT_T *result,
        void *context)
{
        // topic has been removed
        return HANDLER_SUCCESS;
}


int main(int argc, char **argv)
{
        const char *url = "ws://localhost:8080";
        const char *principal = "control";
        const char *password = "password";
        const char *topic_path = "my/topic/path";

        CREDENTIALS_T *credentials = credentials_create_password(password);

        SESSION_T *session;
        DIFFUSION_ERROR_T error = { 0 };

        // Create a session, synchronously
        session = session_create(url, principal, credentials, NULL, NULL, &error);
        if(session == NULL) {
                printf("Failed to create session: %s\n", error.message);
                free(error.message);
                credentials_free(credentials);
                return EXIT_FAILURE;
        }

        // remove `topic_path`
        TOPIC_REMOVAL_PARAMS_T params = {
                .topic_selector = topic_path,
                .on_removed = on_topic_removed
        };
        topic_removal(session, params);

        // Sleep for a while
        sleep(5);

        // Close the session, and release resources and memory
        session_close(session, NULL);
        session_free(session);

        credentials_free(credentials);
        return EXIT_SUCCESS;
}

Apple

session.topicControl.removeTopics(withTopicSelectorExpression: topic_path) { (result, error) in
    if (error != nil) {
        print("An error has occurred while removing topic '%@': %@",
              topic_path,
              error!.localizedDescription)
    }
    else {

        print("Topic '%@' has been successfully removed", topic_path)
    }
}