com.hivemq.spi.services

Interface AsyncSubscriptionStore

public interface AsyncSubscriptionStore

The subscription store allows the management of all client subscriptions from within a plugin

Since:

3.1

Author:

Lukas Brandl, Florian Limpöck

Method Summary

Methods

Modifier and Type	Method and Description
com.google.common.util.concurrent.ListenableFuture<Void>	addSubscription(String clientID, Topic topic) This method adds a subscription for a certain client to a certain topic.
com.google.common.util.concurrent.ListenableFuture<Void>	addSubscriptions(String clientID, Set<Topic> topics) This method adds subscriptions for a certain client to certain topics.
com.google.common.util.concurrent.ListenableFuture<Set<String>>	getLocalSubscribers(String topic) Returns all MQTT client subscriber identifiers for a given topic, for this HiveMQ instance.
com.google.common.util.concurrent.ListenableFuture<com.google.common.collect.Multimap<String,Topic>>	getLocalSubscriptions() This method returns all subscriptions on this HiveMQ Node as a Multimap of client identifiers and topics.
com.google.common.util.concurrent.ListenableFuture<Set<Topic>>	getLocalTopics(String clientID) Returns all topics a client is subscribed to, on this HiveMQ instance.
com.google.common.util.concurrent.ListenableFuture<Set<String>>	getSubscribers(String topic) Returns all MQTT client subscriber identifiers for a given topic, this HiveMQ instance and all other nodes in a HiveMQ cluster.
com.google.common.util.concurrent.ListenableFuture<com.google.common.collect.Multimap<String,Topic>>	getSubscriptions() This method returns all subscriptions this HiveMQ instance and all other nodes in a HiveMQ cluster, as a Multimap of client identifiers and topics.
com.google.common.util.concurrent.ListenableFuture<Set<Topic>>	getTopics(String clientID) Returns all topics a client is subscribed to, on this HiveMQ instance and all other nodes in a HiveMQ cluster.
com.google.common.util.concurrent.ListenableFuture<Void>	removeSubscription(String clientID, String topic) This method removes a subscription for a certain client and a certain topic.
com.google.common.util.concurrent.ListenableFuture<Void>	removeSubscriptions(String clientID, Set<String> topics) This method removes subscriptions for a certain client and certain topics.

Method Detail

getLocalSubscriptions

@ReadOnly
com.google.common.util.concurrent.ListenableFuture<com.google.common.collect.Multimap<String,Topic>> getLocalSubscriptions()

This method returns all subscriptions on this HiveMQ Node as a Multimap of client identifiers and topics. You won't receive subscriptions of connected clients from other HiveMQ nodes if HiveMQ runs in a cluster.

Please be aware that calling this method on HiveMQ instances with many subscriptions could have negative performance effects.

The returned Multimap is read-only and must not be modified.

Returns:

a ListenableFuture which contains a Multimap of client identifiers and their topic subscriptions failing with a RateLimitExceededException if the plugin service rate limit is exceeded.

getLocalSubscribers

@ReadOnly
com.google.common.util.concurrent.ListenableFuture<Set<String>> getLocalSubscribers(@NotNull
                                                                                           String topic)

Returns all MQTT client subscriber identifiers for a given topic, for this HiveMQ instance. MQTT Wildcards are allowed.

Don't pass null as topic. This method is lenient, so it will just return an empty Set.

The returned Set is read-only and must not be modified.

Parameters:

topic - the topic

Returns:

a ListenableFuture which contains the client identifiers of all subscribers that subscribed to the topic failing with a RateLimitExceededException if the plugin service rate limit is exceeded.

getLocalTopics

@ReadOnly
com.google.common.util.concurrent.ListenableFuture<Set<Topic>> getLocalTopics(@NotNull
                                                                                     String clientID)

Returns all topics a client is subscribed to, on this HiveMQ instance.

If the client does not exist, an empty Set is returned.

Don't pass null as clientId. This method is lenient, so it will just return an empty Set.

The returned Set is read-only and must not be modified.

Parameters:

clientID - of the client

Returns:

a ListenableFuture which contains all topics the client subscribed to failing with a RateLimitExceededException if the plugin service rate limit is exceeded.

addSubscription

com.google.common.util.concurrent.ListenableFuture<Void> addSubscription(@NotNull
                                                                       String clientID,
                                                                       @NotNull
                                                                       Topic topic)

