com.hivemq.spi.services

Interface BlockingSubscriptionStore

public interface BlockingSubscriptionStore

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

Since:

3.1

Author:

Lukas Brandl

Method Summary

Methods

Modifier and Type	Method and Description
void	addSubscription(String clientID, Topic topic) This method adds a subscription for a certain client to a certain topic.
void	addSubscriptions(String clientID, Set<Topic> topics) This method adds subscriptions for a certain client to certain topics.
Set<String>	getLocalSubscribers(String topic) Returns all MQTT client subscriber identifiers for a given topic, for this HiveMQ instance.
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.
Set<Topic>	getLocalTopics(String clientID) Returns all topics a client is subscribed to, on this HiveMQ instance.
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.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.
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.
void	removeSubscription(String clientID, String topic) This method removes a subscription for a certain client and a certain topic.
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.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 Multimap of client identifiers and their topic subscriptions

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

getLocalSubscribers

@ReadOnly
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:

client identifiers of all subscribers that subscribed to the topic

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

getLocalTopics

@ReadOnly
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:

all topics the client subscribed to

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

addSubscription

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

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

addSubscriptions

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

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

InvalidTopicException - if any topic is not utf-8 well-formed or empty.

NoSuchClientIdException - if a client does not exist.

NullPointerException - if clientID or topics is null.

IllegalArgumentException - if clientID or topics is empty.

removeSubscription

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

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

removeSubscriptions

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 subscription 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

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

NullPointerException - if clientID or topics is null.

IllegalArgumentException - if clientID or topics is empty.

getSubscriptions

@ReadOnly
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 Multimap of client identifiers and their topic subscriptions

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

getSubscribers

@ReadOnly
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:

client identifiers of all subscribers that subscribed to the topic

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

getTopics

@ReadOnly
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:

all topics the client subscribed to

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.