public interface Request extends MutableRegistry
Modifier and Type | Field and Description |
---|---|
static TypeToken<Request> |
TYPE
A type token for this type.
|
Modifier and Type | Method and Description |
---|---|
<O> Request |
add(Class<? super O> type,
O object)
Adds a registry entry that is available by the given type.
|
Request |
add(Object object)
Adds a registry entry.
|
<O> Request |
add(TypeToken<? super O> type,
O object)
Adds a registry entry that is available by the given type.
|
<O> Request |
addLazy(Class<O> type,
Supplier<? extends O> supplier)
Adds a lazily created entry to the registry.
|
<O> Request |
addLazy(TypeToken<O> type,
Supplier<? extends O> supplier)
Adds a lazily created entry to the registry.
|
Promise<TypedData> |
getBody()
The body of the request.
|
Promise<TypedData> |
getBody(Block onTooLarge)
The body of the request.
|
Promise<TypedData> |
getBody(long maxContentLength)
The body of the request allowing up to the provided size for the content.
|
Promise<TypedData> |
getBody(long maxContentLength,
Block onTooLarge)
The body of the request allowing up to the provided size for the content.
|
TransformablePublisher<? extends ByteBuf> |
getBodyStream()
Allows reading the body as a stream, with back pressure.
|
TransformablePublisher<? extends ByteBuf> |
getBodyStream(long maxContentLength)
Allows reading the body as a stream, with back pressure.
|
long |
getContentLength()
The advertised content length of the request body.
|
MediaType |
getContentType()
The type of the data as specified in the
"content-type" header. |
Set<Cookie> |
getCookies()
The cookies that were sent with the request.
|
Headers |
getHeaders()
The request headers.
|
HostAndPort |
getLocalAddress()
The address of the local network interface that received the request.
|
HttpMethod |
getMethod()
The method of the request.
|
String |
getPath()
The URI without the query string and leading forward slash.
|
String |
getProtocol()
The HTTP protocol of the request.
|
String |
getQuery()
The query string component of the request URI, without the "?".
|
MultiValueMap<String,String> |
getQueryParams()
TBD.
|
String |
getRawUri()
The raw URI of the request.
|
HostAndPort |
getRemoteAddress()
The address of the client that initiated the request.
|
Instant |
getTimestamp()
The timestamp for when this request was received.
|
String |
getUri()
The complete URI of the request (path + query string).
|
boolean |
isAjaxRequest()
A flag representing whether or not the request originated via AJAX.
|
boolean |
isChunkedTransfer()
Whether this request contains a
Transfer-Encoding: chunked header. |
boolean |
isExpectsContinue()
Whether this request contains a
Expect: 100-Continue header. |
String |
oneCookie(String name)
Returns the value of the cookie with the specified name if it was sent.
|
remove, remove
backedBy, builder, empty, first, first, get, get, getAll, getAll, join, maybeGet, maybeGet, of, single, single, single, singleLazy
with
HttpMethod getMethod()
String getProtocol()
e.g. "HTTP/1.1
String getRawUri()
This value may be an absolute URI or an absolute path.
String getUri()
This value is always absolute (i.e. begins with "/
").
String getQuery()
If the request does not contain a query component, an empty string will be returned.
String getPath()
MultiValueMap<String,String> getQueryParams()
Set<Cookie> getCookies()
An empty set will be returned if no cookies were sent.
@Nullable String oneCookie(String name)
If there is more than one cookie with this name, this method will throw an exception.
name
- The name of the cookie to get the value ofPromise<TypedData> getBody()
If this request does not have a body, a non null object is still returned but it effectively has no data.
If the transmitted content is larger than provided ServerConfig.getMaxContentLength()
, the given block will be invoked.
If the block completes successfully, the promise will be terminated.
If the block errors, the promise will carry the failure.
Promise<TypedData> getBody(Block onTooLarge)
If this request does not have a body, a non null object is still returned but it effectively has no data.
If the transmitted content is larger than provided maxContentLength
, the given block will be invoked.
If the block completes successfully, the promise will be terminated.
If the block errors, the promise will carry the failure.
onTooLarge
- the action to take if the request body exceeds the given maxContentLengthPromise<TypedData> getBody(long maxContentLength)
If this request does not have a body, a non null object is still returned but it effectively has no data.
If the transmitted content is larger than the provided maxContentLength
, an 413
client error will be issued.
maxContentLength
- the maximum number of bytes allowed for the request.Promise<TypedData> getBody(long maxContentLength, Block onTooLarge)
If this request does not have a body, a non null object is still returned but it effectively has no data.
If the transmitted content is larger than the provided maxContentLength
, the given block will be invoked.
If the block completes successfully, the promise will be terminated.
If the block errors, the promise will carry the failure.
maxContentLength
- the maximum number of bytes allowed for the request.onTooLarge
- the action to take if the request body exceeds the given maxContentLengthTransformablePublisher<? extends ByteBuf> getBodyStream()
Similar to getBodyStream(long)
, except uses ServerConfig.getMaxContentLength()
as the max content length.
getBodyStream(long)
TransformablePublisher<? extends ByteBuf> getBodyStream(long maxContentLength)
The returned publisher emits the body as ByteBuf
s.
The subscriber MUST release()
each emitted byte buf.
Failing to do so will leak memory.
If the request body is larger than the given maxContentLength
, a RequestBodyTooLargeException
will be emitted.
If the request body has already been read, a RequestBodyAlreadyReadException
will be emitted.
The returned publisher is bound to the calling execution via Streams.bindExec(Publisher)
.
If your subscriber's onNext(), onComplete() or onError() methods are asynchronous they MUST use Promise
,
Blocking
or similar execution control constructs.
The following demonstrates how to use this method to stream the request body to a file, using asynchronous IO.
import com.google.common.io.Files; import io.netty.buffer.ByteBuf; import org.apache.commons.lang3.RandomStringUtils; import org.reactivestreams.Subscriber; import org.reactivestreams.Subscription; import org.junit.Assert; import ratpack.exec.Promise; import ratpack.http.client.ReceivedResponse; import ratpack.test.embed.EmbeddedApp; import ratpack.test.embed.EphemeralBaseDir; import java.io.IOException; import java.nio.channels.AsynchronousFileChannel; import java.nio.charset.StandardCharsets; import java.nio.file.Path; import java.nio.file.StandardOpenOption; public class Example { public static void main(String[] args) throws Exception { EphemeralBaseDir.tmpDir().use(dir -> { String string = RandomStringUtils.random(1024 * 1024); int length = string.getBytes(StandardCharsets.UTF_8).length; Path file = dir.path("out.txt"); EmbeddedApp.fromHandler(ctx -> ctx.getRequest().getBodyStream(length).subscribe(new Subscriber() { private Subscription subscription; private AsynchronousFileChannel out; long written; @Override public void onSubscribe(Subscription s) { subscription = s; try { this.out = AsynchronousFileChannel.open( file, StandardOpenOption.CREATE, StandardOpenOption.WRITE, StandardOpenOption.TRUNCATE_EXISTING ); subscription.request(1); } catch (IOException e) { subscription.cancel(); ctx.error(e); } } @Override public void onNext(ByteBuf byteBuf) { Promise. async(down -> out.write(byteBuf.nioBuffer(), written, null, down.completionHandler()) ).onError(error -> { byteBuf.release(); subscription.cancel(); out.close(); ctx.error(error); }).then(bytesWritten -> { byteBuf.release(); written += bytesWritten; subscription.request(1); }); } @Override public void onError(Throwable t) { ctx.error(t); try { out.close(); } catch (IOException ignore) { // ignore } } @Override public void onComplete() { try { out.close(); } catch (IOException ignore) { // ignore } ctx.render("ok"); } }) ).test(http -> { ReceivedResponse response = http.request(requestSpec -> requestSpec.method("POST").getBody().text(string)); Assert.assertEquals(response.getBody().getText(), "ok"); String fileContents = Files.toString(file.toFile(), StandardCharsets.UTF_8); Assert.assertEquals(fileContents, string); }); }); } }
getBodyStream(long)
Headers getHeaders()
MediaType getContentType()
"content-type"
header.
If no "content-type"
header is specified, an empty MediaType
is returned.
MediaType.isEmpty()
HostAndPort getRemoteAddress()
HostAndPort getLocalAddress()
boolean isAjaxRequest()
boolean isExpectsContinue()
Expect: 100-Continue
header.
You do not need to send the 100 Continue
status response.
It will be automatically sent when the body is read via getBody()
or getBodyStream(long)
(or variants).
Ratpack will not emit a 417 Expectation Failed
response if the body is not read.
The response specified by the handling code will not be altered, as per normal.
If the header is present for the request, this method will return true
before and after the 100 Continue
response has been sent.
Expect: 100-Continue
headerboolean isChunkedTransfer()
Transfer-Encoding: chunked
header.
See https://en.wikipedia.org/wiki/Chunked_transfer_encoding.
Transfer-Encoding: chunked
headerlong getContentLength()
Will return -1
if no Content-Length
header is present, or is not valid long value.
Instant getTimestamp()
<O> Request add(Class<? super O> type, O object)
add
in interface RegistrySpec
O
- the public type of the registry entrytype
- the public type of the registry entryobject
- the actual registry entry<O> Request add(TypeToken<? super O> type, O object)
add
in interface RegistrySpec
O
- the public type of the registry entrytype
- the public type of the registry entryobject
- the actual registry entryRequest add(Object object)
add
in interface RegistrySpec
object
- the object to add to the registry<O> Request addLazy(Class<O> type, Supplier<? extends O> supplier)
The supplier will be invoked exactly once, when a query is made to the registry of a compatible type of the given type.
addLazy
in interface RegistrySpec
O
- the public type of the registry entrytype
- the public type of the registry entrysupplier
- the supplier for creating the object when needed<O> Request addLazy(TypeToken<O> type, Supplier<? extends O> supplier)
The supplier will be invoked exactly once, when a query is made to the registry of a compatible type of the given type.
addLazy
in interface RegistrySpec
O
- the public type of the registry entrytype
- the public type of the registry entrysupplier
- the supplier for creating the object when needed