Package com.linecorp.armeria.common

Interface RequestContext

All Known Subinterfaces:

ClientRequestContext, ServiceRequestContext

All Known Implementing Classes:

ClientRequestContextWrapper, DefaultClientRequestContext, DefaultServiceRequestContext, NonWrappingRequestContext, RequestContextWrapper, ServiceRequestContextWrapper

public interface RequestContext

Provides information about a Request, its Response and related utilities. A server-side Request has a ServiceRequestContext and a client-side Request has a ClientRequestContext.

Method Summary

Modifier and Type	Method	Description
default ByteBufAllocator	alloc()	Returns the ByteBufAllocator for this RequestContext.
<V> V	attr(AttributeKey<V> key)	Returns the value associated with the given AttributeKey or null if there's no value set by setAttr(AttributeKey, Object).
Iterator<Map.Entry<AttributeKey<?>,Object>>	attrs()	Returns the Iterator of all Map.Entrys this context contains.
void	cancel()	Cancels the current Request.
void	cancel(Throwable cause)	Cancels the current Request with a Throwable.
@Nullable Throwable	cancellationCause()	Returns the cause of cancellation, null if the request has not been cancelled.
static <T extends RequestContext> T	current()	Returns the context of the Request that is being handled in the current thread.
static <T extends RequestContext> T	currentOrNull()	Returns the context of the Request that is being handled in the current thread.
String	decodedPath()	Returns the absolute path part of the current Request URI, excluding the query part, decoded in UTF-8.
ContextAwareEventLoop	eventLoop()	Returns the ContextAwareEventLoop that is handling the current Request.
default boolean	hasAttr(AttributeKey<?> key)	Returns true if and only if the value associated with the specified AttributeKey is not null.
default boolean	hasOwnAttr(AttributeKey<?> key)	Returns true if and only if the value associated with the specified AttributeKey is not null.
RequestId	id()	Returns the RequestId of the current Request and Response pair.
default boolean	isCancelled()	Returns whether this RequestContext has been cancelled.
default boolean	isTimedOut()	Returns whether this RequestContext has been timed-out, that is the cancellation cause is an instance of TimeoutException.
<A extends SocketAddress> A	localAddress()	Returns the local address of this request, or null if the connection is not established yet.
RequestLogAccess	log()	Returns the RequestLogAccess that provides the access to the RequestLog, which contains the information collected while processing the current Request.
RequestLogBuilder	logBuilder()	Returns the RequestLogBuilder that collects the information about the current Request.
default Runnable	makeContextAware(Runnable runnable)	Returns a Runnable that makes sure the current RequestContext is set and then invokes the input runnable.
default <T> Callable<T>	makeContextAware(Callable<T> callable)	Returns a Callable that makes sure the current RequestContext is set and then invokes the input callable.
default <T> CompletableFuture<T>	makeContextAware(CompletableFuture<T> future)	Returns a CompletableFuture that makes sure the current RequestContext is set and then invokes the input future.
default <T> CompletionStage<T>	makeContextAware(CompletionStage<T> stage)	Returns a CompletionStage that makes sure the current RequestContext is set and then invokes the input stage.
default Executor	makeContextAware(Executor executor)	Returns an Executor that will execute callbacks in the given executor, making sure to propagate the current RequestContext into the callback execution.
default ExecutorService	makeContextAware(ExecutorService executor)	Returns an ExecutorService that will execute callbacks in the given executor, making sure to propagate this RequestContext into the callback execution.
default ScheduledExecutorService	makeContextAware(ScheduledExecutorService executor)	Returns a ScheduledExecutorService that will execute callbacks in the given executor, making sure to propagate this RequestContext into the callback execution.
default <T, U> BiConsumer<T,U>	makeContextAware(BiConsumer<T,U> action)	Returns a BiConsumer that makes sure the current RequestContext is set and then invokes the input action.
default <T, U, V> BiFunction<T,U,V>	makeContextAware(BiFunction<T,U,V> function)	Returns a BiFunction that makes sure the current RequestContext is set and then invokes the input function.
default <T> Consumer<T>	makeContextAware(Consumer<T> action)	Returns a Consumer that makes sure the current RequestContext is set and then invokes the input action.
default <T, R> Function<T,R>	makeContextAware(Function<T,R> function)	Returns a Function that makes sure the current RequestContext is set and then invokes the input function.
default Logger	makeContextAware(Logger logger)	Returns a Logger which prepends this RequestContext to the log message.
static ExecutorService	makeContextPropagating(ExecutorService executor)	Returns an ExecutorService that will execute callbacks in the given executor, propagating the caller's RequestContext (if any) into the callback execution.
static ScheduledExecutorService	makeContextPropagating(ScheduledExecutorService executor)	Returns a ScheduledExecutorService that will execute callbacks in the given executor, propagating the caller's RequestContext (if any) into the callback execution.
static <T> T	mapCurrent(Function<? super RequestContext,T> mapper, @Nullable Supplier<@Nullable T> defaultValueSupplier)	Maps the context of the Request that is being handled in the current thread.
MeterRegistry	meterRegistry()	Returns the MeterRegistry that collects various stats.
HttpMethod	method()	Returns the HTTP method of the current Request.
<V> V	ownAttr(AttributeKey<V> key)	Returns the value associated with the given AttributeKey or null if there's no value set by setAttr(AttributeKey, Object).
Iterator<Map.Entry<AttributeKey<?>,Object>>	ownAttrs()	Returns the Iterator of all Map.Entrys this context contains.
String	path()	Returns the absolute path part of the current Request URI, excluding the query part, as defined in RFC3986.
SafeCloseable	push()	Pushes the specified context to the thread-local stack.
@Nullable String	query()	Returns the query part of the current Request URI, without the leading '?', as defined in RFC3986.
<A extends SocketAddress> A	remoteAddress()	Returns the remote address of this request, or null if the connection is not established yet.
default SafeCloseable	replace()	Replaces the current RequestContext in the thread-local with this context without any validation.
@Nullable HttpRequest	request()	Returns the HttpRequest associated with this context, or null if there's no HttpRequest associated with this context yet.
@Nullable ServiceRequestContext	root()	Returns the root ServiceRequestContext of this context.
@Nullable RpcRequest	rpcRequest()	Returns the RpcRequest associated with this context, or null if there's no RpcRequest associated with this context.
default void	run(Runnable runnable)	Immediately run a given Runnable with this context.
default <T> T	run(Callable<T> callable)	Immediately call a given Callable with this context.
SessionProtocol	sessionProtocol()	Returns the SessionProtocol of the current Request.
<V> V	setAttr(AttributeKey<V> key, V value)	Associates the specified value with the given AttributeKey in this context.
@Nullable SSLSession	sslSession()	The SSLSession for this request if the connection is made over TLS, or null if the connection is not established yet or the connection is not a TLS connection.
void	timeoutNow()	Times out the current Request.
void	updateRequest(HttpRequest req)	Replaces the HttpRequest associated with this context with the specified one.
void	updateRpcRequest(RpcRequest rpcReq)	Replaces the RpcRequest associated with this context with the specified one.

