com.hivemq.spi.services.AsyncSubscriptionStore Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of hivemq-spi Show documentation
Show all versions of hivemq-spi Show documentation
The Service Provider Interfaces for developing HiveMQ plugins.
/*
* Copyright 2014 dc-square 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.spi.services;
import com.google.common.collect.Multimap;
import com.google.common.util.concurrent.ListenableFuture;
import com.hivemq.spi.annotations.NotNull;
import com.hivemq.spi.annotations.ReadOnly;
import com.hivemq.spi.message.Topic;
import java.util.Set;
/**
* The subscription store allows the management of all client subscriptions from within a plugin
*
* @author Lukas Brandl
* @since 3.1
*/
public interface AsyncSubscriptionStore {
/**
* This method returns all subscriptions on this HiveMQ Node as a {@link com.google.common.collect.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.
*
* @return a {@link com.google.common.util.concurrent.ListenableFuture} which contains a {@link com.google.common.collect.Multimap} of client identifiers and their topic subscriptions
*/
@ReadOnly
ListenableFuture> getLocalSubscriptions();
/**
* 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.
*
* @param topic the topic
* @return a {@link com.google.common.util.concurrent.ListenableFuture} which contains the client identifiers of all subscribers that subscribed to the topic
*/
@ReadOnly
ListenableFuture> getLocalSubscribers(@NotNull String topic);
/**
* 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.
*
* @param clientID of the client
* @return a {@link com.google.common.util.concurrent.ListenableFuture} which contains all topics the client subscribed to
*/
@ReadOnly
ListenableFuture> getLocalTopics(@NotNull String clientID);
/**
* 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.
*
* @param clientID client, which should be subscribed
* @param topic topic to which the client should be subscribed
* @return A {@link com.google.common.util.concurrent.ListenableFuture} object that will succeed,
* as soon es the subscription was added by all Cluster Nodes.
*/
ListenableFuture addSubscription(@NotNull String clientID, @NotNull Topic 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.
*
* @param clientID client, which should get unsubscribed
* @param topic topic from which the client should get unsubscribed
* @return A {@link com.google.common.util.concurrent.ListenableFuture} object that will succeed,
* as soon es the subscription was removed by all Cluster Nodes.
*/
ListenableFuture removeSubscription(@NotNull String clientID, @NotNull String topic);
/**
* This method returns all subscriptions this HiveMQ instance and all other nodes in a HiveMQ cluster,
* as a {@link com.google.common.collect.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.
*
* @return a {@link com.google.common.util.concurrent.ListenableFuture} which contains a {@link com.google.common.collect.Multimap} of client identifiers and their topic subscriptions
*/
@ReadOnly
ListenableFuture> getSubscriptions();
/**
* 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.
*
* @param topic the topic
* @return a {@link com.google.common.util.concurrent.ListenableFuture} which contains the client identifiers of all subscribers that subscribed to the topic
*/
@ReadOnly
ListenableFuture> getSubscribers(@NotNull String topic);
/**
* 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.
*
* @param clientID of the client
* @return a {@link com.google.common.util.concurrent.ListenableFuture} which contains which contains all topics the client subscribed to
*/
@ReadOnly
ListenableFuture> getTopics(@NotNull String clientID);
}