com.hivemq.spi.services

Interface AsyncClientService

public interface AsyncClientService

Through this client service a plugin can query details about connected or disconnected clients (with a persistent session) from the HiveMQ core.

Since:

3.1

Author:

Lukas Brandl

Method Summary

Methods

Modifier and Type	Method and Description
com.google.common.util.concurrent.ListenableFuture<Boolean>	disconnectClient(String clientId) Forcefully disconnect a client with the specified clientId.
com.google.common.util.concurrent.ListenableFuture<Boolean>	disconnectClient(String clientId, boolean preventLwtMessage) Forcefully disconnect a client with the specified clientId.
com.google.common.util.concurrent.ListenableFuture<ClientData>	getClientData(String clientId) Returns additional client information about a given client with a given client identifier.
com.google.common.util.concurrent.ListenableFuture<Set<String>>	getConnectedClients() Returns all identifiers of connected clients of this HiveMQ instance and all other nodes in a HiveMQ cluster Calling this method frequently in a clustered environment could have negative performance effects.
com.google.common.util.concurrent.ListenableFuture<Set<String>>	getDisconnectedClients() Returns all disconnected clients which have a persistent MQTT session on this broker or any other cluster node.
com.google.common.util.concurrent.ListenableFuture<ClientData>	getLocalClientData(String clientId) Returns client information for clients that are connected to this broker instance.
com.google.common.util.concurrent.ListenableFuture<Set<String>>	getLocalConnectedClients() Returns all identifiers of connected clients of this HiveMQ Node.
com.google.common.util.concurrent.ListenableFuture<Set<String>>	getLocalDisconnectedClients() Returns all disconnected clients which have a persistent MQTT session on this instance of HiveMQ (MQTT clean session=false).
com.google.common.util.concurrent.ListenableFuture<Integer>	getTTL(String clientId) Returns the time to live for a client session in seconds.
com.google.common.util.concurrent.ListenableFuture<Boolean>	invalidateSession(String clientId) Invalidates the client session for a client with the given client identifier.
com.google.common.util.concurrent.ListenableFuture<Boolean>	isClientConnected(String clientId) Check if a client with a given identifier is currently connected to this HiveMQ broker instance or any other instance in the cluster.
com.google.common.util.concurrent.ListenableFuture<Boolean>	isClientConnectedLocal(String clientId) Check if a client with a given identifier is currently connected to this HiveMQ instance.
com.google.common.util.concurrent.ListenableFuture<Void>	setTTL(String clientId, int ttl) Sets the time to live for a client session in seconds.

Method Detail

getLocalConnectedClients

com.google.common.util.concurrent.ListenableFuture<Set<String>> getLocalConnectedClients()

Returns all identifiers of connected clients of this HiveMQ Node. You won't receive client identifiers of connected clients from other HiveMQ nodes if HiveMQ runs in a cluster.

If you have many client connections, please note that calling this method frequently could have negative performance effects.

Returns:

a ListenableFuture which contains all client identifiers of all connected clients failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

getLocalDisconnectedClients

com.google.common.util.concurrent.ListenableFuture<Set<String>> getLocalDisconnectedClients()

Returns all disconnected clients which have a persistent MQTT session on this instance of HiveMQ (MQTT clean session=false).

Disconnected MQTT clients which don't have a persistent session won't be returned by this method

Returns:

a ListenableFuture which contains the client identifiers of all disconnected clients with a persistent MQTT session failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

isClientConnectedLocal

com.google.common.util.concurrent.ListenableFuture<Boolean> isClientConnectedLocal(String clientId)

Check if a client with a given identifier is currently connected to this HiveMQ instance.

Parameters:

clientId - client, which should be checked

Returns:

a ListenableFuture which contains true, if a certain client is currently connected and false otherwise failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

getLocalClientData

com.google.common.util.concurrent.ListenableFuture<ClientData> getLocalClientData(String clientId)

Returns client information for clients that are connected to this broker instance.

If the client isn't connected, you will receive an Optional with absent data.

Parameters:

clientId - the client identifier of the client

Returns:

a ListenableFuture which contains the ClientData for a specific client. failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

getConnectedClients

com.google.common.util.concurrent.ListenableFuture<Set<String>> getConnectedClients()

Returns all identifiers of connected clients of this HiveMQ instance and all other nodes in a HiveMQ cluster

