Package com.linecorp.armeria.client

Interface ClientRequestContext

All Superinterfaces:

RequestContext, Unwrappable

All Known Implementing Classes:

ClientRequestContextWrapper

public interface ClientRequestContext
extends RequestContext

Provides information about a Request, its Response and its related utilities. Every client request has its own ClientRequestContext instance.

Method Summary

Modifier and Type	Method	Description
void	addAdditionalRequestHeader(CharSequence name, Object value)	Adds a header with the specified name and value.
HttpHeaders	additionalRequestHeaders()	Returns an HttpHeaders which will be included when a Client sends an HttpRequest.
@Nullable String	authority()	Returns the authority which will eventually be sent when a Client sends an HttpRequest.
static ClientRequestContextBuilder	builder(HttpRequest request)	Returns a new ClientRequestContextBuilder created from the specified HttpRequest.
static ClientRequestContextBuilder	builder(RpcRequest request, String uri)	Returns a new ClientRequestContextBuilder created from the specified RpcRequest and uri.
static ClientRequestContextBuilder	builder(RpcRequest request, URI uri)	Returns a new ClientRequestContextBuilder created from the specified RpcRequest and URI.
default void	cancel()	Cancels the response.
void	clearResponseTimeout()	Clears the previously scheduled response timeout, if any.
static ClientRequestContext	current()	Returns the client-side context of the Request that is being handled in the current thread.
static @Nullable ClientRequestContext	currentOrNull()	Returns the client-side context of the Request that is being handled in the current thread.
HttpHeaders	defaultRequestHeaders()	Returns the default HttpHeaders which will be included when a Client sends an HttpRequest.
@Nullable Endpoint	endpoint()	Returns the remote Endpoint of the current Request.
@Nullable EndpointGroup	endpointGroup()	Returns the EndpointGroup used for the current Request.
ExchangeType	exchangeType()	Returns the ExchangeType that determines whether to stream an HttpRequest or HttpResponse.
@Nullable String	fragment()	Returns the fragment part of the URI of the current Request, as defined in the section 3.5 of RFC3986.
CompletableFuture<Void>	initiateConnectionShutdown()	Initiates connection shutdown and returns CompletableFuture that completes when the connection associated with this context is closed.
static <T> T	mapCurrent(Function<? super ClientRequestContext,T> mapper, @Nullable Supplier<T> defaultValueSupplier)	Maps the client-side context of the Request that is being handled in the current thread.
long	maxResponseLength()	Returns the maximum length of the received Response.
void	mutateAdditionalRequestHeaders(Consumer<HttpHeadersBuilder> mutator)	Mutates the HttpHeaders which will be included when a Client sends an HttpRequest.
ClientRequestContext	newDerivedContext(RequestId id, @Nullable HttpRequest req, @Nullable RpcRequest rpcReq, @Nullable Endpoint endpoint)	Creates a new ClientRequestContext whose properties and Attributes are copied from this ClientRequestContext, except having different Request, Endpoint and its own RequestLog.
static ClientRequestContext	of(HttpRequest request)	Returns a new ClientRequestContext created from the specified HttpRequest.
static ClientRequestContext	of(RpcRequest request, String uri)	Returns a new ClientRequestContext created from the specified RpcRequest and URI.
static ClientRequestContext	of(RpcRequest request, URI uri)	Returns a new ClientRequestContext created from the specified RpcRequest and URI.
ClientOptions	options()	Returns the ClientOptions of the current Request.
default SafeCloseable	push()	Pushes this context to the thread-local stack.
@Nullable HttpRequest	request()	Returns the HttpRequest associated with this context, or null if there's no HttpRequest associated with this context yet.
long	responseTimeoutMillis()	Returns the amount of time allowed until receiving the Response completely since the transfer of the Response started or the Request was fully sent.
@Nullable RpcRequest	rpcRequest()	Returns the RpcRequest associated with this context, or null if there's no RpcRequest associated with this context.
void	setAdditionalRequestHeader(CharSequence name, Object value)	Sets a header with the specified name and value.
void	setMaxResponseLength(long maxResponseLength)	Sets the maximum length of the received Response.
void	setResponseTimeout(TimeoutMode mode, Duration responseTimeout)	Schedules the response timeout that is triggered when the Response is not fully received within the specified TimeoutMode and the specified responseTimeoutMillis since the Response started or Request was fully sent.
default void	setResponseTimeout(Duration responseTimeout)	Schedules the response timeout that is triggered when the Response is not fully received within the specified amount of time from now.
default void	setResponseTimeoutMillis(long responseTimeoutMillis)	Schedules the response timeout that is triggered when the Response is not fully received within the specified amount of time from now.
void	setResponseTimeoutMillis(TimeoutMode mode, long responseTimeoutMillis)	Schedules the response timeout that is triggered when the Response is not fully received within the specified TimeoutMode and the specified responseTimeoutMillis since the Response started or Request was fully sent.
void	setWriteTimeout(Duration writeTimeout)	Sets the amount of time allowed until the initial write attempt of the current Request succeeds.
void	setWriteTimeoutMillis(long writeTimeoutMillis)	Sets the amount of time allowed until the initial write attempt of the current Request succeeds.
default void	timeoutNow()	Times out the response.
default ClientRequestContext	unwrap()	Unwraps this object and returns the object being decorated.
default ClientRequestContext	unwrapAll()	Unwraps this object and returns the innermost object being decorated.
URI	uri()	Returns the URI constructed based on RequestContext.sessionProtocol(), authority(), RequestContext.path() and RequestContext.query().
CompletableFuture<Throwable>	whenResponseCancelled()	Returns a CompletableFuture which is completed with a Throwable cancellation cause after the ClientRequestContext has been cancelled.
CompletableFuture<Throwable>	whenResponseCancelling()	Returns a CompletableFuture which is completed with a Throwable cancellation cause when the ClientRequestContext is about to get cancelled.
CompletableFuture<Void>	whenResponseTimedOut()	Deprecated. Use whenResponseCancelled() instead.
CompletableFuture<Void>	whenResponseTimingOut()	Deprecated. Use whenResponseCancelling() instead.
long	writeTimeoutMillis()	Returns the amount of time allowed until the initial write attempt of the current Request succeeds.

