Module methanol

Package com.github.mizosoft.methanol

Class Methanol

java.lang.Object

java.net.http.HttpClient

com.github.mizosoft.methanol.Methanol

All Implemented Interfaces:

AutoCloseable

public final class Methanol
extends HttpClient

An HttpClient with interceptors, request decoration, HTTP caching and reactive extensions.

In addition to implementing the HttpClient interface, this class allows to:

• Specify a base URI.
• Specify a default request timeout.
• Specify a read timeout.
• Add a set of default HTTP headers for inclusion in requests if absent.
• Add an HTTP caching layer.
• Transparent response decompression.
• Intercept requests and responses going through this client.
• Specify an AdapterCodec to automatically convert to/from request/response bodies.
• Get Publisher<HttpResponse<T>> for asynchronous requests.

A Methanol client relies on a standard HttpClient instance for sending requests, referred to as its backend. You can obtain builders for Methanol using either newBuilder() or newBuilder(HttpClient). The latter takes a prebuilt backend, while the former allows configuring a backend to be newly created each time Methanol.BaseBuilder.build() is invoked. Note that HttpCaches are not usable with a prebuilt backend.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Methanol.BaseBuilder<B extends Methanol.BaseBuilder<B>>	A base Methanol builder allowing to set the non-standard properties.
static final class	Methanol.Builder	A builder of Methanol instances.
static interface	Methanol.Interceptor	An object that intercepts requests being sent over a Methanol client.
static final class	Methanol.WithClientBuilder	A builder for Methanol instances with a pre-specified backend HttpClient.

Nested classes/interfaces inherited from class java.net.http.HttpClient

HttpClient.Redirect, HttpClient.Version

Method Summary

Modifier and Type	Method	Description
Optional<AdapterCodec>	adapterCodec()
Optional<Authenticator>	authenticator()
boolean	autoAcceptEncoding()	Returns this client's auto Accept-Encoding setting.
List<Methanol.Interceptor>	backendInterceptors()	Returns an immutable list of this client's backend interceptors.
Optional<URI>	baseUri()	Returns this client's base URI.
Optional<HttpCache>	cache()	Returns this client's cache.
List<HttpCache>	caches()
Optional<Duration>	connectTimeout()
Optional<CookieHandler>	cookieHandler()
static Methanol	create()	Creates a default Methanol instance.
HttpHeaders	defaultHeaders()	Returns this client's default headers.
<T> Flow.Publisher<HttpResponse<T>>	exchange(HttpRequest request, HttpResponse.BodyHandler<T> bodyHandler)	Returns a Publisher for the HttpResponse<T> resulting from asynchronously sending the given request.
<T> Flow.Publisher<HttpResponse<T>>	exchange(HttpRequest request, HttpResponse.BodyHandler<T> bodyHandler, Function<HttpRequest,@Nullable HttpResponse.BodyHandler<T>> pushPromiseMapper)	Returns a Publisher for the sequence of HttpResponse<T> resulting from asynchronously sending the given request along with accepting incoming push promises using the given Function.
Optional<Executor>	executor()
HttpClient.Redirect	followRedirects()
Optional<Duration>	headersTimeout()	Returns the headers timeout.
List<Methanol.Interceptor>	interceptors()	Returns an immutable list of this client's interceptors.
static Methanol.Builder	newBuilder()	Returns a new Methanol.Builder.
static Methanol.WithClientBuilder	newBuilder(HttpClient backend)	Returns a new Methanol.WithClientBuilder with a prebuilt backend.
List<Methanol.Interceptor>	postDecorationInterceptors()	Deprecated. Use backendInterceptors()
Optional<ProxySelector>	proxy()
Optional<Duration>	readTimeout()	Returns the read timeout used for each request.
Optional<Duration>	requestTimeout()	Returns the default request timeout used when not set in an HttpRequest.
HttpResponse<ResponsePayload>	send(HttpRequest request)	Like send(HttpRequest, BodyHandler) but defers handling the response body into the desired type using the provided ResponsePayload.
<T> HttpResponse<T>	send(HttpRequest request, TypeRef<T> bodyType)
<T> HttpResponse<T>	send(HttpRequest request, Class<T> bodyType)
<T> HttpResponse<T>	send(HttpRequest request, HttpResponse.BodyHandler<T> bodyHandler)
CompletableFuture<HttpResponse<ResponsePayload>>	sendAsync(HttpRequest request)	Like send(HttpRequest, BodyHandler) but defers handling the response body into the desired type using the provided ResponsePayload.
<T> CompletableFuture<HttpResponse<T>>	sendAsync(HttpRequest request, TypeRef<T> bodyType)
<T> CompletableFuture<HttpResponse<T>>	sendAsync(HttpRequest request, Class<T> bodyType)
<T> CompletableFuture<HttpResponse<T>>	sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> bodyHandler)
<T> CompletableFuture<HttpResponse<T>>	sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> bodyHandler, @Nullable HttpResponse.PushPromiseHandler<T> pushPromiseHandler)
SSLContext	sslContext()
SSLParameters	sslParameters()
HttpClient	underlyingClient()	Returns the underlying HttpClient used for sending requests.
Optional<String>	userAgent()	Returns this client's User-Agent.
HttpClient.Version	version()

Methods inherited from class java.net.http.HttpClient

awaitTermination, close, isTerminated, newHttpClient, newWebSocketBuilder, shutdown, shutdownNow

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

exchange

public <T> Flow.Publisher<HttpResponse<T>> exchange(HttpRequest request,
 HttpResponse.BodyHandler<T> bodyHandler)