This method adds a subscription for a certain client to a certain topic. If HiveMQ is connected to a cluster, the subscription will be broadcast to all other Cluster Nodes.

This method is lenient, so if the clientId or the topic is null, nothing will happen.

Parameters:

clientID - client, which should be subscribed

topic - topic to which the client should be subscribed

Returns:

a ListenableFuture object that will succeed, as soon es the subscription was added by all Cluster Nodes. failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

addSubscriptions

com.google.common.util.concurrent.ListenableFuture<Void> addSubscriptions(@NotNull
                                                                        String clientID,
                                                                        @NotNull
                                                                        Set<Topic> topics)

This method adds subscriptions for a certain client to certain topics. If HiveMQ is connected to a cluster, the subscription will be broadcast to all other Cluster Nodes.

Parameters:

clientID - client, which should be subscribed

topics - topics to which the client should be subscribed

Returns:

a ListenableFuture object that will succeed, as soon es the subscriptions were added by all Cluster Nodes. failing with a RateLimitExceededException if the plugin service rate limit was exceeded. failing with a InvalidTopicException if any topic is not utf-8 well-formed or empty. failing with a NoSuchClientIdException if a client does not exist.

Throws:

NullPointerException - if clientID or topics is null.

IllegalArgumentException - if clientID or topics is empty.

removeSubscription

com.google.common.util.concurrent.ListenableFuture<Void> removeSubscription(@NotNull
                                                                          String clientID,
                                                                          @NotNull
                                                                          String topic)

This method removes a subscription for a certain client and a certain topic. If HiveMQ is connected to a cluster, the subscription will be removed by other Cluster Nodes as well.

Parameters:

clientID - client, which should get unsubscribed

topic - topic from which the client should get unsubscribed

Returns:

a ListenableFuture object that will succeed, as soon es the subscription was removed by all Cluster Nodes. failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

removeSubscriptions

com.google.common.util.concurrent.ListenableFuture<Void> removeSubscriptions(@NotNull
                                                                           String clientID,
                                                                           @NotNull
                                                                           Set<String> topics)

This method removes subscriptions for a certain client and certain topics. If HiveMQ is connected to a cluster, the subscriptions will be removed by other Cluster Nodes as well.

Parameters:

clientID - client, which should get unsubscribed

topics - topics from which the client should get unsubscribed

Returns:

a ListenableFuture object that will succeed, as soon es the subscriptions were removed by all Cluster Nodes. failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

Throws:

NullPointerException - if clientID or topics is null.

IllegalArgumentException - if clientID or topics is empty.

getSubscriptions

@ReadOnly
com.google.common.util.concurrent.ListenableFuture<com.google.common.collect.Multimap<String,Topic>> getSubscriptions()

This method returns all subscriptions this HiveMQ instance and all other nodes in a HiveMQ cluster, as a Multimap of client identifiers and topics.

Please be aware that calling this method on HiveMQ instances with many subscriptions could have negative performance effects.

The returned Multimap is read-only and must not be modified.

Returns:

a ListenableFuture which contains a Multimap of client identifiers and their topic subscriptions failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

getSubscribers

@ReadOnly
com.google.common.util.concurrent.ListenableFuture<Set<String>> getSubscribers(@NotNull
                                                                                      String topic)

Returns all MQTT client subscriber identifiers for a given topic, this HiveMQ instance and all other nodes in a HiveMQ cluster. MQTT Wildcards are allowed.

Don't pass null as topic. This method is lenient, so it will just return an empty Set.

The returned Set is read-only and must not be modified.

Parameters:

topic - the topic

Returns:

a ListenableFuture which contains the client identifiers of all subscribers that subscribed to the topic failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

getTopics

@ReadOnly
com.google.common.util.concurrent.ListenableFuture<Set<Topic>> getTopics(@NotNull
                                                                                String clientID)

Returns all topics a client is subscribed to, on this HiveMQ instance and all other nodes in a HiveMQ cluster.

If the client does not exist, an empty Set is returned.

Don't pass null as clientId. This method is lenient, so it will just return an empty Set.

The returned Set is read-only and must not be modified.

Parameters:

clientID - of the client

Returns:

a ListenableFuture which contains which contains all topics the client subscribed to failing with a RateLimitExceededException if the plugin service rate limit was exceeded.