Methods inherited from interface com.linecorp.armeria.common.RequestContext

alloc, attr, attrs, cancel, cancellationCause, decodedPath, eventLoop, hasAttr, hasOwnAttr, id, isCancelled, isTimedOut, localAddress, log, logBuilder, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, meterRegistry, method, ownAttr, ownAttrs, path, query, remoteAddress, replace, requestAutoAbortDelayMillis, root, run, run, sessionProtocol, setAttr, setRequestAutoAbortDelay, setRequestAutoAbortDelayMillis, sslSession, updateRequest, updateRpcRequest

Methods inherited from interface com.linecorp.armeria.common.util.Unwrappable

as, equalsIgnoreWrapper

Method Details

current

static ClientRequestContext current()

Returns the client-side context of the Request that is being handled in the current thread.

Throws:

IllegalStateException - if the context is unavailable in the current thread or the current context is not a ClientRequestContext.

currentOrNull

@Nullable
static @Nullable ClientRequestContext currentOrNull()

Returns the client-side context of the Request that is being handled in the current thread.

Returns:

the ClientRequestContext available in the current thread, or null if unavailable.

mapCurrent

@Nullable
static <T> T mapCurrent(Function<? super ClientRequestContext,T> mapper,
 @Nullable
 @Nullable Supplier<T> defaultValueSupplier)

Maps the client-side context of the Request that is being handled in the current thread.

Parameters:

mapper - the Function that maps the ClientRequestContext

defaultValueSupplier - the Supplier that provides the value when the context is unavailable in the current thread. If null, the null will be returned when the context is unavailable in the current thread.

Throws:

IllegalStateException - if the current context is not a ClientRequestContext.

of

static ClientRequestContext of(HttpRequest request)

Returns a new ClientRequestContext created from the specified HttpRequest. Note that it is not usually required to create a new context by yourself, because Armeria will always provide a context object for you. However, it may be useful in some cases such as unit testing.

See Also:

• ClientRequestContextBuilder

of

static ClientRequestContext of(RpcRequest request,
 String uri)

Returns a new ClientRequestContext created from the specified RpcRequest and URI. Note that it is not usually required to create a new context by yourself, because Armeria will always provide a context object for you. However, it may be useful in some cases such as unit testing.

