Package com.linecorp.armeria.common

Interface HttpRequest

All Superinterfaces:

HttpMessage, org.reactivestreams.Publisher<HttpObject>, Request, StreamMessage<HttpObject>

All Known Subinterfaces:

HttpRequestWriter

All Known Implementing Classes:

FilteredHttpRequest

public interface HttpRequest
extends Request, HttpMessage

A streamed HTTP/2 Request.

Note: The initial RequestHeaders is not signaled to Subscribers. It is readily available via headers().

Method Summary

Modifier and Type	Method	Description
default @Nullable List<Locale.LanguageRange>	acceptLanguages()	Returns a list of Locale.LanguageRanges that are specified in HttpHeaderNames.ACCEPT_LANGUAGE in the order of client-side preferences.
default CompletableFuture<AggregatedHttpRequest>	aggregate()	Aggregates this request.
default CompletableFuture<AggregatedHttpRequest>	aggregate(EventExecutor executor)	Aggregates this request.
default CompletableFuture<AggregatedHttpRequest>	aggregateWithPooledObjects(ByteBufAllocator alloc)	(Advanced users only) Aggregates this request.
default CompletableFuture<AggregatedHttpRequest>	aggregateWithPooledObjects(EventExecutor executor, ByteBufAllocator alloc)	Aggregates this request.
default @Nullable String	authority()	Returns the authority of this request.
static HttpRequestBuilder	builder()	Returns a new HttpRequestBuilder.
default @Nullable MediaType	contentType()	Returns the value of the 'content-type' header.
default <T> StreamMessage<T>	decode(HttpDecoder<T> decoder, ByteBufAllocator alloc, Function<? super HttpData,? extends ByteBuf> byteBufConverter)	Creates a decoded StreamMessage which is decoded from a stream of HttpObjects using the specified HttpDecoder and ByteBufAllocator and byteBufConverter.
RequestHeaders	headers()	Returns the initial HTTP/2 headers of this request.
default HttpRequest	mapData(Function<? super HttpData,? extends HttpData> function)	Transforms the HttpDatas emitted by this HttpRequest by applying the specified Function.
default HttpRequest	mapError(Function<? super Throwable,? extends Throwable> function)	Transforms an error emitted by this HttpRequest by applying the specified Function.
default HttpRequest	mapHeaders(Function<? super RequestHeaders,? extends RequestHeaders> function)	Transforms the ResponseHeaders of this HttpRequest by applying the specified Function.
default HttpRequest	mapTrailers(Function<? super HttpHeaders,? extends HttpHeaders> function)	Transforms the trailers emitted by this HttpRequest by applying the specified Function.
default HttpMethod	method()	Returns the method of this request.
static HttpRequest	of(HttpMethod method, String path)	Creates a new HTTP request with empty content and closes the stream.
static HttpRequest	of(HttpMethod method, String path, MediaType mediaType, byte[] content)	Creates a new HTTP request and closes the stream.
static HttpRequest	of(HttpMethod method, String path, MediaType mediaType, HttpData content)	Creates a new HTTP request and closes the stream.
static HttpRequest	of(HttpMethod method, String path, MediaType mediaType, HttpData content, HttpHeaders trailers)	Creates a new HTTP request and closes the stream.
static HttpRequest	of(HttpMethod method, String path, MediaType mediaType, CharSequence content)	Creates a new HTTP request and closes the stream.
static HttpRequest	of(HttpMethod method, String path, MediaType mediaType, String content)	Creates a new HTTP request and closes the stream.
static HttpRequest	of(HttpMethod method, String path, MediaType mediaType, String format, Object... args)	Creates a new HTTP request and closes the stream.
static HttpRequest	of(RequestHeaders headers)	Creates a new HttpRequest with empty content and closes the stream.
static HttpRequest	of(RequestHeaders headers, HttpData content)	Creates a new HttpRequest and closes the stream.
static HttpRequest	of(RequestHeaders headers, HttpData... contents)	Creates a new HttpRequest that publishes the given HttpObjects and closes the stream.
static HttpRequest	of(RequestHeaders headers, HttpData content, HttpHeaders trailers)	Creates a new HttpRequest and closes the stream.
static HttpRequest	of(RequestHeaders headers, org.reactivestreams.Publisher<? extends HttpObject> publisher)	Creates a new instance from an existing RequestHeaders and Publisher.
default String	path()	Returns the path of this request.
default @Nullable String	scheme()	Returns the scheme of this request.
default @Nullable Locale	selectLocale(Iterable<Locale> supportedLocales)	Matches the Locales supported by the server to the HttpHeaderNames.ACCEPT_LANGUAGE and returning the best match according to client preference.
default @Nullable Locale	selectLocale(Locale... supportedLocales)	Matches the Locales supported by the server to the HttpHeaderNames.ACCEPT_LANGUAGE and returning the best match according to client preference.
static HttpRequestWriter	streaming(HttpMethod method, String path)	Creates a new HTTP request that can be used to stream an arbitrary number of HttpObject with the initial RequestHeaders of the specified HttpMethod and path.
static HttpRequestWriter	streaming(RequestHeaders headers)	Creates a new HTTP request that can be used to stream an arbitrary number of HttpObject with the specified initial RequestHeaders.
default HttpRequestDuplicator	toDuplicator()	Returns a new StreamMessageDuplicator that duplicates this StreamMessage into one or more StreamMessages, which publish the same elements.
default HttpRequestDuplicator	toDuplicator(long maxRequestLength)	Returns a new StreamMessageDuplicator that duplicates this HttpMessage into one or more HttpMessages, which publish the same elements.
default HttpRequestDuplicator	toDuplicator(EventExecutor executor)	Returns a new StreamMessageDuplicator that duplicates this StreamMessage into one or more StreamMessages, which publish the same elements.
default HttpRequestDuplicator	toDuplicator(EventExecutor executor, long maxRequestLength)	Returns a new StreamMessageDuplicator that duplicates this HttpMessage into one or more HttpMessages, which publish the same elements.
default URI	uri()	Returns the URI of this request.
default HttpRequest	withHeaders(RequestHeaders newHeaders)	Returns a new HttpRequest derived from this HttpRequest by replacing its RequestHeaders with the specified newHeaders.
default HttpRequest	withHeaders(RequestHeadersBuilder newHeadersBuilder)	Returns a new HttpRequest derived from this HttpRequest by replacing its RequestHeaders with what's built from the specified newHeadersBuilder.

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