Method Details

current

static <T extends RequestContext> T current()

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

Throws:

IllegalStateException - if the context is unavailable in the current thread

currentOrNull

@Nullable
static <T extends RequestContext> T currentOrNull()

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

Returns:

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

makeContextPropagating

static ExecutorService makeContextPropagating(ExecutorService executor)

Returns an ExecutorService that will execute callbacks in the given executor, propagating the caller's RequestContext (if any) into the callback execution. If this executor service is only used from a single request then it's better to use makeContextAware(ExecutorService)

makeContextPropagating

static ScheduledExecutorService makeContextPropagating(ScheduledExecutorService executor)

Returns a ScheduledExecutorService that will execute callbacks in the given executor, propagating the caller's RequestContext (if any) into the callback execution. If this executor service is only used from a single request then it's better to use makeContextAware(ScheduledExecutorService)

mapCurrent

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

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

Parameters:

mapper - the Function that maps the RequestContext

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.

root

@Nullable
@Nullable ServiceRequestContext root()

Returns the root ServiceRequestContext of this context.

Returns:

the root ServiceRequestContext, or null if this context was not created in the context of a server request.

attr

@Nullable
<V> V attr(AttributeKey<V> key)

Returns the value associated with the given AttributeKey or null if there's no value set by setAttr(AttributeKey, Object).