See Also:

• ClientRequestContextBuilder

of

static ClientRequestContext of(RpcRequest request,
 URI uri)

Returns a new ClientRequestContext created from the specified RpcRequest and URI. Note that it is not usually required to create a new context by yourself, because Armeria will always provide a context object for you. However, it may be useful in some cases such as unit testing.

See Also:

• ClientRequestContextBuilder

builder

static ClientRequestContextBuilder builder(HttpRequest request)

Returns a new ClientRequestContextBuilder created from the specified HttpRequest.

builder

static ClientRequestContextBuilder builder(RpcRequest request,
 String uri)

Returns a new ClientRequestContextBuilder created from the specified RpcRequest and uri.

builder

static ClientRequestContextBuilder builder(RpcRequest request,
 URI uri)

Returns a new ClientRequestContextBuilder created from the specified RpcRequest and URI.

request

@Nullable
@Nullable HttpRequest request()

Returns the HttpRequest associated with this context, or null if there's no HttpRequest associated with this context yet. For example, when you send an RPC request, this method will return null until the RPC request is translated into an HTTP request.

Specified by:

request in interface RequestContext

rpcRequest

@Nullable
@Nullable RpcRequest rpcRequest()

Returns the RpcRequest associated with this context, or null if there's no RpcRequest associated with this context. For example, this method will return null when you are not sending an RPC request but just a plain HTTP request.

Specified by:

rpcRequest in interface RequestContext

push

@MustBeClosed
default SafeCloseable push()

Pushes this context to the thread-local stack. To pop the context from the stack, call SafeCloseable.close(), which can be done using a try-with-resources block:

 try (SafeCloseable ignored = ctx.push()) {
     ...
 }
 

In order to call this method, the current thread-local state must meet one of the following conditions:

• the thread-local does not have any RequestContext in it
• the thread-local has the same ClientRequestContext as this - reentrance
• the thread-local has the ServiceRequestContext which is the same as RequestContext.root()
• the thread-local has the ClientRequestContext whose RequestContext.root() is the same RequestContext.root()
• the thread-local has the ClientRequestContext whose RequestContext.root() is null and this RequestContext.root() is null

Otherwise, this method will throw an IllegalStateException.

Specified by:

push in interface RequestContext

newDerivedContext

ClientRequestContext newDerivedContext(RequestId id,
 @Nullable
 @Nullable HttpRequest req,
 @Nullable
 @Nullable RpcRequest rpcReq,
 @Nullable
 @Nullable Endpoint endpoint)

Creates a new ClientRequestContext whose properties and Attributes are copied from this ClientRequestContext, except having different Request, Endpoint and its own RequestLog.

Note that this method does not copy the RequestLog properties to the derived context.

endpointGroup

@Nullable
@Nullable EndpointGroup endpointGroup()

Returns the EndpointGroup used for the current Request.

Returns:

the EndpointGroup if a user specified an EndpointGroup when initiating a Request. null if a user specified an Endpoint.

endpoint

@Nullable
@Nullable Endpoint endpoint()

Returns the remote Endpoint of the current Request.

Returns:

the remote Endpoint, or null if the Request has failed because its remote Endpoint couldn't be determined.

options

ClientOptions options()

Returns the ClientOptions of the current Request.

fragment

@Nullable
@Nullable String fragment()

Returns the fragment part of the URI of the current Request, as defined in the section 3.5 of RFC3986.

Returns:

the fragment part of the request URI, or null if no fragment was specified

authority

@Nullable
@UnstableApi
@Nullable String authority()

Returns the authority which will eventually be sent when a Client sends an HttpRequest. This method checks the following locations and returns the first non-null value.

1. Either the HttpHeaderNames.HOST or HttpHeaderNames.AUTHORITY value from additionalRequestHeaders().
2. The HttpRequest.authority() from request().
3. defaultRequestHeaders().
4. Endpoint.authority().

uri

@UnstableApi
URI uri()

Returns the URI constructed based on RequestContext.sessionProtocol(), authority(), RequestContext.path() and RequestContext.query().

Specified by:

uri in interface RequestContext

Throws:

