Package io.servicetalk.transport.api

Interface ConnectionObserver

All Known Implementing Classes:

NoopTransportObserver.NoopConnectionObserver

public interface ConnectionObserver

An observer interface that provides visibility into events associated with a network connection.

Either connectionClosed() or connectionClosed(Throwable) will be invoked to signal when connection is closed. The "closed" event is considered terminal and other callbacks after that can be safely discarded because nothing happens on the network interface after closure.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ConnectionObserver.DataObserver	An observer interface that provides visibility into read and write events related to data flow.
static interface	ConnectionObserver.MultiplexedObserver	An observer interface that provides visibility into new streams created by a multiplexed connection.
static interface	ConnectionObserver.ProxyConnectObserver	An observer interface that provides visibility into proxy connect events for establishing a tunnel.
static interface	ConnectionObserver.ReadObserver	An observer interface that provides visibility into read events.
static interface	ConnectionObserver.SecurityHandshakeObserver	An observer interface that provides visibility into security handshake events.
static interface	ConnectionObserver.StreamObserver	An observer interface that provides visibility into stream events.
static interface	ConnectionObserver.WriteObserver	An observer interface that provides visibility into write events.

Method Summary

Modifier and Type	Method	Description
void	connectionClosed()	Callback when the connection is closed.
void	connectionClosed(Throwable error)	Callback when the connection is closed due to an error.
ConnectionObserver.DataObserver	connectionEstablished(ConnectionInfo info)	Callback when a non-multiplexed connection is established and ready.
default void	connectionWritabilityChanged(boolean isWritable)	Callback when a writable state of the connection changes.
ConnectionObserver.MultiplexedObserver	multiplexedConnectionEstablished(ConnectionInfo info)	Callback when a multiplexed connection is established and ready.
void	onDataRead(int size)	Callback when size bytes are read from the connection.
void	onDataWrite(int size)	Callback when size bytes are written to the connection.
void	onFlush()	Callback when previously written data is flushed to the connection.
default ConnectionObserver.ProxyConnectObserver	onProxyConnect(Object connectMsg)	Callback when a proxy connect is initiated.
ConnectionObserver.SecurityHandshakeObserver	onSecurityHandshake()	Callback when a security handshake is initiated.
default void	onTransportHandshakeComplete()	Deprecated. Use onTransportHandshakeComplete(ConnectionInfo)
default void	onTransportHandshakeComplete(ConnectionInfo info)	Callback when a transport handshake completes.

Method Details

onDataRead

void onDataRead(int size)

Callback when size bytes are read from the connection.

Parameters:

size - size of the data chunk read

onDataWrite

void onDataWrite(int size)

Callback when size bytes are written to the connection.

Parameters:

size - size of the data chunk written

onFlush

void onFlush()

Callback when previously written data is flushed to the connection.

onTransportHandshakeComplete

@Deprecated
default void onTransportHandshakeComplete()

Deprecated.

Use onTransportHandshakeComplete(ConnectionInfo)

Callback when a transport handshake completes.

Transport protocols that require a handshake in order to connect. Example: TCP "three-way handshake".

onTransportHandshakeComplete

default void onTransportHandshakeComplete(ConnectionInfo info)

Callback when a transport handshake completes.

Transport protocols that require a handshake in order to connect. Example: TCP "three-way handshake".

Parameters:

info - ConnectionInfo for the connection after transport handshake completes. Note that the ConnectionInfo.sslSession() will always return null since it is called before the security handshake is performed (and as a result no SSL session has been established). Also, ConnectionInfo.protocol() will return L4 (transport) protocol. Finalized ConnectionInfo will be available via connectionEstablished(ConnectionInfo) or multiplexedConnectionEstablished(ConnectionInfo) callbacks.

onProxyConnect

default ConnectionObserver.ProxyConnectObserver onProxyConnect(Object connectMsg)

Callback when a proxy connect is initiated.

For a typical connection, this callback is invoked after onTransportHandshakeComplete(ConnectionInfo).

Parameters:

connectMsg - a message sent to a proxy in request to establish a connection to the target server

Returns:

a new ConnectionObserver.ProxyConnectObserver that provides visibility into proxy connect events.

onSecurityHandshake

ConnectionObserver.SecurityHandshakeObserver onSecurityHandshake()

Callback when a security handshake is initiated.

For a typical connection, this callback is invoked after onTransportHandshakeComplete(ConnectionInfo). There are may be exceptions:

1. For a TCP connection, when ServiceTalkSocketOptions.TCP_FASTOPEN_CONNECT option is configured and the Fast Open feature is supported by the OS, this callback may be invoked earlier. Note, even if the Fast Open is available and configured, it may not actually happen if the Fast Open Cookie is null or rejected by the server.
2. For a proxy connections, the handshake may happen after an observer returned by onProxyConnect(Object) completes successfully.

Returns:

a new ConnectionObserver.SecurityHandshakeObserver that provides visibility into security handshake events

See Also:

• RFC7413: TCP Fast Open

connectionEstablished

ConnectionObserver.DataObserver connectionEstablished(ConnectionInfo info)

Callback when a non-multiplexed connection is established and ready.

Parameters:

info - ConnectionInfo for the established connection

Returns:

a new ConnectionObserver.DataObserver that provides visibility into read and write events

multiplexedConnectionEstablished

ConnectionObserver.MultiplexedObserver multiplexedConnectionEstablished(ConnectionInfo info)

Callback when a multiplexed connection is established and ready.

Parameters:

info - ConnectionInfo for the established connection

Returns:

a new ConnectionObserver.MultiplexedObserver that provides visibility into new streams

connectionWritabilityChanged

default void connectionWritabilityChanged(boolean isWritable)

Callback when a writable state of the connection changes.

Parameters:

isWritable - describes the current state of the connection: true when the I/O thread will perform the requested write operation immediately. If false, write requests will be queued until the I/O thread is ready to process the queued items and the transport will start applying backpressure.

connectionClosed

void connectionClosed(Throwable error)

Callback when the connection is closed due to an error.

Parameters:

error - an occurred error

connectionClosed

void connectionClosed()

Callback when the connection is closed.