Searching for attributes in a root context

Note: This section applies only to a ClientRequestContext. A ServiceRequestContext always has itself as a root().

If the value does not exist in this context but only in root(), this method will return the value from the root().

 ClientRequestContext ctx = ...;
 assert ctx.root().attr(KEY).equals("root");
 assert ctx.attr(KEY).equals("root");
 assert ctx.ownAttr(KEY) == null;
 

If the value exists both in this context and root(), this method will return the value from this context.

 ClientRequestContext ctx = ...;
 assert ctx.root().attr(KEY).equals("root");
 assert ctx.ownAttr(KEY).equals("child");
 assert ctx.attr(KEY).equals("child");
 

See Also:

• ownAttr(AttributeKey)

ownAttr

@Nullable
<V> V ownAttr(AttributeKey<V> key)

Returns the value associated with the given AttributeKey or null if there's no value set by setAttr(AttributeKey, Object).

Unlike attr(AttributeKey), this does not search in root().

See Also:

• attr(AttributeKey)

hasAttr

default boolean hasAttr(AttributeKey<?> key)

Returns true if and only if the value associated with the specified AttributeKey is not null.

See Also:

• hasOwnAttr(AttributeKey)

hasOwnAttr

default boolean hasOwnAttr(AttributeKey<?> key)

Returns true if and only if the value associated with the specified AttributeKey is not null.

Unlike hasAttr(AttributeKey), this does not search in root().

See Also:

• hasAttr(AttributeKey)

attrs

Iterator<Map.Entry<AttributeKey<?>,Object>> attrs()

Returns the Iterator of all Map.Entrys this context contains.

Searching for attributes in a root context

Note: This section applies only to a ClientRequestContext. A ServiceRequestContext always has itself as a root().

The Iterator returned by this method will also yield the Map.Entrys from the root() except those whose AttributeKey exist already in this context, e.g.

 ClientRequestContext ctx = ...;
 assert ctx.ownAttr(KEY_A).equals("child_a");
 assert ctx.root().attr(KEY_A).equals("root_a");
 assert ctx.root().attr(KEY_B).equals("root_b");

 Iterator<Entry<AttributeKey<?>, Object>> attrs = ctx.attrs();
 assert attrs.next().getValue().equals("child_a"); // KEY_A
 // Skip KEY_A in the root.
 assert attrs.next().getValue().equals("root_b"); // KEY_B
 assert attrs.hasNext() == false;
 

Please note that any changes made to the Map.Entry returned by Iterator.next() never affects the Map.Entry owned by root(). For example:

 ClientRequestContext ctx = ...;
 assert ctx.root().attr(KEY).equals("root");
 assert ctx.ownAttr(KEY) == null;

 Iterator<Entry<AttributeKey<?>, Object>> attrs = ctx.attrs();
 Entry<AttributeKey<?>, Object> next = attrs.next();
 assert next.getKey() == KEY;
 // Overriding the root entry creates the client context's own entry.
 next.setValue("child");
 assert ctx.attr(KEY).equals("child");
 assert ctx.ownAttr(KEY).equals("child");
 // root attribute remains unaffected.
 assert ctx.root().attr(KEY).equals("root");
 

