Package com.linecorp.armeria.common
Interface RequestContext
-
- All Superinterfaces:
AttributeMap
- All Known Subinterfaces:
ClientRequestContext
,ServiceRequestContext
- All Known Implementing Classes:
AbstractRequestContext
,ClientRequestContextWrapper
,DefaultClientRequestContext
,DefaultServiceRequestContext
,NonWrappingRequestContext
,RequestContextWrapper
,ServiceRequestContextWrapper
public interface RequestContext extends AttributeMap
Provides information about aRequest
, itsResponse
and related utilities. A server-sideRequest
has aServiceRequestContext
and a client-sideRequest
has aClientRequestContext
.
-
-
Method Summary
Modifier and Type Method Description default ByteBufAllocator
alloc()
Returns theByteBufAllocator
for thisRequestContext
.Iterator<Attribute<?>>
attrs()
Returns allAttribute
s set in this context.default EventLoop
contextAwareEventLoop()
Returns anEventLoop
that will make sure thisRequestContext
is set as the current context before executing any callback.default Executor
contextAwareExecutor()
Returns anExecutor
that will make sure thisRequestContext
is set as the current context before executing any callback.static <T extends RequestContext>
Tcurrent()
Returns the context of theRequest
that is being handled in the current thread.static <T extends RequestContext>
TcurrentOrNull()
Returns the context of theRequest
that is being handled in the current thread.String
decodedPath()
Returns the absolute path part of the currentRequest
URI, excluding the query part, decoded in UTF-8.EventLoop
eventLoop()
default Executor
executor()
RequestId
id()
void
invokeOnChildCallbacks(RequestContext newCtx)
Invokes allonChild(BiConsumer)
callbacks.void
invokeOnEnterCallbacks()
Invokes allonEnter(Consumer)
callbacks.void
invokeOnExitCallbacks()
Invokes allonExit(Consumer)
callbacks.boolean
isTimedOut()
Deprecated.<A extends SocketAddress>
AlocalAddress()
Returns the local address of this request, ornull
if the connection is not established yet.RequestLog
log()
Returns theRequestLog
that contains the information about the currentRequest
.RequestLogBuilder
logBuilder()
Returns theRequestLogBuilder
that collects the information about the currentRequest
.ChannelFutureListener
makeContextAware(ChannelFutureListener listener)
Deprecated.UseCompletableFuture
instead.<T> FutureListener<T>
makeContextAware(FutureListener<T> listener)
Deprecated.UseCompletableFuture
instead.<T extends Future<?>>
GenericFutureListener<T>makeContextAware(GenericFutureListener<T> listener)
Deprecated.UseCompletableFuture
instead.Runnable
makeContextAware(Runnable runnable)
Returns aRunnable
that makes sure the currentRequestContext
is set and then invokes the inputrunnable
.<T> Callable<T>
makeContextAware(Callable<T> callable)
Returns aCallable
that makes sure the currentRequestContext
is set and then invokes the inputcallable
.default <T> CompletableFuture<T>
makeContextAware(CompletableFuture<T> future)
Returns aCompletableFuture
that makes sure the currentCompletableFuture
is set and then invokes the inputfuture
.<T> CompletionStage<T>
makeContextAware(CompletionStage<T> stage)
Returns aCompletionStage
that makes sure the currentCompletionStage
is set and then invokes the inputstage
.default Executor
makeContextAware(Executor executor)
Returns anExecutor
that will execute callbacks in the givenexecutor
, making sure to propagate the currentRequestContext
into the callback execution.default ExecutorService
makeContextAware(ExecutorService executor)
Returns anExecutorService
that will execute callbacks in the givenexecutor
, making sure to propagate the currentRequestContext
into the callback execution.default ScheduledExecutorService
makeContextAware(ScheduledExecutorService executor)
Returns aScheduledExecutorService
that will execute callbacks in the givenexecutor
, making sure to propagate the currentRequestContext
into the callback execution.<T,U>
BiConsumer<T,U>makeContextAware(BiConsumer<T,U> action)
Returns aBiConsumer
that makes sure the currentRequestContext
is set and then invokes the inputaction
.<T,U,V>
BiFunction<T,U,V>makeContextAware(BiFunction<T,U,V> function)
Returns aBiFunction
that makes sure the currentRequestContext
is set and then invokes the inputfunction
.<T> Consumer<T>
makeContextAware(Consumer<T> action)
Returns aConsumer
that makes sure the currentRequestContext
is set and then invokes the inputaction
.<T,R>
Function<T,R>makeContextAware(Function<T,R> function)
Returns aFunction
that makes sure the currentRequestContext
is set and then invokes the inputfunction
.static <T> T
mapCurrent(Function<? super RequestContext,T> mapper, Supplier<T> defaultValueSupplier)
Maps the context of theRequest
that is being handled in the current thread.MeterRegistry
meterRegistry()
Returns theMeterRegistry
that collects various stats.HttpMethod
method()
Returns the HTTP method of the currentRequest
.RequestContext
newDerivedContext(RequestId id, HttpRequest req, RpcRequest rpcReq)
Creates a newRequestContext
whose properties andAttribute
s are copied from thisRequestContext
, except having a different pair ofHttpRequest
andRpcRequest
and its ownRequestLog
.void
onChild(BiConsumer<? super RequestContext,? super RequestContext> callback)
Registerscallback
to be run when this context is replaced by a child context.default void
onEnter(Runnable callback)
Deprecated.UseonEnter(Consumer)
instead.void
onEnter(Consumer<? super RequestContext> callback)
Registerscallback
to be run when re-entering thisRequestContext
, usually when using themakeContextAware(java.util.concurrent.Executor)
family of methods.default void
onExit(Runnable callback)
Deprecated.UseonExit(Consumer)
instead.void
onExit(Consumer<? super RequestContext> callback)
Registerscallback
to be run when re-exiting thisRequestContext
, usually when using themakeContextAware(java.util.concurrent.Executor)
family of methods.String
path()
default SafeCloseable
push()
Pushes the specified context to the thread-local stack.default SafeCloseable
push(boolean runCallbacks)
Pushes the specified context to the thread-local stack.static SafeCloseable
push(RequestContext ctx)
Deprecated.Usepush()
.static SafeCloseable
push(RequestContext ctx, boolean runCallbacks)
Deprecated.Usepush(boolean)
.default SafeCloseable
pushIfAbsent()
Pushes this context to the thread-local stack if there is no current context.String
query()
default void
rejectPromise(Promise<?> promise, Throwable cause)
Deprecated.UseCompletableFuture
instead.<A extends SocketAddress>
AremoteAddress()
Returns the remote address of this request, ornull
if the connection is not established yet.HttpRequest
request()
Returns theHttpRequest
associated with this context, ornull
if there's noHttpRequest
associated with this context yet.default void
resolvePromise(Promise<?> promise, Object result)
Deprecated.UseCompletableFuture
instead.RpcRequest
rpcRequest()
Returns theRpcRequest
associated with this context, ornull
if there's noRpcRequest
associated with this context.SessionProtocol
sessionProtocol()
Returns theSessionProtocol
of the currentRequest
.SSLSession
sslSession()
TheSSLSession
for this request if the connection is made over TLS, ornull
if the connection is not established yet or the connection is not a TLS connection.void
updateRequest(HttpRequest req)
Replaces theHttpRequest
associated with this context with the specified one.void
updateRpcRequest(RpcRequest rpcReq)
Replaces theRpcRequest
associated with this context with the specified one.-
Methods inherited from interface io.netty.util.AttributeMap
attr, hasAttr
-
-
-
-
Method Detail
-
current
static <T extends RequestContext> T current()
Returns the context of theRequest
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 theRequest
that is being handled in the current thread.- Returns:
- the
RequestContext
available in the current thread, ornull
if unavailable.
-
mapCurrent
@Nullable static <T> T mapCurrent(Function<? super RequestContext,T> mapper, @Nullable Supplier<T> defaultValueSupplier)
Maps the context of theRequest
that is being handled in the current thread.- Parameters:
mapper
- theFunction
that maps theRequestContext
defaultValueSupplier
- theSupplier
that provides the value when the context is unavailable in the current thread. Ifnull
, thenull
will be returned when the context is unavailable in the current thread.
-
request
@Nullable HttpRequest request()
Returns theHttpRequest
associated with this context, ornull
if there's noHttpRequest
associated with this context yet.
-
rpcRequest
@Nullable RpcRequest rpcRequest()
Returns theRpcRequest
associated with this context, ornull
if there's noRpcRequest
associated with this context.
-
updateRequest
void updateRequest(HttpRequest req)
Replaces theHttpRequest
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 anHttpRequest
, because the properties of this context, such aspath()
, are unaffected by such an attempt.
-
updateRpcRequest
void updateRpcRequest(RpcRequest rpcReq)
Replaces theRpcRequest
associated with this context with the specified one. This method is useful to a decorator that manipulates an RPC call.
-
sessionProtocol
SessionProtocol sessionProtocol()
Returns theSessionProtocol
of the currentRequest
.
-
remoteAddress
@Nullable <A extends SocketAddress> A remoteAddress()
Returns the remote address of this request, ornull
if the connection is not established yet.
-
localAddress
@Nullable <A extends SocketAddress> A localAddress()
Returns the local address of this request, ornull
if the connection is not established yet.
-
sslSession
@Nullable SSLSession sslSession()
TheSSLSession
for this request if the connection is made over TLS, ornull
if the connection is not established yet or the connection is not a TLS connection.
-
id
RequestId id()
-
method
HttpMethod method()
Returns the HTTP method of the currentRequest
.
-
path
String path()
-
decodedPath
String decodedPath()
Returns the absolute path part of the currentRequest
URI, excluding the query part, decoded in UTF-8.
-
query
@Nullable String query()
-
log
RequestLog log()
Returns theRequestLog
that contains the information about the currentRequest
.
-
logBuilder
RequestLogBuilder logBuilder()
Returns theRequestLogBuilder
that collects the information about the currentRequest
.
-
meterRegistry
MeterRegistry meterRegistry()
Returns theMeterRegistry
that collects various stats.
-
executor
default Executor executor()
-
eventLoop
EventLoop eventLoop()
-
alloc
default ByteBufAllocator alloc()
Returns theByteBufAllocator
for thisRequestContext
. Any buffers created by thisByteBufAllocator
must be reference-counted. If you don't know what this means, you should probably usebyte[]
orByteBuffer
directly instead of calling this method.
-
contextAwareExecutor
default Executor contextAwareExecutor()
Returns anExecutor
that will make sure thisRequestContext
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 theRequestContext
work properly. Most asynchronous libraries likeCompletableFuture
provide methods that accept anExecutor
to run callbacks on.
-
contextAwareEventLoop
default EventLoop contextAwareEventLoop()
Returns anEventLoop
that will make sure thisRequestContext
is set as the current context before executing any callback.
-
push
@Deprecated static SafeCloseable push(RequestContext ctx)
Deprecated.Usepush()
.Pushes the specified context to the thread-local stack. To pop the context from the stack, callSafeCloseable.close()
, which can be done using atry-with-resources
block.
-
push
@Deprecated static SafeCloseable push(RequestContext ctx, boolean runCallbacks)
Deprecated.Usepush(boolean)
.Pushes the specified context to the thread-local stack. To pop the context from the stack, callSafeCloseable.close()
, which can be done using atry-with-resources
block.
-
push
default SafeCloseable push()
Pushes the specified context to the thread-local stack. To pop the context from the stack, callSafeCloseable.close()
, which can be done using atry-with-resources
block:try (SafeCloseable ignored = ctx.push()) { ... }
The callbacks added by
onEnter(Consumer)
andonExit(Consumer)
will be invoked when the context is pushed to and removed from the thread-local stack respectively.NOTE: In case of re-entrance, the callbacks will never run.
-
push
default SafeCloseable push(boolean runCallbacks)
Pushes the specified context to the thread-local stack. To pop the context from the stack, callSafeCloseable.close()
, which can be done using atry-with-resources
block:try (PushHandle ignored = ctx.push(true)) { ... }
NOTE: This method is only useful when it is undesirable to invoke the callbacks, such as replacing the current context with another. Prefer
push()
otherwise.- Parameters:
runCallbacks
- iftrue
, the callbacks added byonEnter(Consumer)
andonExit(Consumer)
will be invoked when the context is pushed to and removed from the thread-local stack respectively. Iffalse
, no callbacks will be executed. NOTE: In case of re-entrance, the callbacks will never run.
-
pushIfAbsent
default SafeCloseable pushIfAbsent()
Pushes this context to the thread-local stack if there is no current context. If there is and it is not same with this context (i.e. not reentrance), this method will throw anIllegalStateException
. To pop the context from the stack, callSafeCloseable.close()
, which can be done using atry-with-resources
block.
-
makeContextAware
default Executor makeContextAware(Executor executor)
Returns anExecutor
that will execute callbacks in the givenexecutor
, making sure to propagate the currentRequestContext
into the callback execution. It is generally preferred to usecontextAwareEventLoop()
to ensure the callback stays on the same thread as well.
-
makeContextAware
default ExecutorService makeContextAware(ExecutorService executor)
Returns anExecutorService
that will execute callbacks in the givenexecutor
, making sure to propagate the currentRequestContext
into the callback execution.
-
makeContextAware
default ScheduledExecutorService makeContextAware(ScheduledExecutorService executor)
Returns aScheduledExecutorService
that will execute callbacks in the givenexecutor
, making sure to propagate the currentRequestContext
into the callback execution.
-
makeContextAware
<T> Callable<T> makeContextAware(Callable<T> callable)
Returns aCallable
that makes sure the currentRequestContext
is set and then invokes the inputcallable
.
-
makeContextAware
Runnable makeContextAware(Runnable runnable)
Returns aRunnable
that makes sure the currentRequestContext
is set and then invokes the inputrunnable
.
-
makeContextAware
<T,R> Function<T,R> makeContextAware(Function<T,R> function)
Returns aFunction
that makes sure the currentRequestContext
is set and then invokes the inputfunction
.
-
makeContextAware
<T,U,V> BiFunction<T,U,V> makeContextAware(BiFunction<T,U,V> function)
Returns aBiFunction
that makes sure the currentRequestContext
is set and then invokes the inputfunction
.
-
makeContextAware
<T> Consumer<T> makeContextAware(Consumer<T> action)
Returns aConsumer
that makes sure the currentRequestContext
is set and then invokes the inputaction
.
-
makeContextAware
<T,U> BiConsumer<T,U> makeContextAware(BiConsumer<T,U> action)
Returns aBiConsumer
that makes sure the currentRequestContext
is set and then invokes the inputaction
.
-
makeContextAware
@Deprecated <T> FutureListener<T> makeContextAware(FutureListener<T> listener)
Deprecated.UseCompletableFuture
instead.Returns aFutureListener
that makes sure the currentRequestContext
is set and then invokes the inputlistener
.
-
makeContextAware
@Deprecated ChannelFutureListener makeContextAware(ChannelFutureListener listener)
Deprecated.UseCompletableFuture
instead.Returns aChannelFutureListener
that makes sure the currentRequestContext
is set and then invokes the inputlistener
.
-
makeContextAware
@Deprecated <T extends Future<?>> GenericFutureListener<T> makeContextAware(GenericFutureListener<T> listener)
Deprecated.UseCompletableFuture
instead.Returns aGenericFutureListener
that makes sure the currentRequestContext
is set and then invokes the inputlistener
. Unlike other versions ofmakeContextAware
, this one will invoke the listener with the future's result even if the context has already been timed out.
-
makeContextAware
<T> CompletionStage<T> makeContextAware(CompletionStage<T> stage)
Returns aCompletionStage
that makes sure the currentCompletionStage
is set and then invokes the inputstage
.
-
makeContextAware
default <T> CompletableFuture<T> makeContextAware(CompletableFuture<T> future)
Returns aCompletableFuture
that makes sure the currentCompletableFuture
is set and then invokes the inputfuture
.
-
isTimedOut
@Deprecated boolean isTimedOut()
Deprecated.Returns whether thisRequestContext
has been timed-out (e.g., when the corresponding request passes a deadline).
-
onEnter
void onEnter(Consumer<? super RequestContext> callback)
Registerscallback
to be run when re-entering thisRequestContext
, usually when using themakeContextAware(java.util.concurrent.Executor)
family of methods. Any thread-local state associated with this context should be restored by this callback.- Parameters:
callback
- aConsumer
whose argument is this context
-
onEnter
@Deprecated default void onEnter(Runnable callback)
Deprecated.UseonEnter(Consumer)
instead.Registerscallback
to be run when re-entering thisRequestContext
, usually when using themakeContextAware(java.util.concurrent.Executor)
family of methods. Any thread-local state associated with this context should be restored by this callback.
-
onExit
void onExit(Consumer<? super RequestContext> callback)
Registerscallback
to be run when re-exiting thisRequestContext
, usually when using themakeContextAware(java.util.concurrent.Executor)
family of methods. Any thread-local state associated with this context should be reset by this callback.- Parameters:
callback
- aConsumer
whose argument is this context
-
onExit
@Deprecated default void onExit(Runnable callback)
Deprecated.UseonExit(Consumer)
instead.Registerscallback
to be run when re-exiting thisRequestContext
, usually when using themakeContextAware(java.util.concurrent.Executor)
family of methods. Any thread-local state associated with this context should be reset by this callback.
-
onChild
void onChild(BiConsumer<? super RequestContext,? super RequestContext> callback)
Registerscallback
to be run when this context is replaced by a child context. You could use this method to inherit an attribute of this context to the child contexts or register a callback to the child contexts that may be created later:ctx.onChild((curCtx, newCtx) -> { assert ctx == curCtx && curCtx != newCtx; // Inherit the value of the 'MY_ATTR' attribute to the child context. newCtx.attr(MY_ATTR).set(curCtx.attr(MY_ATTR).get()); // Add a callback to the child context. newCtx.onExit(() -> { ... }); });
- Parameters:
callback
- aBiConsumer
whose first argument is this context and whose second argument is the new context that replaces this context
-
invokeOnEnterCallbacks
void invokeOnEnterCallbacks()
Invokes allonEnter(Consumer)
callbacks. It is discouraged to use this method directly. UsemakeContextAware(Runnable)
orpush(boolean)
instead so that the callbacks are invoked automatically.
-
invokeOnExitCallbacks
void invokeOnExitCallbacks()
Invokes allonExit(Consumer)
callbacks. It is discouraged to use this method directly. UsemakeContextAware(Runnable)
orpush(boolean)
instead so that the callbacks are invoked automatically.
-
invokeOnChildCallbacks
void invokeOnChildCallbacks(RequestContext newCtx)
Invokes allonChild(BiConsumer)
callbacks. It is discouraged to use this method directly. UsemakeContextAware(Runnable)
orpush(boolean)
instead so that the callbacks are invoked automatically.
-
resolvePromise
@Deprecated default void resolvePromise(Promise<?> promise, Object result)
Deprecated.UseCompletableFuture
instead.Resolves the specifiedpromise
with the specifiedresult
so that thepromise
is marked as 'done'. Ifpromise
is done already, this method does the following:- Log a warning about the failure, and
- Release
result
if it is a reference-counted object, such asByteBuf
andFullHttpResponse
.
Promise
can be done already even if you did not call this method in the following cases:- Invocation timeout - The invocation associated with the
Promise
has been timed out. - User error - A service implementation called any of the following methods more than once:
-
rejectPromise
@Deprecated default void rejectPromise(Promise<?> promise, Throwable cause)
Deprecated.UseCompletableFuture
instead.Rejects the specifiedpromise
with the specifiedcause
. Ifpromise
is done already, this method logs a warning about the failure. Note that aPromise
can be done already even if you did not call this method in the following cases:- Invocation timeout - The invocation associated with the
Promise
has been timed out. - User error - A service implementation called any of the following methods more than once:
- Invocation timeout - The invocation associated with the
-
newDerivedContext
RequestContext newDerivedContext(RequestId id, @Nullable HttpRequest req, @Nullable RpcRequest rpcReq)
Creates a newRequestContext
whose properties andAttribute
s are copied from thisRequestContext
, except having a different pair ofHttpRequest
andRpcRequest
and its ownRequestLog
.
-
-