Package com.linecorp.armeria.server

Interface ServiceRequestContext

All Superinterfaces:

RequestContext

All Known Implementing Classes:

DefaultServiceRequestContext, ServiceRequestContextWrapper

public interface ServiceRequestContext
extends RequestContext

Provides information about an invocation and related utilities. Every request being handled has its own ServiceRequestContext instance.

Method Summary

Modifier and Type	Method	Description
void	addAdditionalResponseHeader(CharSequence name, Object value)	Adds a header with the specified name and value.
void	addAdditionalResponseTrailer(CharSequence name, Object value)	Adds a trailer with the specified name and value.
HttpHeaders	additionalResponseHeaders()	Returns the HttpHeaders which will be included when a Service sends an HttpResponse.
HttpHeaders	additionalResponseTrailers()	Returns the HttpHeaders which is included along with any other trailers when a Service completes an HttpResponse.
ContextAwareScheduledExecutorService	blockingTaskExecutor()	Returns the ContextAwareScheduledExecutorService that could be used for executing a potentially long-running task.
static ServiceRequestContextBuilder	builder(HttpRequest request)	Returns a new ServiceRequestContextBuilder created from the specified HttpRequest.
default void	cancel()	Cancels the request.
void	clearRequestTimeout()	Clears the previously scheduled request timeout, if any.
InetAddress	clientAddress()	Returns the address of the client who initiated this request.
ServiceConfig	config()	Returns the ServiceConfig of the Service that is handling the current Request.
static ServiceRequestContext	current()	Returns the server-side context of the Request that is being handled in the current thread.
static @Nullable ServiceRequestContext	currentOrNull()	Returns the server-side context of the Request that is being handled in the current thread.
String	decodedMappedPath()	Returns the RequestContext.decodedPath() with its context path removed.
CompletableFuture<Void>	initiateConnectionShutdown()	Initiates connection shutdown without overriding current configuration of the drain duration and returns CompletableFuture that completes when the channel is closed.
CompletableFuture<Void>	initiateConnectionShutdown(long drainDurationMicros)	Initiates graceful connection shutdown with a given drain duration in microseconds and returns CompletableFuture that completes when the channel is closed..
default CompletableFuture<Void>	initiateConnectionShutdown(Duration drainDuration)	Initiates graceful connection shutdown with a given drain duration and returns CompletableFuture that completes when the channel is closed.
<A extends SocketAddress> A	localAddress()	Returns the local address of this request.
static <T> T	mapCurrent(Function<? super ServiceRequestContext,T> mapper, @Nullable Supplier<@Nullable T> defaultValueSupplier)	Maps the server-side context of the Request that is being handled in the current thread.
String	mappedPath()	Returns the RequestContext.path() with its context path removed.
long	maxRequestLength()	Returns the maximum length of the current Request.
void	mutateAdditionalResponseHeaders(Consumer<HttpHeadersBuilder> mutator)	Mutates the HttpHeaders which will be included when a Service sends an HttpResponse.
void	mutateAdditionalResponseTrailers(Consumer<HttpHeadersBuilder> mutator)	Mutates the HttpHeaders which is included along with any other trailers when a Service completes an HttpResponse.
@Nullable MediaType	negotiatedResponseMediaType()	Returns the negotiated producible media type.
static ServiceRequestContext	of(HttpRequest request)	Returns a new ServiceRequestContext created from the specified HttpRequest.
default @Nullable String	pathParam(String name)	Returns the value of the specified path parameter.
Map<String,String>	pathParams()	Returns the path parameters mapped by the Route associated with the Service that is handling the current Request.
ProxiedAddresses	proxiedAddresses()	Returns the proxied addresses of the current Request.
default SafeCloseable	push()	Pushes this context to the thread-local stack.
<A extends SocketAddress> A	remoteAddress()	Returns the remote address of this request.
HttpRequest	request()	Returns the HttpRequest associated with this context.
long	requestTimeoutMillis()	Returns the amount of time allowed from the start time of the Request until receiving the current Request and sending the corresponding Response completely.
default ServiceRequestContext	root()	Returns the root ServiceRequestContext of this context.
RoutingContext	routingContext()	Returns the RoutingContext used to find the Service.
@Nullable RpcRequest	rpcRequest()	Returns the RpcRequest associated with this context, or null if there's no RpcRequest associated with this context.
void	setAdditionalResponseHeader(CharSequence name, Object value)	Sets a header with the specified name and value.
void	setAdditionalResponseTrailer(CharSequence name, Object value)	Sets a trailer with the specified name and value.
void	setMaxRequestLength(long maxRequestLength)	Sets the maximum length of the current Request.
void	setRequestTimeout(TimeoutMode mode, Duration requestTimeout)	Schedules the request timeout that is triggered when the Request is not fully received or the corresponding Response is not sent completely within the specified TimeoutMode and the specified requestTimeout.
default void	setRequestTimeout(Duration requestTimeout)	Schedules the request timeout that is triggered when the Request is not fully received or the corresponding Response is not sent completely within the specified amount time from now.
default void	setRequestTimeoutMillis(long requestTimeoutMillis)	Schedules the request timeout that is triggered when the Request is not fully received or the corresponding Response is not sent completely within the specified amount time from now.
void	setRequestTimeoutMillis(TimeoutMode mode, long requestTimeoutMillis)	Schedules the request timeout that is triggered when the Request is not fully received or the corresponding Response is not sent completely within the specified TimeoutMode and the specified requestTimeoutMillis.
default void	timeoutNow()	Times out the request.
CompletableFuture<Throwable>	whenRequestCancelled()	Returns a CompletableFuture which is completed with a Throwable cancellation cause after the ServiceRequestContext has been cancelled.
CompletableFuture<Throwable>	whenRequestCancelling()	Returns a CompletableFuture which is completed with a Throwable cancellation cause when the ServiceRequestContext is about to get cancelled.
CompletableFuture<Void>	whenRequestTimedOut()	Deprecated. Use whenRequestCancelled() instead.
CompletableFuture<Void>	whenRequestTimingOut()	Deprecated. Use whenRequestCancelling() instead.

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

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