If you want to change the value from the root while iterating, please call attrs() from root().

 ClientRequestContext ctx = ...;
 assert ctx.root().attr(KEY).equals("root");
 assert ctx.ownAttr(KEY) == null;

 // Call attrs() from the root to set a value directly while iterating.
 Iterator<Entry<AttributeKey<?>, Object>> attrs = ctx.root().attrs();
 Entry<AttributeKey<?>, Object> next = attrs.next();
 assert next.getKey() == KEY;
 next.setValue("another_root");
 // The ctx does not have its own attribute.
 assert ctx.ownAttr(KEY) == null;
 assert ctx.attr(KEY).equals("another_root");
 

See Also:

• ownAttrs()

ownAttrs

Iterator<Map.Entry<AttributeKey<?>,Object>> ownAttrs()

Returns the Iterator of all Map.Entrys this context contains.

Unlike attrs(), this does not iterate root().

See Also:

• attrs()

setAttr

@Nullable
<V> V setAttr(AttributeKey<V> key,
 @Nullable
 V value)

Associates the specified value with the given AttributeKey in this context. If this context previously contained a mapping for the AttributeKey, the old value is replaced by the specified value. Set null not to iterate the mapping from attrs().

Returns:

the old value that has been replaced if there's a mapping for the specified key in this context or its root(), or null otherwise.

request

@Nullable
@Nullable HttpRequest request()

Returns the HttpRequest associated with this context, or null if there's no HttpRequest associated with this context yet.

rpcRequest

@Nullable
@Nullable RpcRequest rpcRequest()

Returns the RpcRequest associated with this context, or null if there's no RpcRequest associated with this context.

updateRequest

void updateRequest(HttpRequest req)

Replaces the HttpRequest associated with this context with the specified one. This method is useful to a decorator that manipulates HTTP request headers.

Note that it is a bad idea to change the values of the pseudo headers (":method", ":path", ":scheme" and ":authority") when replacing an HttpRequest, because the properties of this context, such as path(), are unaffected by such an attempt.

See Also:

• HttpRequest.withHeaders(RequestHeaders)
• HttpRequest.withHeaders(RequestHeadersBuilder)

updateRpcRequest

void updateRpcRequest(RpcRequest rpcReq)

Replaces the RpcRequest associated with this context with the specified one. This method is useful to a decorator that manipulates an RPC call.

sessionProtocol

SessionProtocol sessionProtocol()

Returns the SessionProtocol of the current Request.

remoteAddress

@Nullable
<A extends SocketAddress> A remoteAddress()

Returns the remote address of this request, or null if the connection is not established yet.

localAddress

@Nullable
<A extends SocketAddress> A localAddress()

Returns the local address of this request, or null if the connection is not established yet.

sslSession

@Nullable
@Nullable SSLSession sslSession()

The SSLSession for this request if the connection is made over TLS, or null if the connection is not established yet or the connection is not a TLS connection.

id

RequestId id()

Returns the RequestId of the current Request and Response pair.

method

HttpMethod method()

Returns the HTTP method of the current Request.

path

String path()

Returns the absolute path part of the current Request URI, excluding the query part, as defined in RFC3986.

decodedPath

String decodedPath()

Returns the absolute path part of the current Request URI, excluding the query part, decoded in UTF-8.

query

@Nullable
@Nullable String query()

Returns the query part of the current Request URI, without the leading '?', as defined in RFC3986.

log

RequestLogAccess log()

Returns the RequestLogAccess that provides the access to the RequestLog, which contains the information collected while processing the current Request.

logBuilder

RequestLogBuilder logBuilder()

Returns the RequestLogBuilder that collects the information about the current Request.

meterRegistry

MeterRegistry meterRegistry()

Returns the MeterRegistry that collects various stats.

cancel

void cancel(Throwable cause)

Cancels the current Request with a Throwable.

cancel

void cancel()

Cancels the current Request.

timeoutNow

void timeoutNow()

Times out the current Request.

cancellationCause

@Nullable
@Nullable Throwable cancellationCause()

Returns the cause of cancellation, null if the request has not been cancelled.

isCancelled

default boolean isCancelled()

Returns whether this RequestContext has been cancelled.

isTimedOut

default boolean isTimedOut()

Returns whether this RequestContext has been timed-out, that is the cancellation cause is an instance of TimeoutException.

