com.hivemq.spi.services

Interface BlockingClientService

public interface BlockingClientService

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
boolean	disconnectClient(String clientId) Forcefully disconnect a client with the specified clientId.
boolean	disconnectClient(String clientId, boolean preventLwtMessage) Forcefully disconnect a client with the specified clientId.
ClientData	getClientData(String clientId) Returns additional client information about a given client with a given client identifier.
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.
Set<String>	getDisconnectedClients() Returns all disconnected clients which have a persistent MQTT session on this broker or any other cluster node.
ClientData	getLocalClientData(String clientId) Returns client information for clients that are connected to this broker instance.
Set<String>	getLocalConnectedClients() Returns all identifiers of connected clients of this HiveMQ Node.
Set<String>	getLocalDisconnectedClients() Returns all disconnected clients which have a persistent MQTT session on this instance of HiveMQ (MQTT clean session=false).
int	getTTL(String clientId) Returns the time to live for a client session in seconds.
void	invalidateSession(String clientId) Invalidates the client session for the client with the given client identifier.
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.
boolean	isClientConnectedLocal(String clientId) Check if a client with a given identifier is currently connected to this HiveMQ instance.
void	setTTL(String clientId, int ttl) Sets the time to live for the client session.

Method Detail

getLocalConnectedClients

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:

client identifiers of all connected clients

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

getLocalDisconnectedClients

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:

all disconnected clients with a persistent MQTT session

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

isClientConnectedLocal

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:

true, if a certain client is currently connected and false otherwise

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

getLocalClientData

@Nullable
ClientData getLocalClientData(String clientId)

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

If the client isn't connected, null will be returned.

Parameters:

clientId - the client identifier of the client

Returns:

ClientData for a specific client or null if the client is not connected

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

getConnectedClients

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:

client identifiers of all connected clients

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

getDisconnectedClients

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:

all disconnected clients with a persistent MQTT session

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

isClientConnected

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:

true, if a certain client is currently connected and false otherwise

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

getClientData

@Nullable
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, null will be returned.

Parameters:

clientId - the client identifier of the client

Returns:

ClientData for a specific client or null if the client is not connected

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

disconnectClient

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:

true if the client has been disconnected, false if no client with that id was found

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

Since:

3.2

disconnectClient

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 false

Parameters:

clientId - the clientId to disconnect

preventLwtMessage - if true the LWT message for this client is not sent

Returns:

true if the client has been disconnected, false if no client with that id was found

Throws:

RateLimitExceededException - if the plugin service rate limit was exceeded.

Since:

3.2

setTTL

void setTTL(@NotNull
          String clientId,
          int ttl)
            throws NoSuchClientIdException

Sets the time to live for the client session. A TTL value of -1 results in the session never expiring. Attention: The given TTL may be overwritten at client reconnection.

Parameters:

clientId - the client identifier of the client

ttl - time to live for a client session in seconds

Throws:

NoSuchClientIdException - if no session for the given clientId exists

IncompatibleHiveMQVersionException - if a node with a version lower than 3.4 exists in the cluster

InvalidTTLException - if the given TTL is invalid (< -1)

Since:

3.4

getTTL

int getTTL(@NotNull
         String clientId)
           throws NoSuchClientIdException

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

A value of -1 for the TTL means that the session never expires.

Parameters:

clientId - the client identifier of the client

Returns:

ttl time to live for the client session in seconds

Throws:

NoSuchClientIdException - if no session for the given clientId exists

com.hivemq.spi.services.exception.IncompatibleHiveMQVersionException} - if a node with a version lower than 3.4 exists in the cluster

Since:

3.4

invalidateSession

void invalidateSession(@NotNull
                     String clientId)
                       throws NoSuchClientIdException

Invalidates the client session for the 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 whose session should be invalidated

Throws:

NoSuchClientIdException - if no session for the given clientId exists

com.hivemq.spi.services.exception.IncompatibleHiveMQVersionException} - if a node with a version lower than 3.4 exists in the cluster

Since:

3.4