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 mapped to the given AttributeKey or null if there's no value set by setAttr(AttributeKey, Object), setAttrIfAbsent(AttributeKey, Object) or computeAttrIfAbsent(AttributeKey, Function).
Iterator<Map.Entry<AttributeKey<?>,Object>>	attrs()	Returns the Iterator of all Map.Entrys this context contains.
<V> V	computeAttrIfAbsent(AttributeKey<V> key, Function<? super AttributeKey<V>,? extends V> mappingFunction)	If the specified AttributeKey is not already associated with a value (or is mapped to null), attempts to compute its value using the given mapping function and stores it into this context.
default EventLoop	contextAwareEventLoop()	Returns an EventLoop that will make sure this RequestContext is set as the current context before executing any callback.
default Executor	contextAwareExecutor()	Returns an Executor that will make sure this RequestContext is set as the current context before executing any callback.
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.
EventLoop	eventLoop()	Returns the EventLoop that is handling the current Request.
default Executor	executor()	Returns the Executor that is handling the current Request.
RequestId	id()	Returns the RequestId of the current Request and Response pair.
boolean	isTimedOut()	Returns whether this RequestContext has been timed-out (e.g., when the corresponding request passes a deadline).
<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 the current 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 the current 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 <T> T	mapCurrent(Function<? super RequestContext,T> mapper, Supplier<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.
RequestContext	newDerivedContext(RequestId id, HttpRequest req, RpcRequest rpcReq)	Deprecated. This method will be removed without a replacement.
<V> V	ownAttr(AttributeKey<V> key)	Returns the value mapped to the given AttributeKey or null if there's no value set by setAttr(AttributeKey, Object), setAttrIfAbsent(AttributeKey, Object) or computeAttrIfAbsent(AttributeKey, Function).
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.
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.
HttpRequest	request()	Returns the HttpRequest associated with this context, or null if there's no HttpRequest associated with this context yet.
ServiceRequestContext	root()	Returns the root ServiceRequestContext of this context.
RpcRequest	rpcRequest()	Returns the RpcRequest associated with this context, or null if there's no RpcRequest associated with this context.
SessionProtocol	sessionProtocol()	Returns the SessionProtocol of the current Request.
<V> void	setAttr(AttributeKey<V> key, V value)	Associates the specified value with the given AttributeKey in this context.
<V> V	setAttrIfAbsent(AttributeKey<V> key, V value)	Associates the specified value with the given AttributeKey in this context only if this context does not contain a mapping for the AttributeKey.
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()	Triggers the current timeout immediately if a timeout was scheduled before.
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.

mapCurrent

@Nullable static <T> T mapCurrent(Function<? super RequestContext,T> mapper, @Nullable Supplier<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 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 mapped to the given AttributeKey or null if there's no value set by setAttr(AttributeKey, Object), setAttrIfAbsent(AttributeKey, Object) or computeAttrIfAbsent(AttributeKey, Function).

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 mapped to the given AttributeKey or null if there's no value set by setAttr(AttributeKey, Object), setAttrIfAbsent(AttributeKey, Object) or computeAttrIfAbsent(AttributeKey, Function).

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

See Also:

attr(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

<V> void 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().

setAttrIfAbsent

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

Associates the specified value with the given AttributeKey in this context only if this context does not contain a mapping for the AttributeKey.

Returns:

null if there was no mapping for the AttributeKey or the old value if there's a mapping for the AttributeKey.

computeAttrIfAbsent

@Nullable <V> V computeAttrIfAbsent(AttributeKey<V> key, Function<? super AttributeKey<V>,? extends V> mappingFunction)

If the specified AttributeKey is not already associated with a value (or is mapped to null), attempts to compute its value using the given mapping function and stores it into this context.

If the mapping function returns null, no mapping is recorded.

Returns:

the current (existing or computed) value associated with the specified AttributeKey, or null if the computed value is null

request

@Nullable HttpRequest request()

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

rpcRequest

@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 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 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.

timeoutNow

void timeoutNow()

Triggers the current timeout immediately if a timeout was scheduled before. Otherwise, the current Request will be timed-out immediately after a timeout scheduler is initialized.

isTimedOut

boolean isTimedOut()

Returns whether this RequestContext has been timed-out (e.g., when the corresponding request passes a deadline).

executor

default Executor executor()

Returns the Executor that is handling the current Request.

eventLoop

EventLoop eventLoop()

Returns the EventLoop that is handling the current Request.

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.

contextAwareExecutor

default Executor contextAwareExecutor()

Returns an Executor that will make sure this RequestContext is set as the current context before executing any callback. This should almost always be used for executing asynchronous callbacks in service code to make sure features that require the RequestContext work properly. Most asynchronous libraries like CompletableFuture provide methods that accept an Executor to run callbacks on.

contextAwareEventLoop

default EventLoop contextAwareEventLoop()

Returns an EventLoop that will make sure this RequestContext is set as the current context before executing any callback.

push

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.

replace

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 contextAwareEventLoop() 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 the current RequestContext into the callback execution.

makeContextAware

default ScheduledExecutorService makeContextAware(ScheduledExecutorService executor)

Returns a ScheduledExecutorService that will execute callbacks in the given executor, making sure to propagate the current RequestContext into the callback execution.

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.

newDerivedContext

@Deprecated RequestContext newDerivedContext(RequestId id, @Nullable HttpRequest req, @Nullable RpcRequest rpcReq)

Deprecated.

This method will be removed without a replacement.

Creates a new RequestContext whose properties and attrs() are copied from this RequestContext, except having a different pair of HttpRequest and RpcRequest and its own RequestLog.