Package com.linecorp.armeria.common

Interface HttpRequest

All Superinterfaces:

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

All Known Subinterfaces:

HttpRequestWriter

All Known Implementing Classes:

FilteredHttpRequest

public interface HttpRequest
extends Request, StreamMessage<HttpObject>

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 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 String	authority()	Returns the authority of this request.
default MediaType	contentType()	Returns the value of the 'content-type' header.
RequestHeaders	headers()	Returns the initial HTTP/2 headers of this request.
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 String	scheme()	Returns the scheme of this request.
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 HttpRequestDuplicator that duplicates this HttpRequest into one or more HttpRequests, which publish the same elements.
default HttpRequestDuplicator	toDuplicator(long maxRequestLength)	Returns a new HttpRequestDuplicator that duplicates this HttpRequest into one or more HttpRequests, which publish the same elements.
default HttpRequestDuplicator	toDuplicator(EventExecutor executor)	Returns a new HttpRequestDuplicator that duplicates this HttpRequest into one or more HttpRequests, which publish the same elements.
default HttpRequestDuplicator	toDuplicator(EventExecutor executor, long maxRequestLength)	Returns a new HttpRequestDuplicator that duplicates this HttpRequest into one or more HttpRequests, 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.stream.StreamMessage

abort, abort, defaultSubscriberExecutor, isComplete, isEmpty, isOpen, 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.

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 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 String authority()

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

contentType

@Nullable default MediaType contentType()

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

Returns:

the valid header value if present, or null otherwise.

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. AggregatedHttpMessage.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. AggregatedHttpMessage.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()

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

Specified by:

toDuplicator in interface StreamMessage<HttpObject>

toDuplicator

default HttpRequestDuplicator toDuplicator(EventExecutor executor)

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

Specified by:

toDuplicator in interface StreamMessage<HttpObject>

Parameters:

executor - the executor to duplicate

toDuplicator

default HttpRequestDuplicator toDuplicator(long maxRequestLength)

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

Parameters:

maxRequestLength - the maximum request 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)

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

Parameters:

executor - the executor to duplicate

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