decode, decode

Methods inherited from interface com.linecorp.armeria.common.stream.StreamMessage

abort, abort, collect, collect, collect, defaultSubscriberExecutor, demand, filter, isComplete, isEmpty, isOpen, map, recoverAndResume, subscribe, subscribe, subscribe, subscribe, whenComplete

Method Details

streaming

static HttpRequestWriter streaming(HttpMethod method,
 String path)

Creates a new HTTP request that can be used to stream an arbitrary number of HttpObject with the initial RequestHeaders of the specified HttpMethod and path.

streaming

static HttpRequestWriter streaming(RequestHeaders headers)

Creates a new HTTP request that can be used to stream an arbitrary number of HttpObject with the specified initial RequestHeaders.

of

static HttpRequest of(HttpMethod method,
 String path)

Creates a new HTTP request with empty content and closes the stream.

Parameters:

method - the HTTP method of the request

path - the path of the request

of

static HttpRequest of(HttpMethod method,
 String path,
 MediaType mediaType,
 CharSequence content)

Creates a new HTTP request and closes the stream.

Parameters:

method - the HTTP method of the request

path - the path of the request

mediaType - the MediaType of the request content

content - the content of the request

of

static HttpRequest of(HttpMethod method,
 String path,
 MediaType mediaType,
 String content)

Creates a new HTTP request and closes the stream.

Parameters:

method - the HTTP method of the request

path - the path of the request

mediaType - the MediaType of the request content

content - the content of the request

of

@FormatMethod
static HttpRequest of(HttpMethod method,
 String path,
 MediaType mediaType,
 @FormatString
 String format,
 Object... args)

Creates a new HTTP request and closes the stream. The content of the request is formatted by String.format(Locale, String, Object...) with English locale.

Parameters:

method - the HTTP method of the request

path - the path of the request

mediaType - the MediaType of the request content

format - the format string of the request content

args - the arguments referenced by the format specifiers in the format string

of