Returns a Publisher for the HttpResponse<T> resulting from asynchronously sending the given request.

exchange

public <T> Flow.Publisher<HttpResponse<T>> exchange(HttpRequest request,
 HttpResponse.BodyHandler<T> bodyHandler,
 Function<HttpRequest,@Nullable HttpResponse.BodyHandler<T>> pushPromiseMapper)

Returns a Publisher for the sequence of HttpResponse<T> resulting from asynchronously sending the given request along with accepting incoming push promises using the given Function. The function accepts an incoming push promise by returning a non-null BodyHandler<T> for handling the pushed response body. If a null handler is returned, the push promise will be rejected.

Note that the published sequence has no specific order, and hence the main response is not guaranteed to be the first and may appear anywhere in the sequence.

underlyingClient

public HttpClient underlyingClient()

Returns the underlying HttpClient used for sending requests.

userAgent

public Optional<String> userAgent()

Returns this client's User-Agent.

baseUri

public Optional<URI> baseUri()

Returns this client's base URI.

requestTimeout

public Optional<Duration> requestTimeout()

Returns the default request timeout used when not set in an HttpRequest.

headersTimeout

public Optional<Duration> headersTimeout()

Returns the headers timeout.

readTimeout

public Optional<Duration> readTimeout()

Returns the read timeout used for each request.

interceptors

public List<Methanol.Interceptor> interceptors()

Returns an immutable list of this client's interceptors.

backendInterceptors

public List<Methanol.Interceptor> backendInterceptors()

Returns an immutable list of this client's backend interceptors.

postDecorationInterceptors

@Deprecated(since="1.5.0")
public List<Methanol.Interceptor> postDecorationInterceptors()

Deprecated.

Use backendInterceptors()

Returns the list of interceptors invoked after request decoration.

defaultHeaders

public HttpHeaders defaultHeaders()

Returns this client's default headers.

autoAcceptEncoding

public boolean autoAcceptEncoding()

Returns this client's auto Accept-Encoding setting.

cache

public Optional<HttpCache> cache()

Returns this client's cache.

caches

public List<HttpCache> caches()

adapterCodec

public Optional<AdapterCodec> adapterCodec()

cookieHandler

public Optional<CookieHandler> cookieHandler()

Specified by:

cookieHandler in class HttpClient

connectTimeout

public Optional<Duration> connectTimeout()

Specified by:

connectTimeout in class HttpClient

followRedirects

public HttpClient.Redirect followRedirects()

Specified by:

followRedirects in class HttpClient

proxy

public Optional<ProxySelector> proxy()

Specified by:

proxy in class HttpClient

sslContext

public SSLContext sslContext()

Specified by:

sslContext in class HttpClient

sslParameters

public SSLParameters sslParameters()

Specified by:

sslParameters in class HttpClient

authenticator

public Optional<Authenticator> authenticator()

Specified by:

authenticator in class HttpClient

version

public HttpClient.Version version()

Specified by:

version in class HttpClient

executor

public Optional<Executor> executor()

Specified by:

executor in class HttpClient

send

public <T> HttpResponse<T> send(HttpRequest request,
 HttpResponse.BodyHandler<T> bodyHandler)
                         throws IOException,
InterruptedException

Specified by:

send in class HttpClient

Throws:

IOException

InterruptedException

send

public HttpResponse<ResponsePayload> send(HttpRequest request)
                                   throws IOException,
InterruptedException

Like send(HttpRequest, BodyHandler) but defers handling the response body into the desired type using the provided ResponsePayload. The call completes as soon as the headers are received. Forgetting to close the returned payload (e.g. using try-with-resources) is a programming error.

Throws:

IOException

InterruptedException

sendAsync

public CompletableFuture<HttpResponse<ResponsePayload>> sendAsync(HttpRequest request)

Like send(HttpRequest, BodyHandler) but defers handling the response body into the desired type using the provided ResponsePayload. The call completes as soon as the headers are received. Forgetting to close the returned payload (e.g. using try-with-resources) is a programming error.

sendAsync

public <T> CompletableFuture<HttpResponse<T>> sendAsync(HttpRequest request,
 HttpResponse.BodyHandler<T> bodyHandler)

Specified by:

sendAsync in class HttpClient

sendAsync

public <T> CompletableFuture<HttpResponse<T>> sendAsync(HttpRequest request,
 HttpResponse.BodyHandler<T> bodyHandler,
 @Nullable HttpResponse.PushPromiseHandler<T> pushPromiseHandler)

Specified by:

sendAsync in class HttpClient

send

public <T> HttpResponse<T> send(HttpRequest request,
 Class<T> bodyType)
                         throws IOException,
InterruptedException

Throws:

IOException

InterruptedException

sendAsync

public <T> CompletableFuture<HttpResponse<T>> sendAsync(HttpRequest request,
 Class<T> bodyType)

send

public <T> HttpResponse<T> send(HttpRequest request,
 TypeRef<T> bodyType)
                         throws IOException,
InterruptedException

Throws:

IOException

InterruptedException

sendAsync

public <T> CompletableFuture<HttpResponse<T>> sendAsync(HttpRequest request,
 TypeRef<T> bodyType)

newBuilder

public static Methanol.Builder newBuilder()

Returns a new Methanol.Builder.

newBuilder

public static Methanol.WithClientBuilder newBuilder(HttpClient backend)

Returns a new Methanol.WithClientBuilder with a prebuilt backend.

create

public static Methanol create()

Creates a default Methanol instance.