IllegalStateException - if the resulting URI is not valid.

See Also:

• ServiceRequestContext.uri()
• uri()

writeTimeoutMillis

long writeTimeoutMillis()

Returns the amount of time allowed until the initial write attempt of the current Request succeeds. This value is initially set from ClientOptions.WRITE_TIMEOUT_MILLIS.

setWriteTimeoutMillis

void setWriteTimeoutMillis(long writeTimeoutMillis)

Sets the amount of time allowed until the initial write attempt of the current Request succeeds. This value is initially set from ClientOptions.WRITE_TIMEOUT_MILLIS.

setWriteTimeout

void setWriteTimeout(Duration writeTimeout)

Sets the amount of time allowed until the initial write attempt of the current Request succeeds. This value is initially set from ClientOptions.WRITE_TIMEOUT_MILLIS.

responseTimeoutMillis

long responseTimeoutMillis()

Returns the amount of time allowed until receiving the Response completely since the transfer of the Response started or the Request was fully sent. This value is initially set from ClientOptions.RESPONSE_TIMEOUT_MILLIS.

clearResponseTimeout

void clearResponseTimeout()

Clears the previously scheduled response timeout, if any. Note that calling this will prevent the response from ever being timed out.

setResponseTimeoutMillis

void setResponseTimeoutMillis(TimeoutMode mode,
 long responseTimeoutMillis)

Schedules the response timeout that is triggered when the Response is not fully received within the specified TimeoutMode and the specified responseTimeoutMillis since the Response started or Request was fully sent. This value is initially set from ClientOptions.RESPONSE_TIMEOUT_MILLIS.

timeout mode description

Timeout mode	description
TimeoutMode.SET_FROM_NOW	Sets a given amount of timeout from the current time.
TimeoutMode.SET_FROM_START	Sets a given amount of timeout since the current Response began processing.
TimeoutMode.EXTEND	Extends the previously scheduled timeout by the given amount of timeout.

For example:

 ClientRequestContext ctx = ...;
 // Schedules a timeout from the start time of the response
 ctx.setResponseTimeoutMillis(TimeoutMode.SET_FROM_START, 2000);
 assert ctx.responseTimeoutMillis() == 2000;
 ctx.setResponseTimeoutMillis(TimeoutMode.SET_FROM_START, 1000);
 assert ctx.responseTimeoutMillis() == 1000;

 // Schedules timeout after 3 seconds from now.
 ctx.setResponseTimeoutMillis(TimeoutMode.SET_FROM_NOW, 3000);

 // Extends the previously scheduled timeout.
 long oldResponseTimeoutMillis = ctx.responseTimeoutMillis();
 ctx.setResponseTimeoutMillis(TimeoutMode.EXTEND, 1000);
 assert ctx.responseTimeoutMillis() == oldResponseTimeoutMillis + 1000;
 ctx.extendResponseTimeoutMillis(TimeoutMode.EXTEND, -500);
 assert ctx.responseTimeoutMillis() == oldResponseTimeoutMillis + 500;
 

setResponseTimeoutMillis

default void setResponseTimeoutMillis(long responseTimeoutMillis)

Schedules the response timeout that is triggered when the Response is not fully received within the specified amount of time from now. Note that the specified responseTimeoutMillis must be positive. This value is initially set from ClientOptions.RESPONSE_TIMEOUT_MILLIS. This method is a shortcut for setResponseTimeoutMillis(TimeoutMode.SET_FROM_NOW, responseTimeoutMillis).

For example:

 ClientRequestContext ctx = ...;
 // Schedules timeout after 1 seconds from now.
 ctx.setResponseTimeoutMillis(1000);
 

Parameters:

responseTimeoutMillis - the amount of time allowed in milliseconds from now

setResponseTimeout

void setResponseTimeout(TimeoutMode mode,
 Duration responseTimeout)

Schedules the response timeout that is triggered when the Response is not fully received within the specified TimeoutMode and the specified responseTimeoutMillis since the Response started or Request was fully sent. This value is initially set from ClientOptions.RESPONSE_TIMEOUT_MILLIS.

timeout mode description

