Interface ClientService
-
@DoNotImplement public interface ClientService
Through this client service an extension can query details about connected or disconnected clients (with a persistent session) from the HiveMQ core.- Since:
- 4.0.0, CE 2019.1
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description @NotNull CompletableFuture<Boolean>
disconnectClient(@NotNull String clientId)
Forcefully disconnect a client with the specified clientId.@NotNull CompletableFuture<Boolean>
disconnectClient(@NotNull String clientId, boolean preventWillMessage)
Forcefully disconnect a client with the specified clientId.@NotNull CompletableFuture<Boolean>
disconnectClient(@NotNull String clientId, boolean preventWillMessage, @Nullable DisconnectReasonCode reasonCode, @Nullable String reasonString)
Forcefully disconnect a client with the specified clientId.@NotNull CompletableFuture<Optional<SessionInformation>>
getSession(@NotNull String clientId)
Returns additional client information about a given client with a given client identifier.@NotNull CompletableFuture<Boolean>
invalidateSession(@NotNull String clientId)
Invalidates the client session for a client with the given client identifier.@NotNull CompletableFuture<Boolean>
isClientConnected(@NotNull 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.@NotNull CompletableFuture<Void>
iterateAllClients(@NotNull IterationCallback<SessionInformation> callback)
Iterate over all clients and their session information in the HiveMQ cluster.@NotNull CompletableFuture<Void>
iterateAllClients(@NotNull IterationCallback<SessionInformation> callback, @NotNull Executor callbackExecutor)
Iterate over all clients and their session information in the HiveMQ cluster.
-
-
-
Method Detail
-
isClientConnected
@NotNull CompletableFuture<Boolean> isClientConnected(@NotNull 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.CompletableFuture
fails with aRateLimitExceededException
if the extension service rate limit was exceeded.- Parameters:
clientId
- The client identifier of the client.- Returns:
- A
CompletableFuture
which containstrue
, if a certain client is currently connected andfalse
otherwise. - Since:
- 4.0.0, CE 2019.1
-
getSession
@NotNull CompletableFuture<Optional<SessionInformation>> getSession(@NotNull 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.
CompletableFuture
fails with aRateLimitExceededException
if the extension service rate limit was exceeded.- Parameters:
clientId
- The client identifier of the client.- Returns:
- A
CompletableFuture
which contains theSessionInformation
for the client, if the session exist. - Since:
- 4.0.0, CE 2019.1
-
disconnectClient
@NotNull CompletableFuture<Boolean> disconnectClient(@NotNull String clientId)
Forcefully disconnect a client with the specified clientId.If the client specified a Will message, it will be sent. To prevent the sending of Will messages, use the
disconnectClient(String, boolean)
method.CompletableFuture
fails with aRateLimitExceededException
if the extension service rate limit was exceeded.- Parameters:
clientId
- The client identifier of the client to disconnect.- Returns:
- A
CompletableFuture
which contains aBoolean
that istrue
when the client has been disconnected andfalse
if no client with that id was found. - Since:
- 4.0.0, CE 2019.1
-
disconnectClient
@NotNull CompletableFuture<Boolean> disconnectClient(@NotNull String clientId, boolean preventWillMessage)
Forcefully disconnect a client with the specified clientId.If a specific reason code and/or reason string should be sent with the DISCONNECT packet use
disconnectClient(String, boolean, DisconnectReasonCode, String)
.Setting the boolean parameter to true will prevent the sending of potential Will messages the client may have specified in its CONNECT packet.
CompletableFuture
fails with aRateLimitExceededException
if the extension service rate limit was exceeded.- Parameters:
clientId
- The client identifier of the client to disconnect.preventWillMessage
- Iftrue
the Will message for this client is not published when the client gets disconnected.- Returns:
- A
CompletableFuture
which contains aBoolean
that istrue
when the client has been disconnected andfalse
if no client with that id was found. - Since:
- 4.0.0, CE 2019.1
-
disconnectClient
@NotNull CompletableFuture<Boolean> disconnectClient(@NotNull String clientId, boolean preventWillMessage, @Nullable DisconnectReasonCode reasonCode, @Nullable String reasonString)
Forcefully disconnect a client with the specified clientId.A specific reason code and/or reason string can be set when wanted.
Setting the boolean parameter to true will prevent the sending of potential Will messages the client may have specified in its CONNECT packet.
CompletableFuture
fails with aRateLimitExceededException
if the extension service rate limit was exceeded.- Parameters:
clientId
- The client identifier of the client to disconnect.preventWillMessage
- Iftrue
the Will message for this client is not published when the client gets disconnected.reasonCode
- The reason code for disconnecting this client.reasonString
- The user defined reason string for disconnecting this client.- Returns:
- A
CompletableFuture
which contains aBoolean
that istrue
when the client has been disconnected andfalse
if no client with that id was found. - Throws:
IllegalArgumentException
- If the disconnect reason code must not be used for outbound disconnect packets from the server to a client.- Since:
- 4.3.0, CE 2020.1
- See Also:
What reason codes exist for outbound disconnect packets from the server to a client.
-
invalidateSession
@NotNull CompletableFuture<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.CompletableFuture
fails with aRateLimitExceededException
if the extension service rate limit was exceeded.CompletableFuture
fails with aNoSuchClientIdException
if no session for the given clientId exists.- Parameters:
clientId
- The client identifier of the client which session should be invalidated.- Returns:
- A
CompletableFuture
succeeding with aBoolean
that istrue
when the client has been actively disconnected by the broker otherwisefalse
. - Since:
- 4.0.0, CE 2019.1
-
iterateAllClients
@NotNull CompletableFuture<Void> iterateAllClients(@NotNull IterationCallback<SessionInformation> callback)
Iterate over all clients and their session information in the HiveMQ cluster.The callback is called once for each client. Passed to each execution of the callback are the client identifier and its session information. Clients that have exceeded their session expiry interval are not included.
The callback is executed in the
ManagedExtensionExecutorService
per default. Use the overloaded methods to pass a custom executor for the callback. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection (thread-safe), as the callback might be executed in another thread as the calling thread of this method.The results are not sorted in any way, no ordering of any kind is guaranteed.
CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.
If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling
IterationContext.abortIteration()
.CompletableFuture
fails with anIncompatibleHiveMQVersionException
if not all HiveMQ nodes in the cluster have at least version 4.2.0.CompletableFuture
fails with aRateLimitExceededException
if the extension service rate limit was exceeded.CompletableFuture
fails with aIterationFailedException
if the cluster topology changed during the iteration (e.g. a network-split, node leave or node join)- Parameters:
callback
- AnIterationCallback
that is called for every returned result.- Returns:
- A
CompletableFuture
that is completed after all iterations are executed, no match is found or the iteration is aborted manually with theIterationContext
. - Throws:
NullPointerException
- If the passed callback is null.- Since:
- 4.2.0, CE 2020.1
-
iterateAllClients
@NotNull CompletableFuture<Void> iterateAllClients(@NotNull IterationCallback<SessionInformation> callback, @NotNull Executor callbackExecutor)
Iterate over all clients and their session information in the HiveMQ cluster.The callback is called once for each client. Passed to each execution of the callback are the client identifier and its session information. Clients that have exceeded their session expiry interval are not included.
The callback is executed in the passed
Executor
. If you want to collect the results of each execution of the callback in a collection please make sure to use a concurrent collection, as the callback might be executed in another thread as the calling thread of this method.The results are not sorted in any way, no ordering of any kind is guaranteed.
CAUTION: This method can be used in large scale deployments, but it is a very expensive operation. Do not call this method in short time intervals.
If you are searching for a specific entry in the results and have found what you are looking for, you can abort further iteration and save resources by calling
IterationContext.abortIteration()
.CompletableFuture
fails with anIncompatibleHiveMQVersionException
if not all HiveMQ nodes in the cluster have at least version 4.2.0.CompletableFuture
fails with aRateLimitExceededException
if the extension service rate limit was exceeded.CompletableFuture
fails with aIterationFailedException
if the cluster topology changed during the iteration (e.g. a network-split, node leave or node join)- Parameters:
callback
- AnIterationCallback
that is called for every returned result.callbackExecutor
- AnExecutor
in which the callback for each iteration is executed.- Returns:
- A
CompletableFuture
that is completed after all iterations are executed, no match is found or the iteration is aborted manually with theIterationContext
. - Throws:
NullPointerException
- If the passed callback or callbackExecutor are null.- Since:
- 4.2.0, CE 2020.1
-
-