Package com.hivemq.extension.sdk.api.services.session

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 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 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

      • 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 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 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.

      • 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 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 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