Interface HttpRequest
- All Superinterfaces:
HttpMessage
,org.reactivestreams.Publisher<HttpObject>
,Request
,StreamMessage<HttpObject>
- All Known Subinterfaces:
HttpRequestWriter
- All Known Implementing Classes:
FilteredHttpRequest
Request
.
Note: The initial RequestHeaders
is not signaled to Subscriber
s. It is readily available
via headers()
.
-
Method Summary
Modifier and TypeMethodDescriptiondefault @Nullable List<Locale.LanguageRange>
Returns a list ofLocale.LanguageRange
s that are specified inHttpHeaderNames.ACCEPT_LANGUAGE
in the order of client-side preferences.default CompletableFuture<AggregatedHttpRequest>
Aggregates this request.default CompletableFuture<AggregatedHttpRequest>
aggregate
(EventExecutor executor) Aggregates this request.default CompletableFuture<AggregatedHttpRequest>
(Advanced users only) Aggregates this request.default CompletableFuture<AggregatedHttpRequest>
aggregateWithPooledObjects
(EventExecutor executor, ByteBufAllocator alloc) Aggregates this request.Returns the authority of this request.static HttpRequestBuilder
builder()
Returns a newHttpRequestBuilder
.Returns the value of the'content-type'
header.headers()
Returns the initial HTTP/2 headers of this request.default HttpRequest
default HttpRequest
Transforms an error emitted by thisHttpRequest
by applying the specifiedFunction
.default HttpRequest
mapHeaders
(Function<? super RequestHeaders, ? extends RequestHeaders> function) default HttpRequest
mapTrailers
(Function<? super HttpHeaders, ? extends HttpHeaders> 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
Creates a new HTTP request and closes the stream.static HttpRequest
of
(RequestHeaders headers) Creates a newHttpRequest
with empty content and closes the stream.static HttpRequest
of
(RequestHeaders headers, HttpData content) Creates a newHttpRequest
and closes the stream.static HttpRequest
of
(RequestHeaders headers, HttpData... contents) Creates a newHttpRequest
that publishes the givenHttpObject
s and closes the stream.static HttpRequest
of
(RequestHeaders headers, HttpData content, HttpHeaders trailers) Creates a newHttpRequest
and closes the stream.static HttpRequest
of
(RequestHeaders headers, org.reactivestreams.Publisher<? extends HttpObject> publisher) Creates a new instance from an existingRequestHeaders
andPublisher
.default String
path()
Returns the path of this request.default HttpRequest
default HttpRequest
Applies the specifiedConsumer
to an error emitted by thisHttpRequest
.default HttpRequest
peekTrailers
(Consumer<? super HttpHeaders> action) scheme()
Returns the scheme of this request.selectLocale
(Iterable<Locale> supportedLocales) Matches theLocale
s supported by the server to theHttpHeaderNames.ACCEPT_LANGUAGE
and returning the best match according to client preference.selectLocale
(Locale... supportedLocales) Matches theLocale
s supported by the server to theHttpHeaderNames.ACCEPT_LANGUAGE
and returning the best match according to client preference.default SplitHttpRequest
split()
Returns a newSplitHttpRequest
which splits a stream ofHttpObject
s intoHttpData
s and an HTTP trailers.default SplitHttpRequest
split
(EventExecutor executor) Returns a newSplitHttpRequest
which splits a stream ofHttpObject
s intoHttpData
s and an HTTP trailers.static HttpRequestWriter
streaming
(HttpMethod method, String path) Creates a new HTTP request that can be used to stream an arbitrary number ofHttpObject
with the initialRequestHeaders
of the specifiedHttpMethod
andpath
.static HttpRequestWriter
streaming
(RequestHeaders headers) Creates a new HTTP request that can be used to stream an arbitrary number ofHttpObject
with the specified initialRequestHeaders
.default HttpRequestDuplicator
Returns a newStreamMessageDuplicator
that duplicates thisStreamMessage
into one or moreStreamMessage
s, which publish the same elements.default HttpRequestDuplicator
toDuplicator
(long maxRequestLength) Returns a newStreamMessageDuplicator
that duplicates thisHttpMessage
into one or moreHttpMessage
s, which publish the same elements.default HttpRequestDuplicator
toDuplicator
(EventExecutor executor) Returns a newStreamMessageDuplicator
that duplicates thisStreamMessage
into one or moreStreamMessage
s, which publish the same elements.default HttpRequestDuplicator
toDuplicator
(EventExecutor executor, long maxRequestLength) Returns a newStreamMessageDuplicator
that duplicates thisHttpMessage
into one or moreHttpMessage
s, which publish the same elements.default URI
uri()
Returns the URI of this request.default HttpRequest
withHeaders
(RequestHeaders newHeaders) Returns a newHttpRequest
derived from thisHttpRequest
by replacing itsRequestHeaders
with the specifiednewHeaders
.default HttpRequest
withHeaders
(RequestHeadersBuilder newHeadersBuilder) Returns a newHttpRequest
derived from thisHttpRequest
by replacing itsRequestHeaders
with what's built from the specifiednewHeadersBuilder
.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, decode, decode, defaultSubscriberExecutor, demand, filter, isComplete, isEmpty, isOpen, map, mapAsync, mapParallel, mapParallel, peek, peek, recoverAndResume, subscribe, subscribe, subscribe, subscribe, toInputStream, toInputStream, whenComplete, writeTo
-
Method Details
-
streaming
Creates a new HTTP request that can be used to stream an arbitrary number ofHttpObject
with the initialRequestHeaders
of the specifiedHttpMethod
andpath
. -
streaming
Creates a new HTTP request that can be used to stream an arbitrary number ofHttpObject
with the specified initialRequestHeaders
. -
of
Creates a new HTTP request with empty content and closes the stream.- Parameters:
method
- the HTTP method of the requestpath
- the path of the request
-
of
Creates a new HTTP request and closes the stream.- Parameters:
method
- the HTTP method of the requestpath
- the path of the requestmediaType
- theMediaType
of the request contentcontent
- the content of the request
-
of
Creates a new HTTP request and closes the stream.- Parameters:
method
- the HTTP method of the requestpath
- the path of the requestmediaType
- theMediaType
of the request contentcontent
- 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 byString.format(Locale, String, Object...)
with English locale.- Parameters:
method
- the HTTP method of the requestpath
- the path of the requestmediaType
- theMediaType
of the request contentformat
- the format string of the request contentargs
- the arguments referenced by the format specifiers in the format string
-
of
Creates a new HTTP request and closes the stream. Thecontent
will be wrapped usingHttpData.wrap(byte[])
, so any changes made tocontent
will be reflected in the request.- Parameters:
method
- the HTTP method of the requestpath
- the path of the requestmediaType
- theMediaType
of the request contentcontent
- the content of the request
-
of
Creates a new HTTP request and closes the stream.- Parameters:
method
- the HTTP method of the requestpath
- the path of the requestmediaType
- theMediaType
of the request contentcontent
- 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 requestpath
- the path of the requestmediaType
- theMediaType
of the request contentcontent
- the content of the requesttrailers
- the HTTP trailers
-
of
Creates a newHttpRequest
with empty content and closes the stream. -
of
Creates a newHttpRequest
and closes the stream. -
of
Creates a newHttpRequest
and closes the stream.- Throws:
IllegalStateException
- if the headers are malformed.
-
of
Creates a newHttpRequest
that publishes the givenHttpObject
s and closes the stream. -
of
static HttpRequest of(RequestHeaders headers, org.reactivestreams.Publisher<? extends HttpObject> publisher) Creates a new instance from an existingRequestHeaders
andPublisher
.Note that the
HttpObject
s in thePublisher
are not released whenSubscription.cancel()
orStreamMessage.abort()
is called. You should add a hook in order to release the elements. SeePublisherBasedStreamMessage
for more information. -
builder
Returns a newHttpRequestBuilder
. -
headers
RequestHeaders headers()Returns the initial HTTP/2 headers of this request. -
uri
Returns the URI of this request. This method is a shortcut forheaders().uri()
. -
scheme
Returns the scheme of this request. This method is a shortcut forheaders().scheme()
. -
method
Returns the method of this request. This method is a shortcut forheaders().method()
. -
path
Returns the path of this request. This method is a shortcut forheaders().path()
. -
authority
Returns the authority of this request. This method is a shortcut forheaders().authority()
. -
contentType
Returns the value of the'content-type'
header.- Returns:
- the valid header value if present, or
null
otherwise.
-
acceptLanguages
Returns a list ofLocale.LanguageRange
s that are specified inHttpHeaderNames.ACCEPT_LANGUAGE
in the order of client-side preferences. If the client does not send the header, this will contain only a wild cardLocale.LanguageRange
. -
selectLocale
Matches theLocale
s supported by the server to theHttpHeaderNames.ACCEPT_LANGUAGE
and returning the best match according to client preference. It does this viaBasic Filtering eachLocale.LanguageRange
and picking the first match. This is the "classic" algorithm described in RFC2616 Accept-Language (obsoleted) and also referenced in RFC7231 Accept-Language. -
selectLocale
Matches theLocale
s supported by the server to theHttpHeaderNames.ACCEPT_LANGUAGE
and returning the best match according to client preference. It does this viaBasic Filtering eachLocale.LanguageRange
and picking the first match. This is the "classic" algorithm described in RFC2616 Accept-Language (obsoleted) and also referenced in RFC7231 Accept-Language. -
withHeaders
Returns a newHttpRequest
derived from thisHttpRequest
by replacing itsRequestHeaders
with the specifiednewHeaders
. Note that the content stream and trailers of thisHttpRequest
is not duplicated, which means you can subscribe to only one of the twoHttpRequest
s.If you are using this method for intercepting an
HttpRequest
in a decorator, make sure to updateRequestContext.request()
withRequestContext.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
Returns a newHttpRequest
derived from thisHttpRequest
by replacing itsRequestHeaders
with what's built from the specifiednewHeadersBuilder
. Note that the content stream and trailers of thisHttpRequest
is not duplicated, which means you can subscribe to only one of the twoHttpRequest
s.If you are using this method for intercepting an
HttpRequest
in a decorator, make sure to updateRequestContext.request()
withRequestContext.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
Aggregates this request. The returnedCompletableFuture
will be notified when the content and the trailers of the request is received fully. -
aggregate
Aggregates this request. The returnedCompletableFuture
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 returnedCompletableFuture
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, useaggregate()
.- See Also:
-
aggregateWithPooledObjects
default CompletableFuture<AggregatedHttpRequest> aggregateWithPooledObjects(EventExecutor executor, ByteBufAllocator alloc) Aggregates this request. The returnedCompletableFuture
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, useaggregate()
. -
toDuplicator
Description copied from interface:StreamMessage
Returns a newStreamMessageDuplicator
that duplicates thisStreamMessage
into one or moreStreamMessage
s, which publish the same elements. Note that you cannot subscribe to thisStreamMessage
anymore after you call this method. To subscribe, callStreamMessageDuplicator.duplicate()
from the returnedStreamMessageDuplicator
.- Specified by:
toDuplicator
in interfaceStreamMessage<HttpObject>
-
toDuplicator
Description copied from interface:StreamMessage
Returns a newStreamMessageDuplicator
that duplicates thisStreamMessage
into one or moreStreamMessage
s, which publish the same elements. Note that you cannot subscribe to thisStreamMessage
anymore after you call this method. To subscribe, callStreamMessageDuplicator.duplicate()
from the returnedStreamMessageDuplicator
.- Specified by:
toDuplicator
in interfaceStreamMessage<HttpObject>
- Parameters:
executor
- the executor to duplicate
-
toDuplicator
Description copied from interface:HttpMessage
Returns a newStreamMessageDuplicator
that duplicates thisHttpMessage
into one or moreHttpMessage
s, which publish the same elements. Note that you cannot subscribe to thisHttpMessage
anymore after you call this method. To subscribe, callStreamMessageDuplicator.duplicate()
from the returnedStreamMessageDuplicator
.- Specified by:
toDuplicator
in interfaceHttpMessage
- Parameters:
maxRequestLength
- the maximum content length that the duplicator can hold in its buffer.ContentTooLargeException
is raised if the length of the bufferedHttpData
is greater than this value.
-
toDuplicator
Description copied from interface:HttpMessage
Returns a newStreamMessageDuplicator
that duplicates thisHttpMessage
into one or moreHttpMessage
s, which publish the same elements. Note that you cannot subscribe to thisHttpMessage
anymore after you call this method. To subscribe, callStreamMessageDuplicator.duplicate()
from the returnedStreamMessageDuplicator
.- Specified by:
toDuplicator
in interfaceHttpMessage
- Parameters:
executor
- the executor to duplicatemaxRequestLength
- the maximum content length that the duplicator can hold in its buffer.ContentTooLargeException
is raised if the length of the bufferedHttpData
is greater than this value.
-
split
Returns a newSplitHttpRequest
which splits a stream ofHttpObject
s intoHttpData
s and an HTTP trailers.SplitHttpMessage.trailers()
might not complete until the entire request body is consumed completely. -
split
Returns a newSplitHttpRequest
which splits a stream ofHttpObject
s intoHttpData
s and an HTTP trailers.SplitHttpMessage.trailers()
might not complete until the entire request body is consumed completely. -
mapHeaders
Transforms theRequestHeaders
of thisHttpRequest
by applying the specifiedFunction
.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
Transforms theHttpData
s emitted by thisHttpRequest
by applying the specifiedFunction
.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");
- Specified by:
mapData
in interfaceHttpMessage
-
mapTrailers
Transforms the trailers emitted by thisHttpRequest
by applying the specifiedFunction
.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");
- Specified by:
mapTrailers
in interfaceHttpMessage
-
mapError
Transforms an error emitted by thisHttpRequest
by applying the specifiedFunction
.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 interfaceStreamMessage<HttpObject>
-
peekData
Applies the specifiedConsumer
to theHttpData
s emitted by thisHttpRequest
.For example:
HttpRequest request = HttpRequest.of(RequestHeaders.of(HttpMethod.POST, "/items"), HttpData.ofUtf8("data1,data2")); HttpRequest peeked = request.peekData(data -> { assert data.toStringUtf8().equals("data1,data2"); });
- Specified by:
peekData
in interfaceHttpMessage
-
peekTrailers
Applies the specifiedConsumer
to the trailers emitted by thisHttpRequest
.For example:
HttpRequest request = HttpRequest.of(RequestHeaders.of(HttpMethod.POST, "/items"), HttpData.ofUtf8("..."), HttpHeaders.of("trailer", "foo")); HttpRequest peeked = request.peekTrailers(trailers -> { assert trailers.get("trailer").equals("foo"); });
- Specified by:
peekTrailers
in interfaceHttpMessage
-
peekError
Applies the specifiedConsumer
to an error emitted by thisHttpRequest
.For example:
HttpRequest request = HttpRequest.ofFailure(new IllegalStateException("Something went wrong.")); HttpRequest peeked = request.peekError(cause -> { assert cause instanceof IllegalStateException; });
- Specified by:
peekError
in interfaceStreamMessage<HttpObject>
-