eventLoop

ContextAwareEventLoop eventLoop()

Returns the ContextAwareEventLoop that is handling the current Request. The ContextAwareEventLoop sets this RequestContext as the current context before executing any submitted tasks. If you want to use EventLoop without setting this context, call ContextAwareEventLoop.withoutContext() and use the returned EventLoop.

alloc

default ByteBufAllocator alloc()

Returns the ByteBufAllocator for this RequestContext. Any buffers created by this ByteBufAllocator must be reference-counted. If you don't know what this means, you should probably use byte[] or ByteBuffer directly instead of calling this method.

push

@MustBeClosed
SafeCloseable push()

Pushes the specified 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()) {
     ...
 }
 

This method may throw an IllegalStateException according to the status of the current thread-local. Please see ServiceRequestContext.push() and ClientRequestContext.push() to find out the satisfying conditions.

run

default void run(Runnable runnable)

Immediately run a given Runnable with this context.

run

default <T> T run(Callable<T> callable)
           throws Exception

Immediately call a given Callable with this context.

Throws:

Exception

replace

@MustBeClosed
default SafeCloseable replace()

Replaces the current RequestContext in the thread-local with this context without any validation. This method also does not run any callbacks.

Note: Do not use this if you don't know what you are doing. This method does not prevent the situation where a wrong RequestContext is pushed into the thread-local. Use push() instead.

See Also:

• ClientRequestContext.push()
• ServiceRequestContext.push()

makeContextAware

default Executor makeContextAware(Executor executor)

Returns an Executor that will execute callbacks in the given executor, making sure to propagate the current RequestContext into the callback execution. It is generally preferred to use eventLoop() to ensure the callback stays on the same thread as well.

makeContextAware

default ExecutorService makeContextAware(ExecutorService executor)

Returns an ExecutorService that will execute callbacks in the given executor, making sure to propagate this RequestContext into the callback execution. If this executor service will be used for callbacks from several different requests, use makeContextPropagating(ExecutorService) instead.

makeContextAware

default ScheduledExecutorService makeContextAware(ScheduledExecutorService executor)

Returns a ScheduledExecutorService that will execute callbacks in the given executor, making sure to propagate this RequestContext into the callback execution. If this executor service will be used for callbacks from several different requests, use makeContextPropagating(ScheduledExecutorService) instead.

makeContextAware

default <T> Callable<T> makeContextAware(Callable<T> callable)

Returns a Callable that makes sure the current RequestContext is set and then invokes the input callable.

makeContextAware

default Runnable makeContextAware(Runnable runnable)

Returns a Runnable that makes sure the current RequestContext is set and then invokes the input runnable.

makeContextAware

default <T,
R> Function<T,R> makeContextAware(Function<T,R> function)

Returns a Function that makes sure the current RequestContext is set and then invokes the input function.

makeContextAware

default <T,
U,
V> BiFunction<T,U,V> makeContextAware(BiFunction<T,U,V> function)

Returns a BiFunction that makes sure the current RequestContext is set and then invokes the input function.

makeContextAware

default <T> Consumer<T> makeContextAware(Consumer<T> action)

Returns a Consumer that makes sure the current RequestContext is set and then invokes the input action.

makeContextAware

default <T,
U> BiConsumer<T,U> makeContextAware(BiConsumer<T,U> action)

Returns a BiConsumer that makes sure the current RequestContext is set and then invokes the input action.

makeContextAware

default <T> CompletionStage<T> makeContextAware(CompletionStage<T> stage)

Returns a CompletionStage that makes sure the current RequestContext is set and then invokes the input stage.

makeContextAware

default <T> CompletableFuture<T> makeContextAware(CompletableFuture<T> future)

Returns a CompletableFuture that makes sure the current RequestContext is set and then invokes the input future.

makeContextAware

default Logger makeContextAware(Logger logger)

Returns a Logger which prepends this RequestContext to the log message.

Parameters:

logger - the Logger to decorate.