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 Details

    • addSubscription

      @NotNull @NotNull CompletableFuture<Void> addSubscription​(@NotNull String clientID, @NotNull TopicSubscription subscription)
      This method adds a subscription for a certain client to a certain topic.

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

      CompletableFuture fails with a DoNotImplementException if TopicSubscription is implemented by the extension.

      CompletableFuture fails with a NoSuchClientIdException if no session for this client exists.

      Parameters:
      clientID - The client for which the new subscription should be added.
      subscription - The subscription to which the client should be subscribed.
      Returns:
      A CompletableFuture object that will succeed, as soon as the subscription was added by all cluster nodes.
      Throws:
      NullPointerException - If clientID or subscription is null.
      IllegalArgumentException - If clientID is empty.
      Since:
      4.0.0, CE 2019.1

    • addSubscriptions

      @NotNull @NotNull CompletableFuture<Void> addSubscriptions​(@NotNull String clientID, @NotNull Set<TopicSubscription> subscriptions)
      This method adds multiple subscriptions for a certain client.

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

      CompletableFuture fails with a DoNotImplementException if any of the TopicSubscription is implemented by the extension.

      CompletableFuture fails with a NoSuchClientIdException if no session for this client exists.

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

    • removeSubscription

      @NotNull @NotNull CompletableFuture<Void> removeSubscription​(@NotNull String clientID, @NotNull String topicFilter)
      This method removes a subscription for a certain client and a certain topic.

      When the client or the subscription for the client does not exist, nothing happens.

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

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

      Parameters:
      clientID - The client for which the subscription should be removed.
      topicFilter - The topic from which the client should get unsubscribed.
      Returns:
      A CompletableFuture object that will succeed, as soon as the subscription was removed by all cluster nodes.
      Throws:
      NullPointerException - If clientID or topicFilter is null.
      IllegalArgumentException - If clientID is empty.
      Since:
      4.0.0, CE 2019.1

    • removeSubscriptions

      @NotNull @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

    • getSubscriptions

      @NotNull @NotNull CompletableFuture<Set<TopicSubscription>> getSubscriptions​(@NotNull String clientID)
      Returns all subscriptions a client is subscribed to.

      The returned Set is read-only and must not be modified. If the client does not exist, an empty Set is returned.

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

      Parameters:
      clientID - The client from where to get all subscriptions.
      Returns:
      A CompletableFuture which contains all subscriptions the client subscribed to.
      Throws:
      NullPointerException - If clientID is null.
      IllegalArgumentException - If clientID is empty.
      Since:
      4.0.0, CE 2019.1

    • iterateAllSubscribersForTopic

      @NotNull @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 @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 @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 @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 @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 @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 @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 @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 @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 @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