Timeout mode	description
TimeoutMode.SET_FROM_NOW	Sets a given amount of timeout from the current time.
TimeoutMode.SET_FROM_START	Sets a given amount of timeout since the current Response began processing.
TimeoutMode.EXTEND	Extends the previously scheduled timeout by the given amount of timeout.

For example:

 ClientRequestContext ctx = ...;
 // Schedules a timeout from the start time of the response
 ctx.setResponseTimeoutMillis(TimeoutMode.SET_FROM_START, Duration.ofSeconds(2));
 assert ctx.responseTimeoutMillis() == 2000;
 ctx.setResponseTimeoutMillis(TimeoutMode.SET_FROM_START, Duration.ofSeconds(1));
 assert ctx.responseTimeoutMillis() == 1000;

 // Schedules timeout after 3 seconds from now.
 ctx.setResponseTimeoutMillis(TimeoutMode.SET_FROM_NOW, Duration.ofSeconds(3));

 // Extends the previously scheduled timeout.
 long oldResponseTimeoutMillis = ctx.responseTimeoutMillis();
 ctx.setResponseTimeoutMillis(TimeoutMode.EXTEND, Duration.ofSeconds(1));
 assert ctx.responseTimeoutMillis() == oldResponseTimeoutMillis + 1000;
 ctx.setResponseTimeoutMillis(TimeoutMode.EXTEND, Duration.ofMillis(-500));
 assert ctx.responseTimeoutMillis() == oldResponseTimeoutMillis + 500;
 

setResponseTimeout

default void setResponseTimeout(Duration responseTimeout)

Schedules the response timeout that is triggered when the Response is not fully received within the specified amount of time from now. Note that the specified responseTimeout must be positive. This value is initially set from ClientOptions.RESPONSE_TIMEOUT_MILLIS. This method is a shortcut for setResponseTimeout(TimeoutMode.SET_FROM_NOW, responseTimeout).

For example:

 ClientRequestContext ctx = ...;
 // Schedules timeout after 1 seconds from now.
 ctx.setResponseTimeout(Duration.ofSeconds(1));
 

Parameters:

responseTimeout - the amount of time allowed from now

whenResponseCancelling

CompletableFuture<Throwable> whenResponseCancelling()

Returns a CompletableFuture which is completed with a Throwable cancellation cause when the ClientRequestContext is about to get cancelled. If the response is handled successfully without cancellation, the CompletableFuture won't complete.

whenResponseCancelled

CompletableFuture<Throwable> whenResponseCancelled()

Returns a CompletableFuture which is completed with a Throwable cancellation cause after the ClientRequestContext has been cancelled. RequestContext.isCancelled() will always return true when the returned CompletableFuture is completed. If the response is handled successfully without cancellation, the CompletableFuture won't complete.

whenResponseTimingOut

@Deprecated
CompletableFuture<Void> whenResponseTimingOut()

Deprecated.

Use whenResponseCancelling() instead.

Returns a CompletableFuture which is completed when the ClientRequestContext is about to get timed out. If the response is handled successfully or not cancelled by timeout, the CompletableFuture won't complete.

whenResponseTimedOut

@Deprecated
CompletableFuture<Void> whenResponseTimedOut()

Deprecated.

Use whenResponseCancelled() instead.

Returns a CompletableFuture which is completed after the ClientRequestContext has been timed out. RequestContext.isTimedOut() will always return true when the returned CompletableFuture is completed. If the response is handled successfully or not cancelled by timeout, the CompletableFuture won't complete.

cancel

default void cancel()

Cancels the response. Shortcut for cancel(ResponseCancellationException.get()).

Specified by:

cancel in interface RequestContext

timeoutNow

default void timeoutNow()

Times out the response. Shortcut for cancel(ResponseTimeoutException.get()).

Specified by:

timeoutNow in interface RequestContext

maxResponseLength

long maxResponseLength()

Returns the maximum length of the received Response. This value is initially set from ClientOptions.MAX_RESPONSE_LENGTH.

Returns:

the maximum length of the response. 0 if unlimited.

See Also:

• ContentTooLargeException

setMaxResponseLength

void setMaxResponseLength(long maxResponseLength)

Sets the maximum length of the received Response. This value is initially set from ClientOptions.MAX_RESPONSE_LENGTH. Specify 0 to disable the limit of the length of a response.

See Also:

