com.devexperts.qd.qtp.socket

Interface SocketSource

@Experimental
public interface SocketSource

SocketSource encapsulates a network address resolution and load-balancing logic for the connector.

Usually SocketSource is bound to a series of connections with the same "scope" inside a connector. For example, client-side connectors use a separate SocketSource instance for connections assigned to a particular stripe.

Method Summary

Modifier and Type	Method and Description
default void	close() Closes this socket source and releases any resources associated with it.
default void	closeSocket(SocketInfo socketInfo, Throwable reason) Handle closing of a previously returned socket.
SocketInfo	getSocket() Retrieves the next available socket information for establishing a connection.
default void	markForImmediateRestart() Marks the socket source for an immediate restart, signaling that connections associated with this socket source should be re-established as soon as possible.
default boolean	shouldRestoreConnection(SocketInfo socketInfo) Checks if the current connection (last invocation of getSocket()) is preferred by this socket source policy and prepares reconnecting if not.

Method Detail

getSocket

SocketInfo getSocket()
              throws InterruptedException

Retrieves the next available socket information for establishing a connection. This method may block the calling thread if a socket is not immediately available (for example, if the socket source policy requires a cool-down period between reconnection attempts). Returned socket should be ready to use by an associated connection protocol. If some initial handshake communication is required (like for a ClientSocketConnector with configured proxy), it should be successfully performed before the method is returned.

Returns:

the next SocketInfo instance containing the socket and its corresponding address. May return null if the current attempt has failed or the close() was invoked concurrently.

Throws:

InterruptedException - if the thread is interrupted while waiting for a socket to become available.

closeSocket

default void closeSocket(SocketInfo socketInfo,
                         @Nullable
                         Throwable reason)
                  throws IOException

Handle closing of a previously returned socket. Invoked when the connector releases a socket returned by the socket source.

Parameters:

socketInfo - SocketInfo object previously returned by the socket source

reason - an optional exception that caused the socket closing

Throws:

IOException

Implementation Requirements:

It's expected that the implementation will handle the socket shutdown and finally close the socket.

NOTE: Socket maybe be already closed before the method is invoked, and implementation shall support it.

markForImmediateRestart

default void markForImmediateRestart()

Marks the socket source for an immediate restart, signaling that connections associated with this socket source should be re-established as soon as possible.

This method is particularly useful in scenarios where the current state of connections managed by the socket source is no longer valid or requires a refresh, such as in response to network topology changes or application logic that mandates reinitialization.

Calling this method does not immediately terminate or restart any existing connections; it merely flags the socket source for a restart process to occur at the earliest opportunity, and next invocation of getSocket() should return a socket without artificial delay.

Implementation Requirements:

implementation of the method shall be safe for asynchronous invocation

shouldRestoreConnection

default boolean shouldRestoreConnection(@Nullable
                                        SocketInfo socketInfo)

Checks if the current connection (last invocation of getSocket()) is preferred by this socket source policy and prepares reconnecting if not.

This method is used by connectors supporting a restoring connection to a preferred counter-party. If method returns true, the connector will reestablish connection and expect that next invocation of getSocket() returns a socket connected to a preferred address.

The exact implementation of the check and reset logic may depend on the specific requirements of the socket source implementation.

Parameters:

socketInfo - optional SocketInfo corresponding to the current established connection

Returns:

true if the current connection needs to be reestablished; false otherwise.

Implementation Requirements:

implementation of the method shall be safe for asynchronous invocation

close

default void close()

Closes this socket source and releases any resources associated with it.

After calling this method, the socket source is considered terminated, and any attempts to retrieve sockets with getSocket() should return null.

If the socket source is already closed, subsequent calls to this method have no effect.

Implementation Requirements:

implementation of the method shall be safe for asynchronous invocation. Specifically, close method may be invoked concurrently with getSocket(), closeSocket(com.devexperts.qd.qtp.socket.SocketInfo, java.lang.Throwable) or shouldRestoreConnection(com.devexperts.qd.qtp.socket.SocketInfo) invocation. Stale connections may invoke closeSocket(com.devexperts.qd.qtp.socket.SocketInfo, java.lang.Throwable) for an already closed socket source.