Interface HttpTransportObserver.ConnectionObservation

Enclosing interface:

HttpTransportObserver

public static interface HttpTransportObserver.ConnectionObservation

Observation of one physical connection.

The publisher must invoke all lifecycle methods for this connection sequentially. This includes methods on this observation and on any HttpTransportObserver.HandshakeObservation or HttpTransportObserver.StreamObservation it returns. Concurrent lifecycle calls for the same connection are unsupported. Events for different connections may be published concurrently.

Method Summary

Modifier and Type	Method	Description
void	close(HttpTransportObserver.ConnectionOutcome outcome)	Completes this connection observation.
HttpTransportObserver.HandshakeObservation	handshakeStarted()	Observes the start of the configured handshake.
static HttpTransportObserver.ConnectionObservation	noop()	Returns a no-op connection observation.
void	protocolSelected(String protocol)	Reports the currently selected HTTP protocol.
HttpTransportObserver.StreamObservation	streamOpened(HttpTransportObserver.Direction direction, HttpTransportObserver.Initiator initiator)	Observes a started application request and response exchange.

Method Details

noop

static HttpTransportObserver.ConnectionObservation noop()

Returns a no-op connection observation.

Returns:

no-op observation

handshakeStarted

HttpTransportObserver.HandshakeObservation handshakeStarted()

Observes the start of the configured handshake.

The same observation is returned if this method is invoked more than once. The returned observation must not be null. Implementations that do not observe handshakes should return HttpTransportObserver.HandshakeObservation.noop().

Returns:

handshake observation

protocolSelected

void protocolSelected(String protocol)

Reports the currently selected HTTP protocol.

Publishers must report a known HTTP version using the corresponding PROTOCOL_HTTP_* constant, rather than its negotiation identifier. For example, h2 and h2c map to HttpTransportObserver.PROTOCOL_HTTP_2, and h3 maps to HttpTransportObserver.PROTOCOL_HTTP_3. A protocol for which this observer defines no constant may use its own stable, non-blank identifier.

The first selection marks the physical connection as established and usable for that protocol. A publisher must therefore report the first selection only after any required transport security handshake has succeeded and its HttpTransportObserver.HandshakeObservation.close(HandshakeOutcome) call has returned. The selected protocol may later change, for example after a successful HTTP/1.1 upgrade to HTTP/2. Repeated selection of an equal protocol identifier has no effect.

Parameters:

protocol - non-blank selected protocol identifier, normalized to a known constant when applicable

streamOpened

HttpTransportObserver.StreamObservation streamOpened(HttpTransportObserver.Direction direction,
 HttpTransportObserver.Initiator initiator)

Observes a started application request and response exchange.

An HTTP/1.1 publisher reports each exchange once as a HttpTransportObserver.Direction.BIDIRECTIONAL stream, with HttpTransportObserver.Initiator identifying the request sender relative to the observed endpoint. HTTP/2 and HTTP/3 publishers apply the same mapping to request streams. Publishers must not report server-push streams, protocol control streams, compression-state streams such as HTTP/3 QPACK encoder or decoder streams, or underlying transport streams.

The publisher must report the initial protocol selection before invoking this method. For a secured transport, this means after the required security handshake has succeeded. This lifecycle model does not represent HTTP streams accepted as TLS or QUIC early data.

The caller owns the returned observation and closes it when the stream terminates. The returned observation must not be null.

Parameters:

direction - stream directionality

initiator - stream initiator

Returns:

stream observation

close

void close(HttpTransportObserver.ConnectionOutcome outcome)

Completes this connection observation.

This method is idempotent. It also completes any handshake or stream observations which are still open. Open child observations receive these outcomes:

Outcomes for open child observations

Connection outcome	Handshake outcome	Stream outcome
HttpTransportObserver.ConnectionOutcome.NORMAL	HttpTransportObserver.HandshakeOutcome.CANCELLED	HttpTransportObserver.StreamOutcome.CANCELLED
HttpTransportObserver.ConnectionOutcome.LOCAL_CLOSE	HttpTransportObserver.HandshakeOutcome.CANCELLED	HttpTransportObserver.StreamOutcome.CANCELLED
HttpTransportObserver.ConnectionOutcome.REMOTE_CLOSE	HttpTransportObserver.HandshakeOutcome.FAILURE	HttpTransportObserver.StreamOutcome.CANCELLED
HttpTransportObserver.ConnectionOutcome.TIMEOUT	HttpTransportObserver.HandshakeOutcome.TIMEOUT	HttpTransportObserver.StreamOutcome.ERROR
HttpTransportObserver.ConnectionOutcome.ERROR	HttpTransportObserver.HandshakeOutcome.FAILURE	HttpTransportObserver.StreamOutcome.ERROR

Parameters:

outcome - termination outcome