• ContentTooLargeException

defaultRequestHeaders

@UnstableApi
HttpHeaders defaultRequestHeaders()

Returns the default HttpHeaders which will be included when a Client sends an HttpRequest.

Note that the values of the default HttpHeaders could be overridden if the same HttpHeaderNames are defined in HttpRequest.headers() or additionalRequestHeaders().

See Also:

• AbstractClientOptionsBuilder.addHeader(CharSequence, Object)

additionalRequestHeaders

HttpHeaders additionalRequestHeaders()

Returns an HttpHeaders which will be included when a Client sends an HttpRequest.

setAdditionalRequestHeader

void setAdditionalRequestHeader(CharSequence name,
 Object value)

Sets a header with the specified name and value. This will remove all previous values associated with the specified name. The header will be included when a Client sends an HttpRequest.

addAdditionalRequestHeader

void addAdditionalRequestHeader(CharSequence name,
 Object value)

Adds a header with the specified name and value. The header will be included when a Client sends an HttpRequest.

mutateAdditionalRequestHeaders

void mutateAdditionalRequestHeaders(Consumer<HttpHeadersBuilder> mutator)

Mutates the HttpHeaders which will be included when a Client sends an HttpRequest.

Parameters:

mutator - the Consumer that mutates the additional request headers

initiateConnectionShutdown

@UnstableApi
CompletableFuture<Void> initiateConnectionShutdown()

Initiates connection shutdown and returns CompletableFuture that completes when the connection associated with this context is closed.

If not sent already, "connection: close" header is sent with the request. If the underlying connection's protocol is HTTP/1.1, the connection will be closed as soon as all pending requests are processed. Otherwise, a GOAWAY frame will be sent to initiate graceful connection shutdown.

Specified by:

initiateConnectionShutdown in interface RequestContext

See Also:

• initiateConnectionShutdown()
• ServiceRequestContext.initiateConnectionShutdown()

exchangeType

@UnstableApi
ExchangeType exchangeType()

Returns the ExchangeType that determines whether to stream an HttpRequest or HttpResponse.

Note that an HttpRequest will be aggregated before being written if ExchangeType.UNARY or ExchangeType.RESPONSE_STREAMING is set.

Specified by:

exchangeType in interface RequestContext

unwrap

default ClientRequestContext unwrap()

Description copied from interface: Unwrappable

Unwraps this object and returns the object being decorated. If this Unwrappable is the innermost object, this method returns itself. For example:

 class Foo implements Unwrappable {}

 class Bar<T extends Unwrappable> extends AbstractUnwrappable<T> {
     Bar(T delegate) {
         super(delegate);
     }
 }

 class Qux<T extends Unwrappable> extends AbstractUnwrappable<T> {
     Qux(T delegate) {
         super(delegate);
     }
 }

 Foo foo = new Foo();
 assert foo.unwrap() == foo;

 Bar<Foo> bar = new Bar<>(foo);
 assert bar.unwrap() == foo;

 Qux<Bar<Foo>> qux = new Qux<>(bar);
 assert qux.unwrap() == bar;
 assert qux.unwrap().unwrap() == foo;
 

Specified by:

unwrap in interface RequestContext

Specified by:

unwrap in interface Unwrappable

unwrapAll

default ClientRequestContext unwrapAll()

Description copied from interface: Unwrappable

Unwraps this object and returns the innermost object being decorated. If this Unwrappable is the innermost object, this method returns itself. For example:

 class Foo implements Unwrappable {}

 class Bar<T extends Unwrappable> extends AbstractUnwrappable<T> {
     Bar(T delegate) {
         super(delegate);
     }
 }

 class Qux<T extends Unwrappable> extends AbstractUnwrappable<T> {
     Qux(T delegate) {
         super(delegate);
     }
 }

 Foo foo = new Foo();
 assert foo.unwrapAll() == foo;

 Bar<Foo> bar = new Bar<>(foo);
 assert bar.unwrapAll() == foo;

 Qux<Bar<Foo>> qux = new Qux<>(bar);
 assert qux.unwrap() == bar;
 assert qux.unwrapAll() == foo;
 

Specified by:

unwrapAll in interface RequestContext

Specified by:

unwrapAll in interface Unwrappable