static HttpRequest of(HttpMethod method,
 String path,
 MediaType mediaType,
 byte[] content)

Creates a new HTTP request and closes the stream. The content will be wrapped using HttpData.wrap(byte[]), so any changes made to content will be reflected in the request.

Parameters:

method - the HTTP method of the request

path - the path of the request

mediaType - the MediaType of the request content

content - the content of the request

of

static HttpRequest of(HttpMethod method,
 String path,
 MediaType mediaType,
 HttpData content)

Creates a new HTTP request and closes the stream.

Parameters:

method - the HTTP method of the request

path - the path of the request

mediaType - the MediaType of the request content

content - the content of the request

of

static HttpRequest of(HttpMethod method,
 String path,
 MediaType mediaType,
 HttpData content,
 HttpHeaders trailers)

Creates a new HTTP request and closes the stream.

Parameters:

method - the HTTP method of the request

path - the path of the request

mediaType - the MediaType of the request content

content - the content of the request

trailers - the HTTP trailers

of

static HttpRequest of(RequestHeaders headers)

Creates a new HttpRequest with empty content and closes the stream.

of

static HttpRequest of(RequestHeaders headers,
 HttpData content)

Creates a new HttpRequest and closes the stream.

of

static HttpRequest of(RequestHeaders headers,
 HttpData content,
 HttpHeaders trailers)

Creates a new HttpRequest and closes the stream.

Throws:

IllegalStateException - if the headers are malformed.

of

static HttpRequest of(RequestHeaders headers,
 HttpData... contents)

Creates a new HttpRequest that publishes the given HttpObjects and closes the stream.

of

static HttpRequest of(RequestHeaders headers,
 org.reactivestreams.Publisher<? extends HttpObject> publisher)

Creates a new instance from an existing RequestHeaders and Publisher.

Note that the HttpObjects in the Publisher are not released when Subscription.cancel() or StreamMessage.abort() is called. You should add a hook in order to release the elements. See PublisherBasedStreamMessage for more information.

builder

static HttpRequestBuilder builder()

Returns a new HttpRequestBuilder.

headers

RequestHeaders headers()

Returns the initial HTTP/2 headers of this request.

uri

default URI uri()

Returns the URI of this request. This method is a shortcut for headers().uri().

scheme

@Nullable
default @Nullable String scheme()

Returns the scheme of this request. This method is a shortcut for headers().scheme().

method

default HttpMethod method()

Returns the method of this request. This method is a shortcut for headers().method().

path

default String path()

Returns the path of this request. This method is a shortcut for headers().path().

authority

@Nullable
default @Nullable String authority()

Returns the authority of this request. This method is a shortcut for headers().authority().

contentType

@Nullable
default @Nullable MediaType contentType()

Returns the value of the 'content-type' header.

Returns:

the valid header value if present, or null otherwise.

acceptLanguages

@Nullable
default @Nullable List<Locale.LanguageRange> acceptLanguages()

Returns a list of Locale.LanguageRanges that are specified in HttpHeaderNames.ACCEPT_LANGUAGE in the order of client-side preferences. If the client does not send the header, this will contain only a wild card Locale.LanguageRange.

selectLocale

@Nullable
default @Nullable Locale selectLocale(Iterable<Locale> supportedLocales)

Matches the Locales supported by the server to the HttpHeaderNames.ACCEPT_LANGUAGE and returning the best match according to client preference. It does this via Basic Filtering each Locale.LanguageRange and picking the first match. This is the "classic" algorithm described in RFC2616 Accept-Language (obsoleted) and also referenced in RFC7231 Accept-Language.

Parameters:

supportedLocales - an Iterable of Locales supported by the server.

Returns:

The best matching Locale or null if no Locale matches.

selectLocale

@Nullable
default @Nullable Locale selectLocale(Locale... supportedLocales)

Matches the Locales supported by the server to the HttpHeaderNames.ACCEPT_LANGUAGE and returning the best match according to client preference. It does this via Basic Filtering each Locale.LanguageRange and picking the first match. This is the "classic" algorithm described in RFC2616 Accept-Language (obsoleted) and also referenced in RFC7231 Accept-Language.

Parameters:

supportedLocales - Locales supported by the server.

Returns:

