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.
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 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.
<A extends SocketAddress> A	localAddress()	Returns the local address of this request.
static <T> T	mapCurrent(Function<? super ServiceRequestContext,T> mapper, Supplier<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.
MediaType	negotiatedResponseMediaType()	Returns the negotiated producible media type.
static ServiceRequestContext	of(HttpRequest request)	Returns a new ServiceRequestContext created from the specified HttpRequest.
default 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.
default Runnable	requestTimeoutHandler()	Deprecated. Use whenRequestTimingOut() or whenRequestTimedOut()
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.
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	setRequestTimeoutHandler(Runnable requestTimeoutHandler)	Deprecated. Use whenRequestTimingOut() or whenRequestTimedOut().
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.
CompletableFuture<Void>	whenRequestTimedOut()	Returns a CompletableFuture which is completed after ServiceRequestContext has been timed out (e.g., when the corresponding request passes a deadline).
CompletableFuture<Void>	whenRequestTimingOut()	Returns a CompletableFuture which is completed when ServiceRequestContext is about to get timed out.

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

alloc, attr, attrs, computeAttrIfAbsent, contextAwareEventLoop, contextAwareExecutor, decodedPath, eventLoop, executor, id, isTimedOut, log, logBuilder, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, makeContextAware, meterRegistry, method, ownAttr, ownAttrs, path, query, replace, sessionProtocol, setAttr, setAttrIfAbsent, sslSession, timeoutNow, 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 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 Supplier<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 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 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 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
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
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;
 

requestTimeoutHandler

@Deprecated @Nullable default Runnable requestTimeoutHandler()

Deprecated.

Use whenRequestTimingOut() or whenRequestTimedOut()

Returns Request timeout handler which is executed when receiving the current Request and sending the corresponding Response is not completely received within the allowed requestTimeoutMillis().

setRequestTimeoutHandler

@Deprecated default void setRequestTimeoutHandler(Runnable requestTimeoutHandler)

Deprecated.

Use whenRequestTimingOut() or whenRequestTimedOut().

Sets a handler to run when the request times out. requestTimeoutHandler must close the response, e.g., by calling StreamWriter.close(). If not set, the response will be closed with HttpStatus.SERVICE_UNAVAILABLE.

For example,

   HttpResponseWriter res = HttpResponse.streaming();
   ctx.setRequestTimeoutHandler(() -> {
      res.write(ResponseHeaders.of(HttpStatus.OK,
                                   HttpHeaderNames.CONTENT_TYPE, MediaType.PLAIN_TEXT_UTF_8));
      res.write(HttpData.ofUtf8("Request timed out."));
      res.close();
   });
   ...
 

whenRequestTimingOut

CompletableFuture<Void> whenRequestTimingOut()

Returns a CompletableFuture which is completed when ServiceRequestContext is about to get timed out.

whenRequestTimedOut

CompletableFuture<Void> whenRequestTimedOut()

Returns a CompletableFuture which is completed after ServiceRequestContext has been timed out (e.g., when the corresponding request passes a deadline). RequestContext.isTimedOut() will always return true when the returned CompletableFuture is completed.

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.