Interface HttpClientSpi

All Superinterfaces:

ReleasableResource

All Known Implementing Classes:

Http2ClientImpl

public interface HttpClientSpi
extends ReleasableResource

Integration for HTTP versions to provide a single API.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	HttpClientSpi.SupportLevel	How does the provider support the request.

Method Summary

Modifier and Type	Method	Description
ClientRequest<?>	clientRequest(FullClientRequest<?> clientRequest, ClientUri clientUri)	Create a client request based on the provided HTTP request that is for the version of this client.
default boolean	isTcp()	For TCP based protocols, we can do ALPN negotiation, obtain a connection, and then let the client handle the protocol.
default void	responseReceived(WebClientProtocolResponse response)	Notification invoked after the WebClient receives a transport response, regardless of the protocol that produced it.
HttpClientSpi.SupportLevel	supports(FullClientRequest<?> clientRequest, ClientUri clientUri)	Return whether this HTTP version can handle the provided request.

Methods inherited from interface ReleasableResource

closeResource, releaseResource

Modifier and Type	Method	Description
void	closeResource()	Closes the resource, we cannot use name close, as that would conflict with AutoCloseable, as we do not want to have a checked exception thrown.
default void	releaseResource()	Releases the resource, and if this resource is re-usable, enabled reuse.

Method Details

supports

HttpClientSpi.SupportLevel supports(FullClientRequest<?> clientRequest,
 ClientUri clientUri)

Return whether this HTTP version can handle the provided request.

Examples:

• HTTP/1.1 always returns HttpClientSpi.SupportLevel.COMPATIBLE, as it is the fallback protocol of all other protocols
• A protocol with a reusable connection returns HttpClientSpi.SupportLevel.SUPPORTED
• A dynamically discovered protocol can move between HttpClientSpi.SupportLevel.NOT_SUPPORTED and HttpClientSpi.SupportLevel.SUPPORTED as endpoint information becomes available or expires

So how can we get to HTTP/2 with prior knowledge, or HTTP/3? There are the following options:

• An explicit protocol id is configured for the request - HttpClientRequest.protocolId(String)
• There is no fallback protocol enabled, in such a case, we use the one with highest priority - see WebClientConfig.BuilderBase.addProtocolPreference(String)
• The client dynamically learns that another protocol is viable for the endpoint
• This protocol version already handled a request to such an endpoint and has the connection available

Note that this result is cached and revalidated for later requests. Implementations must make this method cheap and safe to invoke repeatedly, including for concurrent requests.

Parameters:

clientRequest - HTTP request

clientUri - URI to invoke

Returns:

support level for this protocol and request

clientRequest

ClientRequest<?> clientRequest(FullClientRequest<?> clientRequest,
 ClientUri clientUri)

Create a client request based on the provided HTTP request that is for the version of this client.

Parameters:

clientRequest - request configuration

clientUri - URI to invoke (resolved)

Returns:

a new request

responseReceived

default void responseReceived(WebClientProtocolResponse response)

Notification invoked after the WebClient receives a transport response, regardless of the protocol that produced it.

An implementation may inspect response metadata relevant to its protocol. For example, it may learn about an alternative service from an Alt-Svc response header received over another protocol.

Parameters:

response - received protocol response

isTcp

default boolean isTcp()

For TCP based protocols, we can do ALPN negotiation, obtain a connection, and then let the client handle the protocol. Similar for proxies - we can establish a proxy connection, and then let the client handle the protocol. For UDP based protocols, we need to wait for Alt-Svc headers before attempting anything, or have an explicit version configured.

Returns:

whether this is a TCP based HTTP protocol, defaults to true