@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

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 Details
- isClientConnected
  
  @NotNull @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 a RateLimitExceededException if the extension service rate limit was exceeded.
  
  Parameters:
  
  clientId - The client identifier of the client.
  
  Returns:
  
  A CompletableFuture which contains true, if a certain client is currently connected and false otherwise.
  
  Since:
  
  4.0.0, CE 2019.1
- getSession
  
  @NotNull @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 a RateLimitExceededException if the extension service rate limit was exceeded.
  
  Parameters:
  
  clientId - The client identifier of the client.
  
  Returns:
  
  A CompletableFuture which contains the SessionInformation for the client, if the session exist.
  
  Since:
  
  4.0.0, CE 2019.1
- disconnectClient
  
  @NotNull @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 a RateLimitExceededException if the extension service rate limit was exceeded.
  
  Parameters:
  
  clientId - The client identifier of the client to disconnect.
  
  Returns:
  
  A CompletableFuture which contains a Boolean that is true when the client has been disconnected and false if no client with that id was found.
  
  Since:
  
  4.0.0, CE 2019.1
- disconnectClient
  
  @NotNull @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 a RateLimitExceededException if the extension service rate limit was exceeded.
  
  Parameters:
  
  clientId - The client identifier of the client to disconnect.
  
  preventWillMessage - If true the Will message for this client is not published when the client gets disconnected.
  
  Returns:
  
  A CompletableFuture which contains a Boolean that is true when the client has been disconnected and false if no client with that id was found.
  
  Since:
  
  4.0.0, CE 2019.1
- disconnectClient
  
  @NotNull @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 a RateLimitExceededException if the extension service rate limit was exceeded.
  
  Parameters:
  
  clientId - The client identifier of the client to disconnect.
  
  preventWillMessage - If true 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 a Boolean that is true when the client has been disconnected and false 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 @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 a RateLimitExceededException if the extension service rate limit was exceeded.
  CompletableFuture fails with a NoSuchClientIdException 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 a Boolean that is true when the client has been actively disconnected by the broker otherwise false.
  
  Since:
  
  4.0.0, CE 2019.1
- iterateAllClients
  
  @NotNull @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 an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded. CompletableFuture fails with a IterationFailedException if the cluster topology changed during the iteration (e.g. a network-split, node leave or node join)
  
  Parameters:
  
  callback - An IterationCallback 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 the IterationContext.
  
  Throws:
  
  NullPointerException - If the passed callback is null.
  
  Since:
  
  4.2.0, CE 2020.1
- iterateAllClients
  
  @NotNull @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 an IncompatibleHiveMQVersionException if not all HiveMQ nodes in the cluster have at least version 4.2.0. CompletableFuture fails with a RateLimitExceededException if the extension service rate limit was exceeded. CompletableFuture fails with a IterationFailedException if the cluster topology changed during the iteration (e.g. a network-split, node leave or node join)
  
  Parameters:
  
  callback - An IterationCallback that is called for every returned result.
  
  callbackExecutor - An Executor 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 the IterationContext.
  
  Throws:
  
  NullPointerException - If the passed callback or callbackExecutor are null.
  
  Since:
  
  4.2.0, CE 2020.1

Interface ClientService

Method Summary

Method Details