Method Details

current

static ServiceRequestContext current()

Returns the server-side context of the Request that is being handled in the current thread. If the context is a ClientRequestContext, RequestContext.root() is returned.

Throws:

IllegalStateException - if the context is unavailable in the current thread or the current context is a ClientRequestContext and RequestContext.root() is null

currentOrNull

@Nullable
static @Nullable ServiceRequestContext currentOrNull()

Returns the server-side context of the Request that is being handled in the current thread. If the context is a ClientRequestContext, RequestContext.root() is returned.

Returns:

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

mapCurrent

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

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

Parameters:

mapper - the Function that maps the ServiceRequestContext

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

of

static ServiceRequestContext of(HttpRequest request)

Returns a new ServiceRequestContext 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:

ServiceRequestContextBuilder

builder

static ServiceRequestContextBuilder builder(HttpRequest request)

Returns a new ServiceRequestContextBuilder created from the specified HttpRequest.

root

@Nonnull
default ServiceRequestContext root()

Returns the root ServiceRequestContext of this context. This method always returns this.

Specified by:

root in interface RequestContext

Returns:

this

request

@Nonnull
HttpRequest request()

Returns the HttpRequest associated with this context.

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 the request being handled is 1) not an RPC request or 2) not decoded into an RPC request yet.

Specified by:

rpcRequest in interface RequestContext

remoteAddress

@Nonnull
<A extends SocketAddress> A remoteAddress()

Returns the remote address of this request.

Specified by:

remoteAddress in interface RequestContext

localAddress

@Nonnull
<A extends SocketAddress> A localAddress()

Returns the local address of this request.

Specified by:

localAddress in interface RequestContext

clientAddress

InetAddress clientAddress()

Returns the address of the client who initiated this request.

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 ServiceRequestContext as this - reentrance
• the thread-local has the ClientRequestContext whose RequestContext.root() is the same ServiceRequestContext as this

Otherwise, this method will throw an IllegalStateException.

Specified by:

push in interface RequestContext

config

ServiceConfig config()

Returns the ServiceConfig of the Service that is handling the current Request.

routingContext

RoutingContext routingContext()

Returns the RoutingContext used to find the Service.

pathParams

Map<String,String> pathParams()

Returns the path parameters mapped by the Route associated with the Service that is handling the current Request.

pathParam

@Nullable
default @Nullable String pathParam(String name)

Returns the value of the specified path parameter.

blockingTaskExecutor

ContextAwareScheduledExecutorService blockingTaskExecutor()