The best matching Locale or null if no Locale matches.

withHeaders

default HttpRequest withHeaders(RequestHeaders newHeaders)

Returns a new HttpRequest derived from this HttpRequest by replacing its RequestHeaders with the specified newHeaders. Note that the content stream and trailers of this HttpRequest is not duplicated, which means you can subscribe to only one of the two HttpRequests.

If you are using this method for intercepting an HttpRequest in a decorator, make sure to update RequestContext.request() with RequestContext.updateRequest(HttpRequest), e.g.

 > public class MyService extends SimpleDecoratingHttpService {
 >     @Override
 >     public HttpResponse serve(ServiceRequestContext ctx, HttpRequest req) {
 >         // Create a new request with an additional header.
 >         final HttpRequest newReq =
 >                 req.withHeaders(req.headers().toBuilder()
 >                                    .set("x-custom-header", "value")
 >                                    .build());
 >
 >         // Update the ctx.request.
 >         ctx.updateRequest(newReq);
 >
 >         // Delegate the new request with the updated context.
 >         return delegate().serve(ctx, newReq);
 >     }
 > }
 

withHeaders

default HttpRequest withHeaders(RequestHeadersBuilder newHeadersBuilder)

Returns a new HttpRequest derived from this HttpRequest by replacing its RequestHeaders with what's built from the specified newHeadersBuilder. Note that the content stream and trailers of this HttpRequest is not duplicated, which means you can subscribe to only one of the two HttpRequests.

If you are using this method for intercepting an HttpRequest in a decorator, make sure to update RequestContext.request() with RequestContext.updateRequest(HttpRequest), e.g.

 > public class MyService extends SimpleDecoratingHttpService {
 >     @Override
 >     public HttpResponse serve(ServiceRequestContext ctx, HttpRequest req) {
 >         // Create a new request with an additional header.
 >         final HttpRequest newReq =
 >                 req.withHeaders(req.headers().toBuilder()
 >                                    .set("x-custom-header", "value"));
 >
 >         // Update the ctx.request.
 >         ctx.updateRequest(newReq);
 >
 >         // Delegate the new request with the updated context.
 >         return delegate().serve(ctx, newReq);
 >     }
 > }
 

aggregate

default CompletableFuture<AggregatedHttpRequest> aggregate()

Aggregates this request. The returned CompletableFuture will be notified when the content and the trailers of the request is received fully.

aggregate

default CompletableFuture<AggregatedHttpRequest> aggregate(EventExecutor executor)

Aggregates this request. The returned CompletableFuture will be notified when the content and the trailers of the request is received fully.

aggregateWithPooledObjects

@UnstableApi
default CompletableFuture<AggregatedHttpRequest> aggregateWithPooledObjects(ByteBufAllocator alloc)

(Advanced users only) Aggregates this request. The returned CompletableFuture will be notified when the content and the trailers of the request is received fully. AggregatedHttpObject.content() will return a pooled object, and the caller must ensure to release it. If you don't know what this means, use aggregate().

See Also:

PooledObjects

aggregateWithPooledObjects

default CompletableFuture<AggregatedHttpRequest> aggregateWithPooledObjects(EventExecutor executor,
 ByteBufAllocator alloc)

Aggregates this request. The returned CompletableFuture will be notified when the content and the trailers of the request is received fully. AggregatedHttpObject.content() will return a pooled object, and the caller must ensure to release it. If you don't know what this means, use aggregate().

toDuplicator

default HttpRequestDuplicator toDuplicator()

Description copied from interface: StreamMessage

Returns a new StreamMessageDuplicator that duplicates this StreamMessage into one or more StreamMessages, which publish the same elements. Note that you cannot subscribe to this StreamMessage anymore after you call this method. To subscribe, call StreamMessageDuplicator.duplicate() from the returned StreamMessageDuplicator.

Specified by:

toDuplicator in interface StreamMessage<HttpObject>

toDuplicator

default HttpRequestDuplicator toDuplicator(EventExecutor executor)

Description copied from interface: StreamMessage

Returns a new StreamMessageDuplicator that duplicates this StreamMessage into one or more StreamMessages, which publish the same elements. Note that you cannot subscribe to this StreamMessage anymore after you call this method. To subscribe, call StreamMessageDuplicator.duplicate() from the returned StreamMessageDuplicator.