Calling this method frequently in a clustered environment could have negative performance effects.

Returns:

a ListenableFuture which contains the client identifiers of all connected clients failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

getDisconnectedClients

com.google.common.util.concurrent.ListenableFuture<Set<String>> getDisconnectedClients()

Returns all disconnected clients which have a persistent MQTT session on this broker or any other cluster node.

Disconnected MQTT clients which don't have a persistent session won't be returned by this method

Returns:

a ListenableFuture which contains the of client identifiers of all disconnected clients with a persistent MQTT session failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

isClientConnected

com.google.common.util.concurrent.ListenableFuture<Boolean> isClientConnected(String clientId)

Check if a client with a given identifier is currently connected to this HiveMQ broker instance or any other instance in the cluster.

Parameters:

clientId - client, which should be checked

Returns:

a ListenableFuture which contains true, if a certain client is currently connected and false otherwise failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

getClientData

com.google.common.util.concurrent.ListenableFuture<ClientData> getClientData(String clientId)

Returns additional client information about a given client with a given client identifier.

This method will also get client information from other cluster nodes if needed.

If the client isn't connected, you will receive null.

Parameters:

clientId - the client identifier of the client

Returns:

a ListenableFuture which contains the ClientData for a specific client. failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

disconnectClient

com.google.common.util.concurrent.ListenableFuture<Boolean> disconnectClient(String clientId)

Forcefully disconnect a client with the specified clientId.

If the client specified a LWT message, it will be sent. To prevent LWT messages use the disconnectClient(String, boolean) method

Parameters:

clientId - the clientId to disconnect

Returns:

a ListenableFuture which contains a Boolean which is true when the client has been disconnected and false if no client with that id was found. failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

Since:

3.2

disconnectClient

com.google.common.util.concurrent.ListenableFuture<Boolean> disconnectClient(String clientId,
                                                                           boolean preventLwtMessage)

Forcefully disconnect a client with the specified clientId.

If the client specified a LWT message it will only be sent if the boolean parameter is set to false.

Parameters:

clientId - the clientId to disconnect

preventLwtMessage - if true the LWT message for this client is not published when the client gets disconnected

Returns:

a ListenableFuture which contains a Boolean which is true when the client has been disconnected and false if no client with that id was found. failing with a RateLimitExceededException if the plugin service rate limit was exceeded.

Since:

3.2

setTTL

com.google.common.util.concurrent.ListenableFuture<Void> setTTL(@NotNull
                                                              String clientId,
                                                              int ttl)

Sets the time to live for a client session in seconds. Session expiry can be disabled by setting the session time to live to -1. Attention: The given TTL may be overwritten when a client (re-)connects.

Parameters:

clientId - the client identifier of the client

ttl - time to live for the client session in seconds

Returns:

a ListenableFuture which succeeds when the TTL is set successfully, failing with a NoSuchClientIdException if no session for the given clientId exists, failing with a IncompatibleHiveMQVersionException if a node with a version lower than 3.4 exists in the cluster, failing with a InvalidTTLException if the given TTL is invalid (< -1).

Since:

3.4

getTTL

com.google.common.util.concurrent.ListenableFuture<Integer> getTTL(@NotNull
                                                                 String clientId)

Returns the time to live for a client session in seconds.

A value of -1 for the TTL means that session expiry is disabled.

Parameters:

clientId - the client identifier of the client

Returns:

a ListenableFuture succeeding with the client session TTL in seconds, failing with a NoSuchClientIdException if no session for the given clientId exists, failing with a IncompatibleHiveMQVersionException if a node with a version lower than 3.4 exists in the cluster.

Since:

3.4

invalidateSession

com.google.common.util.concurrent.ListenableFuture<Boolean> invalidateSession(@NotNull
                                                                            String clientId)

Invalidates the client session for a client with the given client identifier. If the client is currently connected, it will be disconnected as well.

Sets time to live to 0. Attention: The given TTL of 0 may be overwritten at client reconnection.

Parameters:

clientId - the client identifier of the client which session should be invalidated

Returns:

a ListenableFuture succeeding with a Boolean which is true when the client has been actively disconnected by the broker otherwise false, failing with a NoSuchClientIdException if no session for the given clientId exists, failing with a IncompatibleHiveMQVersionException if a node with a version lower than 3.4 exists in the cluster.

Since:

3.4