com.hivemq.extension.sdk.api.services.subscription.SubscriptionStore Maven / Gradle / Ivy
Show all versions of hivemq-extension-sdk Show documentation
/*
* Copyright 2018-present HiveMQ GmbH
*
* 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.
*/
package com.hivemq.extension.sdk.api.services.subscription;
import com.hivemq.extension.sdk.api.annotations.DoNotImplement;
import com.hivemq.extension.sdk.api.annotations.NotNull;
import com.hivemq.extension.sdk.api.services.ManagedExtensionExecutorService;
import com.hivemq.extension.sdk.api.services.exception.DoNotImplementException;
import com.hivemq.extension.sdk.api.services.exception.IncompatibleHiveMQVersionException;
import com.hivemq.extension.sdk.api.services.exception.InvalidTopicException;
import com.hivemq.extension.sdk.api.services.exception.IterationFailedException;
import com.hivemq.extension.sdk.api.services.exception.NoSuchClientIdException;
import com.hivemq.extension.sdk.api.services.exception.RateLimitExceededException;
import com.hivemq.extension.sdk.api.services.general.IterationCallback;
import com.hivemq.extension.sdk.api.services.general.IterationContext;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executor;
/**
* This service allows extensions to manage the Subscriptions for client session programmatically.
*
* @author Christoph Schäbel
* @author Florian Limpöck
* @since 4.0.0, CE 2019.1
*/
@DoNotImplement
public interface SubscriptionStore {
/**
* This method adds a subscription for a certain client to a certain topic.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* {@link CompletableFuture} fails with a {@link DoNotImplementException} if TopicSubscription is implemented by the
* extension.
*
* {@link CompletableFuture} fails with a {@link NoSuchClientIdException} if no session for this client exists.
*
* @param clientID The client for which the new subscription should be added.
* @param subscription The subscription to which the client should be subscribed.
* @return A {@link CompletableFuture} object that will succeed, as soon as the subscription was added by all
* cluster nodes.
* @throws NullPointerException If clientID or subscription is null.
* @throws IllegalArgumentException If clientID is empty.
* @since 4.0.0, CE 2019.1
*/
@NotNull CompletableFuture addSubscription(@NotNull String clientID, @NotNull TopicSubscription subscription);
/**
* This method adds multiple subscriptions for a certain client.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* {@link CompletableFuture} fails with a {@link DoNotImplementException} if any of the TopicSubscription is
* implemented by the extension.
*
* {@link CompletableFuture} fails with a {@link NoSuchClientIdException} if no session for this client exists.
*
* @param clientID The client for which the new subscriptions should be added.
* @param subscriptions The subscriptions to which the client should be subscribed.
* @return A {@link 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.
* @throws IllegalArgumentException If clientID or subscriptions is empty.
* @since 4.0.0, CE 2019.1
*/
@NotNull CompletableFuture addSubscriptions(
@NotNull String clientID, @NotNull Set subscriptions);
/**
* 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.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* {@link CompletableFuture} fails with a {@link InvalidTopicException} if the topic filter is invalid.
*
* @param clientID The client for which the subscription should be removed.
* @param topicFilter The topic from which the client should get unsubscribed.
* @return A {@link CompletableFuture} object that will succeed, as soon as the subscription was removed by all
* cluster nodes.
* @throws NullPointerException If clientID or topicFilter is null.
* @throws IllegalArgumentException If clientID is empty.
* @since 4.0.0, CE 2019.1
*/
@NotNull CompletableFuture removeSubscription(@NotNull String clientID, @NotNull String topicFilter);
/**
* 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.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* {@link CompletableFuture} fails with a {@link InvalidTopicException} if any topic filter is invalid.
*
* @param clientID The client for which the subscriptions should be removed.
* @param topicFilters The topics from which the client should get unsubscribed.
* @return A {@link 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.
* @throws IllegalArgumentException If clientID or topics is empty.
* @since 4.0.0, CE 2019.1
*/
@NotNull CompletableFuture removeSubscriptions(@NotNull String clientID, @NotNull Set topicFilters);
/**
* 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.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* @param clientID The client from where to get all subscriptions.
* @return A {@link CompletableFuture} which contains all subscriptions the client subscribed to.
* @throws NullPointerException If clientID is null.
* @throws IllegalArgumentException If clientID is empty.
* @since 4.0.0, CE 2019.1
*/
@NotNull CompletableFuture> getSubscriptions(@NotNull String clientID);
/**
* 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 {@link SubscriptionType}.
*
* The callback is executed in the {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded.
*
* @param topic The topic to check for (no wildcards allowed). Same topic that is used in an MQTT PUBLISH
* message.
* @param callback An {@link IterationCallback} that is called for every returned result.
* @return A {@link CompletableFuture} that is completed after all iterations are executed, no match is found for
* the topic or the iteration is aborted manually with the {@link IterationContext}.
* @throws NullPointerException If the passed topic or callback are null.
* @throws IllegalArgumentException If the passed topic is not a valid topic or contains wildcards.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllSubscribersForTopic(
@NotNull String topic, @NotNull IterationCallback 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 {@link SubscriptionType}.
*
* The callback is executed in the {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded.
*
* @param topic The topic to check for (no wildcards allowed). Same topic that is used in an MQTT PUBLISH
* message.
* @param subscriptionType A {@link SubscriptionType} to filter only individual or shared subscriptions, or both.
* @param callback An {@link IterationCallback} that is called for every returned result.
* @return A {@link CompletableFuture} that is completed after all iterations are executed, no match is found for
* the topic or the iteration is aborted manually with the {@link IterationContext}.
* @throws NullPointerException If the passed topic, subscriptionType or callback are null.
* @throws IllegalArgumentException If the passed topic is not a valid topic or contains wildcards.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllSubscribersForTopic(
@NotNull String topic,
@NotNull SubscriptionType subscriptionType,
@NotNull IterationCallback 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 including individual and shared subscriptions. To filter the result use
* the overloaded methods and pass a {@link SubscriptionType}.
*
* The callback is executed in the passed {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded.
*
* @param topic The topic to check for (no wildcards allowed). Same topic that is used in an MQTT PUBLISH
* message.
* @param callback An {@link IterationCallback} that is called for every returned result.
* @param callbackExecutor An {@link Executor} in which the callback for each iteration is executed.
* @return A {@link CompletableFuture} that is completed after all iterations are executed, no match is found for
* the topic or the iteration is aborted manually with the {@link IterationContext}.
* @throws NullPointerException If the passed topic, callback or callbackExecutor are null.
* @throws IllegalArgumentException If the passed topic is not a valid topic or contains wildcards.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllSubscribersForTopic(
@NotNull String topic,
@NotNull IterationCallback 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 {@link SubscriptionType}.
*
* The callback is executed in the passed {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded.
*
* @param topic The topic to check for (no wildcards allowed). Same topic that is used in an MQTT PUBLISH
* message.
* @param subscriptionType A {@link SubscriptionType} to filter only individual or shared subscriptions, or both.
* @param callback An {@link IterationCallback} that is called for every returned result.
* @param callbackExecutor An {@link Executor} in which the callback for each iteration is executed.
* @return A {@link CompletableFuture} that is completed after all iterations are executed, no match is found for
* the topic or the iteration is aborted manually with the {@link IterationContext}.
* @throws NullPointerException If the passed topic, subscriptionType, callback or callbackExecutor are null.
* @throws IllegalArgumentException If the passed topic is not a valid topic or contains wildcards.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllSubscribersForTopic(
@NotNull String topic,
@NotNull SubscriptionType subscriptionType,
@NotNull IterationCallback 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 {@link SubscriptionType}.
*
* The callback is executed in the {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded.
*
* @param 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.
* @param callback An {@link IterationCallback} that is called for every returned result.
* @return A {@link 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 {@link IterationContext}.
* @throws NullPointerException If the passed topicFilter or callback are null.
* @throws IllegalArgumentException If the passed topicFilter is not a valid topic.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllSubscribersWithTopicFilter(
@NotNull String topicFilter, @NotNull IterationCallback 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 {@link SubscriptionType}.
*
* The callback is executed in the {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded.
*
* @param 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.
* @param callback An {@link IterationCallback} that is called for every returned result.
* @param subscriptionType A {@link SubscriptionType} to filter only individual or shared subscriptions, or both.
* @return A {@link 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 {@link IterationContext}.
* @throws NullPointerException If the passed topicFilter, subscriptionType or callback are null.
* @throws IllegalArgumentException If the passed topicFilter is not a valid topic.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllSubscribersWithTopicFilter(
@NotNull String topicFilter,
@NotNull SubscriptionType subscriptionType,
@NotNull IterationCallback 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 {@link SubscriptionType}.
*
* The callback is executed in the passed {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded.
*
* @param 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.
* @param callback An {@link IterationCallback} that is called for every returned result.
* @param callbackExecutor An {@link Executor} in which the callback for each iteration is executed.
* @return A {@link 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 {@link IterationContext}.
* @throws NullPointerException If the passed topicFilter, callback or callbackExecutor are null.
* @throws IllegalArgumentException If the passed topicFilter is not a valid topic.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllSubscribersWithTopicFilter(
@NotNull String topicFilter,
@NotNull IterationCallback 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 {@link SubscriptionType}.
*
* The callback is executed in the passed {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded.
*
* @param 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.
* @param subscriptionType A {@link SubscriptionType} to filter only individual or shared subscriptions, or both.
* @param callback An {@link IterationCallback} that is called for every returned result.
* @param callbackExecutor An {@link Executor} in which the callback for each iteration is executed.
* @return A {@link 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 {@link IterationContext}.
* @throws NullPointerException If the passed topicFilter, subscriptionType, callback or callbackExecutor are
* null.
* @throws IllegalArgumentException If the passed topicFilter is not a valid topic.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllSubscribersWithTopicFilter(
@NotNull String topicFilter,
@NotNull SubscriptionType subscriptionType,
@NotNull IterationCallback 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 {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded. {@link CompletableFuture} fails with a
* {@link IterationFailedException} if the cluster topology changed during the iteration (e.g. a network-split, node
* leave or node join).
*
* @param callback An {@link IterationCallback} that is called for every returned result.
* @return A {@link CompletableFuture} that is completed after all iterations are executed, no subscriptions exist
* or the iteration is aborted manually with the {@link IterationContext}.
* @throws NullPointerException If the passed callback is null.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllSubscriptions(
@NotNull IterationCallback 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 passed {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded. {@link CompletableFuture} fails with a
* {@link IterationFailedException} if the cluster topology changed during the iteration (e.g. a network-split, node
* leave or node join).
*
* @param callback An {@link IterationCallback} that is called for every returned result.
* @param callbackExecutor An {@link Executor} in which the callback for each iteration is executed.
* @return A {@link CompletableFuture} that is completed after all iterations are executed, no subscriptions exist
* or the iteration is aborted manually with the {@link IterationContext}.
* @throws NullPointerException If the passed callback or callbackExecutor are null.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllSubscriptions(
@NotNull IterationCallback callback, @NotNull Executor callbackExecutor);
}