com.hivemq.extension.sdk.api.services.session.ClientService Maven / Gradle / Ivy
Show all versions of hivemq-extension-sdk Show documentation
/*
* Copyright 2018-present HiveMQ GmbH
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.hivemq.extension.sdk.api.services.session;
import com.hivemq.extension.sdk.api.annotations.DoNotImplement;
import com.hivemq.extension.sdk.api.annotations.NotNull;
import com.hivemq.extension.sdk.api.annotations.Nullable;
import com.hivemq.extension.sdk.api.packets.disconnect.DisconnectReasonCode;
import com.hivemq.extension.sdk.api.services.ManagedExtensionExecutorService;
import com.hivemq.extension.sdk.api.services.exception.IncompatibleHiveMQVersionException;
import com.hivemq.extension.sdk.api.services.exception.IterationFailedException;
import com.hivemq.extension.sdk.api.services.exception.NoSuchClientIdException;
import com.hivemq.extension.sdk.api.services.exception.RateLimitExceededException;
import com.hivemq.extension.sdk.api.services.general.IterationCallback;
import com.hivemq.extension.sdk.api.services.general.IterationContext;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executor;
/**
* Through this client service an extension can query details about connected or disconnected clients (with a persistent
* session) from the HiveMQ core.
*
* @author Lukas Brandl
* @author Christoph Schäbel
* @author Florian Limpöck
* @author Robin Atherton
* @since 4.0.0, CE 2019.1
*/
@DoNotImplement
public interface ClientService {
/**
* Check if a client with a given identifier is currently connected to this HiveMQ broker instance or any other
* instance in the cluster.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* @param clientId The client identifier of the client.
* @return A {@link CompletableFuture} which contains true, if a certain client is currently connected
* and false otherwise.
* @since 4.0.0, CE 2019.1
*/
@NotNull CompletableFuture isClientConnected(@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.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* @param clientId The client identifier of the client.
* @return A {@link CompletableFuture} which contains the {@link SessionInformation} for the client, if the session
* exist.
* @since 4.0.0, CE 2019.1
*/
@NotNull CompletableFuture> getSession(@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
* {@link #disconnectClient(String, boolean)} method.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* @param clientId The client identifier of the client to disconnect.
* @return A {@link CompletableFuture} which contains a {@link 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
*/
@NotNull CompletableFuture disconnectClient(@NotNull String clientId);
/**
* 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
* {@link ClientService#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.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* @param clientId The client identifier of the client to disconnect.
* @param preventWillMessage If true the Will message for this client is not published when the client
* gets disconnected.
* @return A {@link CompletableFuture} which contains a {@link 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
*/
@NotNull CompletableFuture disconnectClient(@NotNull String clientId, boolean preventWillMessage);
/**
* 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.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* @param clientId The client identifier of the client to disconnect.
* @param preventWillMessage If true the Will message for this client is not published when the client
* gets disconnected.
* @param reasonCode The reason code for disconnecting this client.
* @param reasonString The user defined reason string for disconnecting this client.
* @return A {@link CompletableFuture} which contains a {@link 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.
* @see DisconnectReasonCode What reason codes exist for outbound disconnect packets from the server to a
* client.
* @since 4.3.0, CE 2020.1
*/
@NotNull CompletableFuture disconnectClient(
@NotNull String clientId,
boolean preventWillMessage,
@Nullable DisconnectReasonCode reasonCode,
@Nullable String reasonString);
/**
* Invalidates the client session for a client with the given client identifier. If the client is currently
* connected, it will be disconnected as well.
*
* {@link CompletableFuture} fails with a {@link RateLimitExceededException} if the extension service rate limit was
* exceeded.
*
* {@link CompletableFuture} fails with a {@link NoSuchClientIdException} if no session for the given clientId
* exists.
*
* @param clientId The client identifier of the client which session should be invalidated.
* @return A {@link CompletableFuture} succeeding with a {@link Boolean} that is true when the client
* has been actively disconnected by the broker otherwise false.
* @since 4.0.0, CE 2019.1
*/
@NotNull CompletableFuture invalidateSession(@NotNull String clientId);
/**
* 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 {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded. {@link CompletableFuture} fails with a
* {@link IterationFailedException} if the cluster topology changed during the iteration (e.g. a network-split, node
* leave or node join)
*
* @param callback An {@link IterationCallback} that is called for every returned result.
* @return A {@link CompletableFuture} that is completed after all iterations are executed, no match is found or the
* iteration is aborted manually with the {@link IterationContext}.
* @throws NullPointerException If the passed callback is null.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllClients(@NotNull IterationCallback 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 passed {@link 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 {@link IterationContext#abortIteration()}.
*
* {@link CompletableFuture} fails with an {@link IncompatibleHiveMQVersionException} if not all HiveMQ nodes in the
* cluster have at least version 4.2.0. {@link CompletableFuture} fails with a {@link RateLimitExceededException} if
* the extension service rate limit was exceeded. {@link CompletableFuture} fails with a
* {@link IterationFailedException} if the cluster topology changed during the iteration (e.g. a network-split, node
* leave or node join)
*
* @param callback An {@link IterationCallback} that is called for every returned result.
* @param callbackExecutor An {@link Executor} in which the callback for each iteration is executed.
* @return A {@link CompletableFuture} that is completed after all iterations are executed, no match is found or the
* iteration is aborted manually with the {@link IterationContext}.
* @throws NullPointerException If the passed callback or callbackExecutor are null.
* @since 4.2.0, CE 2020.1
*/
@NotNull CompletableFuture iterateAllClients(
@NotNull IterationCallback callback, @NotNull Executor callbackExecutor);
}