diff --git a/tarantool-core/src/main/java/io/tarantool/core/connection/Connection.java b/tarantool-core/src/main/java/io/tarantool/core/connection/Connection.java index 23492369..e3d02b49 100644 --- a/tarantool-core/src/main/java/io/tarantool/core/connection/Connection.java +++ b/tarantool-core/src/main/java/io/tarantool/core/connection/Connection.java @@ -14,28 +14,114 @@ import io.tarantool.core.protocol.IProtoMessage; import io.tarantool.core.protocol.IProtoResponse; +/** An interface representing interaction with a Tarantool node via a connection abstraction. */ public interface Connection extends AutoCloseable { + /** + * Method for asynchronous connection to a Tarantool node. + * + * @param addr address at which the connection is being established + * @param timeoutMs timeout, specified in milliseconds, that defines the maximum wait time between + * the start of a connection attempt and the receipt of a greeting packet + * @return an instance of {@link CompletableFuture} that completes with a greeting or an error. + */ CompletableFuture connect(InetSocketAddress addr, long timeoutMs) throws IllegalStateException; + /** + * Asynchronously sends an {@link IProtoMessage} object to a Tarantool node. + * + * @param message the message to be sent to Tarantool. + * @return a {@link CompletableFuture} object. + * @throws IllegalStateException if the method is called when the connection is not in a state + * ready to send or receive messages. + */ CompletableFuture send(IProtoMessage message) throws IllegalStateException; + /** + * Registers a callback that will receive any {@link IProtoResponse} message arriving from a + * Tarantool node. + * + * @param listener A handler for responses from Tarantool. Must not be {@code null}. + * @return The same connection object on which this method was called. + * @implSpec Each subsequent call to this method will overwrite the previously registered handler. + * Not thread-safe. + * @apiNote Typically used when connection object are creating and not used thereafter. + */ Connection listen(Consumer listener); + /** + * A method that registers a callback to handle a connection-close event. + * + * @param event the connection-close event ({@link ConnectionCloseEvent}) for which the handler is + * being registered. + * @param handler the handler object. + * @implSpec If multiple handlers are provided for the same event, the implementation must + * register all of them, rather than replacing a previously registered handler with a new one. + * All callbacks are guaranteed to be invoked after the connection has transitioned to the + * closed state. + * @apiNote Typically used during the creation of a connection object and not used thereafter. + */ Connection onClose(ConnectionCloseEvent event, BiConsumer handler); + /** + * Gets greeting packet. + * + * @return {@link Optional#empty()} if this method was called before the connection reached a + * state ready. + */ Optional getGreeting(); + /** + * Checks whether the connection is currently active and ready to process requests. + * + *

Note that this status represents a snapshot in time. The connection state may change + * immediately after this method returns. + * + * @return {@code true} if the connection is currently in the ready state; {@code false} otherwise + */ boolean isConnected(); + /** + * Closes the connection reporting the close cause as a graceful shutdown of the server. + * + *

The method is meant to be called upon receiving the {@code box.shutdown} notification from + * Tarantool. At that moment the connection is still operational, it is the server that is about + * to terminate. + * + *

In contrast to {@link #close()}, the close is reported to the listeners as {@link + * ConnectionCloseEvent#CLOSE_BY_SHUTDOWN} rather than {@link + * ConnectionCloseEvent#CLOSE_BY_CLIENT}, and they are expected to react differently: a connection + * closed by the client needs no attention, while a connection closed by shutdown has to be + * replaced with a new one. The method itself does not reestablish the connection. + * + *

Requests pending on the connection are not failed by this method, the caller is responsible + * for cancelling them. The method does nothing if the connection is already closed or is being + * closed. + * + * @see Tarantool + * graceful shutdown + */ void shutdownClose(); + void setIdleTimeout(int idleTimeout); + + /** + * Method that pauses the reading of the buffer containing incoming data at the OS level for + * Netty. + */ void pause(); + /** + * Method that resumes the reading of the buffer containing incoming data at the OS level for + * Netty. + */ void resume(); - void setIdleTimeout(int idleTimeout); - + /** + * A method that checks whether automatic reading of a buffer with incoming data has been stopped + * at the OS level for Netty. + */ boolean isPaused(); } diff --git a/tarantool-core/src/main/java/io/tarantool/core/connection/ConnectionCloseEvent.java b/tarantool-core/src/main/java/io/tarantool/core/connection/ConnectionCloseEvent.java index b73b2ce3..27104858 100644 --- a/tarantool-core/src/main/java/io/tarantool/core/connection/ConnectionCloseEvent.java +++ b/tarantool-core/src/main/java/io/tarantool/core/connection/ConnectionCloseEvent.java @@ -5,9 +5,33 @@ package io.tarantool.core.connection; +/** {@link Connection} close events. */ public enum ConnectionCloseEvent { + + /** + * This event reflects a situation where the connection is closed from the network side—for + * example, due to a network disconnection. + */ CLOSE_BY_REMOTE, + + /** + * An event reflecting a situation where the connection has been closed by the client-side calling + * code. + */ CLOSE_BY_CLIENT, + + /** + * This event reflects a situation where a connection is closed from the Tarantool side via a call + * to {@code box.shutdown}. Unlike {@link #CLOSE_BY_REMOTE}, this event does not indicate network + * issues; rather, it signifies that a message has been received from a Tarantool node initiating + * a graceful shutdown. + * + * @see Tarantool + * documentation + */ CLOSE_BY_SHUTDOWN, + + /** An event representing a situation where a connection has been closed due to a timeout */ CLOSE_BY_TIMEOUT; }