Package com.hivemq.extension.sdk.api.services.subscription

Interface SubscriptionStore

  • @DoNotImplement
public interface SubscriptionStore
    This service allows extensions to manage the Subscriptions for client session programmatically.
    Since:
    4.0.0, CE 2019.1

    • Method Detail

      • removeSubscriptions

        @NotNull CompletableFuture<Void> removeSubscriptions​(@NotNull String clientID,
                                                     @NotNull Set<String> topicFilters)
        This method removes multiple subscriptions for a certain client.

        When the client does not exist, nothing happens. This also applies for subscriptions that should be removed for the client, but the client has no subscription for.

        CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

        CompletableFuture fails with a InvalidTopicException if any topic filter is invalid.

        Parameters:
        clientID - The client for which the subscriptions should be removed.
        topicFilters - The topics from which the client should get unsubscribed.
        Returns:
        A CompletableFuture object that will succeed, as soon as the subscriptions were removed by all Cluster Nodes.
        Throws:
        NullPointerException - If clientID, topics or one of the topics in the set is null.
        IllegalArgumentException - If clientID or topics is empty.
        Since:
        4.0.0, CE 2019.1

      • iterateAllSubscribersForTopic

        @NotNull CompletableFuture<Void> iterateAllSubscribersForTopic​(@NotNull String topic,
                                                               @NotNull IterationCallback<SubscriberForTopicResult> callback)
        Iterate over all subscribers in the HiveMQ cluster that have a subscription that matches the passed topic. Includes subscribers with direct matches of the topic or a match via a wildcard topic.

        Example: For topic example/topic we would iterate over all clients with a subscription for example/topic or example/# and other wildcard matches.

        This will iterate all subscribers including individual and shared subscriptions. To filter the result use the overloaded methods and pass a SubscriptionType.

        The callback is executed in the ManagedExtensionExecutorService per default. Use the overloaded methods to pass a custom executor for the callback. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.

        The results are not sorted in any way, no ordering of any kind is guaranteed.

        CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

        If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

        CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

        Parameters:
        topic - The topic to check for (no wildcards allowed). Same topic that is used in an MQTT PUBLISH message.
        callback - An IterationCallback that is called for every returned result.
        Returns:
        A CompletableFuture that is completed after all iterations are executed, no match is found for the topic or the iteration is aborted manually with the IterationContext.
        Throws:
        NullPointerException - If the passed topic or callback are null.
        IllegalArgumentException - If the passed topic is not a valid topic or contains wildcards.
        Since:
        4.2.0, CE 2020.1

      • iterateAllSubscribersForTopic

        @NotNull CompletableFuture<Void> iterateAllSubscribersForTopic​(@NotNull String topic,
                                                               @NotNull SubscriptionType subscriptionType,
                                                               @NotNull IterationCallback<SubscriberForTopicResult> callback)
        Iterate over all subscribers in the HiveMQ cluster that have a subscription that matches the passed topic. Includes subscribers with direct matches of the topic or a match via a wildcard topic.

        Example: For topic example/topic we would iterate over all clients with a subscription for example/topic or example/# and other wildcard matches.

        This method will iterate all subscribers according to the passed SubscriptionType.

        The callback is executed in the ManagedExtensionExecutorService per default. Use the overloaded methods to pass a custom executor for the callback. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.

        The results are not sorted in any way, no ordering of any kind is guaranteed.

        CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

        If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

        CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

        Parameters:
        topic - The topic to check for (no wildcards allowed). Same topic that is used in an MQTT PUBLISH message.
        subscriptionType - A SubscriptionType to filter only individual or shared subscriptions, or both.
        callback - An IterationCallback that is called for every returned result.
        Returns:
        A CompletableFuture that is completed after all iterations are executed, no match is found for the topic or the iteration is aborted manually with the IterationContext.
        Throws:
        NullPointerException - If the passed topic, subscriptionType or callback are null.
        IllegalArgumentException - If the passed topic is not a valid topic or contains wildcards.
        Since:
        4.2.0, CE 2020.1

      • iterateAllSubscribersForTopic

        @NotNull CompletableFuture<Void> iterateAllSubscribersForTopic​(@NotNull String topic,
                                                               @NotNull IterationCallback<SubscriberForTopicResult> callback,
                                                               @NotNull Executor callbackExecutor)
        Iterate over all subscribers in the HiveMQ cluster that have a subscription that matches the passed topic. Includes subscribers with direct matches of the topic or a match via a wildcard topic.

        Example: For topic example/topic we would iterate over all clients with a subscription for example/topic or example/# and other wildcard matches.

        This method will iterate all subscribers including individual and shared subscriptions. To filter the result use the overloaded methods and pass a SubscriptionType.

        The callback is executed in the passed Executor. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.

        The results are not sorted in any way, no ordering of any kind is guaranteed.

        CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

        If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

        CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

        Parameters:
        topic - The topic to check for (no wildcards allowed). Same topic that is used in an MQTT PUBLISH message.
        callback - An IterationCallback that is called for every returned result.
        callbackExecutor - An Executor in which the callback for each iteration is executed.
        Returns:
        A CompletableFuture that is completed after all iterations are executed, no match is found for the topic or the iteration is aborted manually with the IterationContext.
        Throws:
        NullPointerException - If the passed topic, callback or callbackExecutor are null.
        IllegalArgumentException - If the passed topic is not a valid topic or contains wildcards.
        Since:
        4.2.0, CE 2020.1

      • iterateAllSubscribersForTopic

        @NotNull CompletableFuture<Void> iterateAllSubscribersForTopic​(@NotNull String topic,
                                                               @NotNull SubscriptionType subscriptionType,
                                                               @NotNull IterationCallback<SubscriberForTopicResult> callback,
                                                               @NotNull Executor callbackExecutor)
        Iterate over all subscribers in the HiveMQ cluster that have a subscription that matches the passed topic. Includes subscribers with direct matches of the topic or a match via a wildcard topic.

        Example: For topic example/topic we would iterate over all clients with a subscription for example/topic or example/# and other wildcard matches.

        This method will iterate all subscribers according to the passed SubscriptionType.

        The callback is executed in the passed Executor. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.

        The results are not sorted in any way, no ordering of any kind is guaranteed.

        CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

        If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

        CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

        Parameters:
        topic - The topic to check for (no wildcards allowed). Same topic that is used in an MQTT PUBLISH message.
        subscriptionType - A SubscriptionType to filter only individual or shared subscriptions, or both.
        callback - An IterationCallback that is called for every returned result.
        callbackExecutor - An Executor in which the callback for each iteration is executed.
        Returns:
        A CompletableFuture that is completed after all iterations are executed, no match is found for the topic or the iteration is aborted manually with the IterationContext.
        Throws:
        NullPointerException - If the passed topic, subscriptionType, callback or callbackExecutor are null.
        IllegalArgumentException - If the passed topic is not a valid topic or contains wildcards.
        Since:
        4.2.0, CE 2020.1

      • iterateAllSubscribersWithTopicFilter

        @NotNull CompletableFuture<Void> iterateAllSubscribersWithTopicFilter​(@NotNull String topicFilter,
                                                                      @NotNull IterationCallback<SubscriberWithFilterResult> callback)
        Iterate over all subscribers in the HiveMQ cluster that have a subscription that equals the passed topic filter. Only includes subscribers with direct matches of the topic.

        Example 1: For topic filter example/topic we would iterate over all clients with a subscription for example/topic, but not for example/# or other wildcard matches.

        Example 2: For topic filter example/# we would iterate over all clients with a subscription for example/#, but not for example/+ or other wildcard matches and also not for topic filters like example/topic.

        This method will iterate all subscribers including individual and shared subscriptions. To filter the result use the overloaded methods and pass a SubscriptionType.

        The callback is executed in the ManagedExtensionExecutorService per default. Use the overloaded methods to pass a custom executor for the callback. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.

        The results are not sorted in any way, no ordering of any kind is guaranteed.

        CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

        If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

        CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

        Parameters:
        topicFilter - The topic filter to search for (wildcards allowed). Same topic that is used in an MQTT SUBSCRIBE message. Wildcards in the topic filter are not expanded, only exact matches are contained in the result.
        callback - An IterationCallback that is called for every returned result.
        Returns:
        A CompletableFuture that is completed after all iterations are executed, no match is found for the topic filter or the iteration is aborted manually with the IterationContext.
        Throws:
        NullPointerException - If the passed topicFilter or callback are null.
        IllegalArgumentException - If the passed topicFilter is not a valid topic.
        Since:
        4.2.0, CE 2020.1

      • iterateAllSubscribersWithTopicFilter

        @NotNull CompletableFuture<Void> iterateAllSubscribersWithTopicFilter​(@NotNull String topicFilter,
                                                                      @NotNull SubscriptionType subscriptionType,
                                                                      @NotNull IterationCallback<SubscriberWithFilterResult> callback)
        Iterate over all subscribers in the HiveMQ cluster that have a subscription that equals the passed topic filter. Only includes subscribers with direct matches of the topic.

        Example 1: For topic filter example/topic we would iterate over all clients with a subscription for example/topic, but not for example/# or other wildcard matches.

        Example 2: For topic filter example/# we would iterate over all clients with a subscription for example/#, but not for example/+ or other wildcard matches and also not for topic filters like example/topic.

        This method will iterate all subscribers according to the passed SubscriptionType.

        The callback is executed in the ManagedExtensionExecutorService per default. Use the overloaded methods to pass a custom executor for the callback. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.

        The results are not sorted in any way, no ordering of any kind is guaranteed.

        CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

        If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

        CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

        Parameters:
        topicFilter - The topic filter to search for (wildcards allowed). Same topic that is used in an MQTT SUBSCRIBE message. Wildcards in the topic filter are not expanded, only exact matches are contained in the result.
        callback - An IterationCallback that is called for every returned result.
        subscriptionType - A SubscriptionType to filter only individual or shared subscriptions, or both.
        Returns:
        A CompletableFuture that is completed after all iterations are executed, no match is found for the topic filter or the iteration is aborted manually with the IterationContext.
        Throws:
        NullPointerException - If the passed topicFilter, subscriptionType or callback are null.
        IllegalArgumentException - If the passed topicFilter is not a valid topic.
        Since:
        4.2.0, CE 2020.1

      • iterateAllSubscribersWithTopicFilter

        @NotNull CompletableFuture<Void> iterateAllSubscribersWithTopicFilter​(@NotNull String topicFilter,
                                                                      @NotNull IterationCallback<SubscriberWithFilterResult> callback,
                                                                      @NotNull Executor callbackExecutor)
        Iterate over all subscribers in the HiveMQ cluster that have a subscription that equals the passed topic filter. Only includes subscribers with direct matches of the topic.

        Example 1: For topic filter example/topic we would iterate over all clients with a subscription for example/topic, but not for example/# or other wildcard matches.

        Example 2: For topic filter example/# we would iterate over all clients with a subscription for example/#, but not for example/+ or other wildcard matches and also not for topic filters like example/topic.

        This method will iterate all subscribers including individual and shared subscriptions. To filter the result use the overloaded methods and pass a SubscriptionType.

        The callback is executed in the passed Executor. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection, as the callback might be executed in another thread as the calling thread of this method.

        The results are not sorted in any way, no ordering of any kind is guaranteed.

        CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

        If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

        CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

        Parameters:
        topicFilter - The topic filter to search for (wildcards allowed). Same topic that is used in an MQTT SUBSCRIBE message. Wildcards in the topic filter are not expanded, only exact matches are contained in the result.
        callback - An IterationCallback that is called for every returned result.
        callbackExecutor - An Executor in which the callback for each iteration is executed.
        Returns:
        A CompletableFuture that is completed after all iterations are executed, no match is found for the topic filter or the iteration is aborted manually with the IterationContext.
        Throws:
        NullPointerException - If the passed topicFilter, callback or callbackExecutor are null.
        IllegalArgumentException - If the passed topicFilter is not a valid topic.
        Since:
        4.2.0, CE 2020.1

      • iterateAllSubscribersWithTopicFilter

        @NotNull CompletableFuture<Void> iterateAllSubscribersWithTopicFilter​(@NotNull String topicFilter,
                                                                      @NotNull SubscriptionType subscriptionType,
                                                                      @NotNull IterationCallback<SubscriberWithFilterResult> callback,
                                                                      @NotNull Executor callbackExecutor)
        Iterate over all subscribers in the HiveMQ cluster that have a subscription that equals the passed topic filter. Only includes subscribers with direct matches of the topic.

        Example 1: For topic filter example/topic we would iterate over all clients with a subscription for example/topic, but not for example/# or other wildcard matches.

        Example 2: For topic filter example/# we would iterate over all clients with a subscription for example/#, but not for example/+ or other wildcard matches and also not for topic filters like example/topic.

        This method will iterate all subscribers according to the passed SubscriptionType.

        The callback is executed in the passed Executor. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection, as the callback might be executed in another thread as the calling thread of this method.

        The results are not sorted in any way, no ordering of any kind is guaranteed.

        CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

        If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

        CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded.

        Parameters:
        topicFilter - The topic filter to search for (wildcards allowed). Same topic that is used in an MQTT SUBSCRIBE message. Wildcards in the topic filter are not expanded, only exact matches are contained in the result.
        subscriptionType - A SubscriptionType to filter only individual or shared subscriptions, or both.
        callback - An IterationCallback that is called for every returned result.
        callbackExecutor - An Executor in which the callback for each iteration is executed.
        Returns:
        A CompletableFuture that is completed after all iterations are executed, no match is found for the topic filter or the iteration is aborted manually with the IterationContext.
        Throws:
        NullPointerException - If the passed topicFilter, subscriptionType, callback or callbackExecutor are null.
        IllegalArgumentException - If the passed topicFilter is not a valid topic.
        Since:
        4.2.0, CE 2020.1

      • iterateAllSubscriptions

        @NotNull CompletableFuture<Void> iterateAllSubscriptions​(@NotNull IterationCallback<SubscriptionsForClientResult> callback)
        Iterate over all subscribers and their subscriptions in the HiveMQ cluster.

        The callback is called once for each client. Passed to each execution of the callback are the client identifier and a set of all its subscriptions. Clients without subscriptions are not included.

        The callback is executed in the ManagedExtensionExecutorService per default. Use the overloaded methods to pass a custom executor for the callback. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.

        The results are not sorted in any way, no ordering of any kind is guaranteed.

        CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

        If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

        CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded. CompletableFuture fails with a IterationFailedException if the cluster topology changed during the iteration (e.g. a network-split, node leave or node join).

        Parameters:
        callback - An IterationCallback that is called for every returned result.
        Returns:
        A CompletableFuture that is completed after all iterations are executed, no subscriptions exist or the iteration is aborted manually with the IterationContext.
        Throws:
        NullPointerException - If the passed callback is null.
        Since:
        4.2.0, CE 2020.1

      • iterateAllSubscriptions

        @NotNull CompletableFuture<Void> iterateAllSubscriptions​(@NotNull IterationCallback<SubscriptionsForClientResult> callback,
                                                         @NotNull Executor callbackExecutor)
        Iterate over all subscribers and their subscriptions in the HiveMQ cluster.

        The callback is called once for each client. Passed to each execution of the callback are the client identifier and a set of all its subscriptions. Clients without subscriptions are not included.

        The callback is executed in the passed Executor. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.

        The results are not sorted in any way, no ordering of any kind is guaranteed.

        CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.

        If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling IterationContext.abortIteration().

        CompletableFuture fails with an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded. CompletableFuture fails with a IterationFailedException if the cluster topology changed during the iteration (e.g. a network-split, node leave or node join).

        Parameters:
        callback - An IterationCallback that is called for every returned result.
        callbackExecutor - An Executor in which the callback for each iteration is executed.
        Returns:
        A CompletableFuture that is completed after all iterations are executed, no subscriptions exist or the iteration is aborted manually with the IterationContext.
        Throws:
        NullPointerException - If the passed callback or callbackExecutor are null.
        Since:
        4.2.0, CE 2020.1