Specified by:

toDuplicator in interface StreamMessage<HttpObject>

Parameters:

executor - the executor to duplicate

toDuplicator

default HttpRequestDuplicator toDuplicator(long maxRequestLength)

Description copied from interface: HttpMessage

Returns a new StreamMessageDuplicator that duplicates this HttpMessage into one or more HttpMessages, which publish the same elements. Note that you cannot subscribe to this HttpMessage anymore after you call this method. To subscribe, call StreamMessageDuplicator.duplicate() from the returned StreamMessageDuplicator.

Specified by:

toDuplicator in interface HttpMessage

Parameters:

maxRequestLength - the maximum content length that the duplicator can hold in its buffer. ContentTooLargeException is raised if the length of the buffered HttpData is greater than this value.

toDuplicator

default HttpRequestDuplicator toDuplicator(EventExecutor executor,
 long maxRequestLength)

Description copied from interface: HttpMessage

Returns a new StreamMessageDuplicator that duplicates this HttpMessage into one or more HttpMessages, which publish the same elements. Note that you cannot subscribe to this HttpMessage anymore after you call this method. To subscribe, call StreamMessageDuplicator.duplicate() from the returned StreamMessageDuplicator.

Specified by:

toDuplicator in interface HttpMessage

Parameters:

executor - the executor to duplicate

maxRequestLength - the maximum content length that the duplicator can hold in its buffer. ContentTooLargeException is raised if the length of the buffered HttpData is greater than this value.

decode

default <T> StreamMessage<T> decode(HttpDecoder<T> decoder,
 ByteBufAllocator alloc,
 Function<? super HttpData,? extends ByteBuf> byteBufConverter)

Description copied from interface: HttpMessage

Creates a decoded StreamMessage which is decoded from a stream of HttpObjects using the specified HttpDecoder and ByteBufAllocator and byteBufConverter.

Specified by:

decode in interface HttpMessage

mapHeaders

default HttpRequest mapHeaders(Function<? super RequestHeaders,? extends RequestHeaders> function)

Transforms the ResponseHeaders of this HttpRequest by applying the specified Function.

For example:

 HttpRequest request = HttpRequest.of(HttpMethod.GET, "/items");
 HttpRequest transformed =
     request.mapHeaders(headers -> headers.toBuilder()
                                          .add("TraceId", "1")
                                          .build());
 assert transformed.aggregate().join().headers().get("TraceId").equals("1");
 

mapData

default HttpRequest mapData(Function<? super HttpData,? extends HttpData> function)

Transforms the HttpDatas emitted by this HttpRequest by applying the specified Function.

For example:

 HttpRequest request = HttpRequest.of(RequestHeaders.of(HttpMethod.POST, "/items"),
                                      HttpData.ofUtf8("data1,data2"));
 HttpRequest transformed = request.mapData(data -> {
     return HttpData.ofUtf8(data.toStringUtf8().replaceAll(",", "\n"));
 });
 assert transformed.aggregate().join().contentUtf8().equals("data1\ndata2");
 

mapTrailers

default HttpRequest mapTrailers(Function<? super HttpHeaders,? extends HttpHeaders> function)

Transforms the trailers emitted by this HttpRequest by applying the specified Function.

For example:

 HttpRequest request = HttpRequest.of(RequestHeaders.of(HttpMethod.POST, "/items"),
                                      HttpData.ofUtf8("..."));
 HttpRequest transformed = request.mapTrailers(trailers -> {
     return trailers.withMutations(builder -> builder.set("trailer1", "foo"));
 });
 assert transformed.aggregate().join().trailers().get("trailer1").equals("foo");
 

mapError

default HttpRequest mapError(Function<? super Throwable,? extends Throwable> function)

Transforms an error emitted by this HttpRequest by applying the specified Function.

For example:

 HttpRequest request = HttpRequest.ofFailure(new IllegalStateException("Something went wrong.");
 HttpRequest transformed = request.mapError(cause -> {
     if (cause instanceof IllegalStateException) {
         return new MyDomainException(cause);
     } else {
         return cause;
     }
 });
 

Specified by:

mapError in interface StreamMessage<HttpObject>