Returns the ContextAwareScheduledExecutorService that could be used for executing a potentially long-running task. The ContextAwareScheduledExecutorService sets this ServiceRequestContext as the current context before executing any submitted tasks. If you want to use ScheduledExecutorService without setting this context, call ContextAwareScheduledExecutorService.withoutContext() and use the returned ScheduledExecutorService.

mappedPath

String mappedPath()

Returns the RequestContext.path() with its context path removed. This method can be useful for a reusable service bound at various path prefixes.

decodedMappedPath

String decodedMappedPath()

Returns the RequestContext.decodedPath() with its context path removed. This method can be useful for a reusable service bound at various path prefixes.

negotiatedResponseMediaType

@Nullable
@Nullable MediaType negotiatedResponseMediaType()

Returns the negotiated producible media type. If the media type negotiation is not used for the Service, null would be returned.

requestTimeoutMillis

long requestTimeoutMillis()

Returns the amount of time allowed from the start time of the Request until receiving the current Request and sending the corresponding Response completely. This value is initially set from ServiceConfig.requestTimeoutMillis().

clearRequestTimeout

void clearRequestTimeout()

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

setRequestTimeoutMillis

default void setRequestTimeoutMillis(long requestTimeoutMillis)

Schedules the request timeout that is triggered when the Request is not fully received or the corresponding Response is not sent completely within the specified amount time from now. Note that the specified requestTimeout must be positive. This value is initially set from ServiceConfig.requestTimeoutMillis(). This method is a shortcut for setRequestTimeoutMillis(TimeoutMode.SET_FROM_NOW, requestTimeoutMillis).

For example:

 ServiceRequestContext ctx = ...;
 // Schedules timeout after 1 seconds from now.
 ctx.setRequestTimeoutMillis(1000);
 

Parameters:

requestTimeoutMillis - the amount of time allowed in milliseconds from now

setRequestTimeoutMillis

void setRequestTimeoutMillis(TimeoutMode mode,
 long requestTimeoutMillis)

Schedules the request timeout that is triggered when the Request is not fully received or the corresponding Response is not sent completely within the specified TimeoutMode and the specified requestTimeoutMillis.

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 Request began processing.
TimeoutMode.EXTEND	Extends the previously scheduled timeout by the given amount of timeout.

For example:

 ServiceRequestContext ctx = ...;
 // Schedules a timeout from the start time of the request
 ctx.setRequestTimeoutMillis(TimeoutMode.SET_FROM_START, 2000);
 assert ctx.requestTimeoutMillis() == 2000;
 ctx.setRequestTimeoutMillis(TimeoutMode.SET_FROM_START, 1000);
 assert ctx.requestTimeoutMillis() == 1000;

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

 // Extends the previously scheduled timeout.
 long oldRequestTimeoutMillis = ctx.requestTimeoutMillis();
 ctx.setRequestTimeoutMillis(TimeoutMode.EXTEND, 1000);
 assert ctx.requestTimeoutMillis() == oldRequestTimeoutMillis + 1000;
 ctx.extendRequestTimeoutMillis(TimeoutMode.EXTEND, -500);
 assert ctx.requestTimeoutMillis() == oldRequestTimeoutMillis + 500;
 

setRequestTimeout

default void setRequestTimeout(Duration requestTimeout)

Schedules the request timeout that is triggered when the Request is not fully received or the corresponding Response is not sent completely within the specified amount time from now. Note that the specified requestTimeout must be positive. This value is initially set from ServiceConfig.requestTimeoutMillis(). This method is a shortcut for setRequestTimeout(TimeoutMode.SET_FROM_NOW, requestTimeout).

For example:

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

Parameters:

requestTimeout - the amount of time allowed from now

setRequestTimeout

void setRequestTimeout(TimeoutMode mode,
 Duration requestTimeout)

Schedules the request timeout that is triggered when the Request is not fully received or the corresponding Response is not sent completely within the specified TimeoutMode and the specified requestTimeout.

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 Request began processing.
TimeoutMode.EXTEND	Extends the previously scheduled timeout by the given amount of timeout.

For example:

 ServiceRequestContext ctx = ...;
 // Schedules a timeout from the start time of the request
 ctx.setRequestTimeout(TimeoutMode.SET_FROM_START, Duration.ofSeconds(2));
 assert ctx.requestTimeoutMillis() == 2000;
 ctx.setRequestTimeout(TimeoutMode.SET_FROM_START, Duration.ofSeconds(1));
 assert ctx.requestTimeoutMillis() == 1000;

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

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

whenRequestCancelling

CompletableFuture<Throwable> whenRequestCancelling()

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

whenRequestCancelled

CompletableFuture<Throwable> whenRequestCancelled()

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

whenRequestTimingOut

@Deprecated
CompletableFuture<Void> whenRequestTimingOut()

Deprecated.

Use whenRequestCancelling() instead.

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

whenRequestTimedOut

@Deprecated
CompletableFuture<Void> whenRequestTimedOut()

Deprecated.

Use whenRequestCancelled() instead.

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

cancel

default void cancel()

Cancels the request. Shortcut for cancel(RequestCancellationException.get()).

Specified by:

cancel in interface RequestContext

timeoutNow

default void timeoutNow()

Times out the request. Shortcut for cancel(RequestTimeoutException.get()).

Specified by:

timeoutNow in interface RequestContext

maxRequestLength

long maxRequestLength()

Returns the maximum length of the current Request. This value is initially set from ServiceConfig.maxRequestLength(). If 0, there is no limit on the request size.

See Also:

ContentTooLargeException

setMaxRequestLength

void setMaxRequestLength(long maxRequestLength)

Sets the maximum length of the current Request. This value is initially set from ServiceConfig.maxRequestLength(). If 0, there is no limit on the request size.

See Also:

ContentTooLargeException

additionalResponseHeaders

HttpHeaders additionalResponseHeaders()

Returns the HttpHeaders which will be included when a Service sends an HttpResponse.

setAdditionalResponseHeader

void setAdditionalResponseHeader(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 Service sends an HttpResponse.

addAdditionalResponseHeader

void addAdditionalResponseHeader(CharSequence name,
 Object value)

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

mutateAdditionalResponseHeaders

void mutateAdditionalResponseHeaders(Consumer<HttpHeadersBuilder> mutator)

Mutates the HttpHeaders which will be included when a Service sends an HttpResponse.

Parameters:

mutator - the Consumer that mutates the additional response headers

additionalResponseTrailers

HttpHeaders additionalResponseTrailers()

Returns the HttpHeaders which is included along with any other trailers when a Service completes an HttpResponse.

setAdditionalResponseTrailer

void setAdditionalResponseTrailer(CharSequence name,
 Object value)

Sets a trailer with the specified name and value. This will remove all previous values associated with the specified name. The trailer will be included when a Service completes an HttpResponse.

addAdditionalResponseTrailer

void addAdditionalResponseTrailer(CharSequence name,
 Object value)

Adds a trailer with the specified name and value. The trailer will be included when a Service completes an HttpResponse.

mutateAdditionalResponseTrailers

void mutateAdditionalResponseTrailers(Consumer<HttpHeadersBuilder> mutator)

Mutates the HttpHeaders which is included along with any other trailers when a Service completes an HttpResponse.

Parameters:

mutator - the Consumer that mutates the additional trailers

proxiedAddresses

ProxiedAddresses proxiedAddresses()

Returns the proxied addresses of the current Request.

initiateConnectionShutdown

@UnstableApi
CompletableFuture<Void> initiateConnectionShutdown(long drainDurationMicros)

Initiates graceful connection shutdown with a given drain duration in microseconds and returns CompletableFuture that completes when the channel is closed..

At the connection drain server signals the clients that the connection shutdown is imminent but still accepts in flight requests. At the connection drain end server stops accepting new requests.

If graceful shutdown is already triggered and the given connection drain duration is smaller than the wait time before the connection drain end, it reschedules the drain end to happen faster. Otherwise, drain will end as it was previously scheduled.

Note that HTTP/1 doesn't support draining as described here, so for HTTP/1 drain duration is always 0, which means the connection will be closed immediately at the end of the current response.

See Also:

initiateConnectionShutdown(), initiateConnectionShutdown(Duration)

initiateConnectionShutdown

@UnstableApi
default CompletableFuture<Void> initiateConnectionShutdown(Duration drainDuration)

Initiates graceful connection shutdown with a given drain duration and returns CompletableFuture that completes when the channel is closed.

See Also:

initiateConnectionShutdown(), initiateConnectionShutdown(long)

initiateConnectionShutdown

@UnstableApi
CompletableFuture<Void> initiateConnectionShutdown()

Initiates connection shutdown without overriding current configuration of the drain duration and returns CompletableFuture that completes when the channel is closed.

See Also:

initiateConnectionShutdown(long), initiateConnectionShutdown(Duration)