public interface Response
The headers and status are configured, before committing the response with one of the send()
methods.
Modifier and Type | Field and Description |
---|---|
static com.google.common.reflect.TypeToken<Response> |
TYPE
A type token for this type.
|
Modifier and Type | Method and Description |
---|---|
Response |
beforeSend(Action<? super Response> responseFinalizer)
Register a callback to execute with the response immediately before sending it to the client.
|
Response |
contentType(java.lang.CharSequence contentType)
Sets the response
Content-Type header. |
default Response |
contentTypeIfNotSet(java.lang.CharSequence contentType)
Sets the response
Content-Type header, if it has not already been set. |
Response |
contentTypeIfNotSet(java.util.function.Supplier<java.lang.CharSequence> contentType) |
io.netty.handler.codec.http.cookie.Cookie |
cookie(java.lang.String name,
java.lang.String value)
Creates a new cookie with the given name and value.
|
io.netty.handler.codec.http.cookie.Cookie |
expireCookie(java.lang.String name)
Adds a cookie to the response with a 0 max-age, forcing the client to expire it.
|
default Response |
forceCloseConnection()
Forces the closing of the current connection, even if the client requested it to be kept alive.
|
java.util.Set<io.netty.handler.codec.http.cookie.Cookie> |
getCookies()
The cookies that are to be part of the response.
|
MutableHeaders |
getHeaders()
The response headers.
|
Status |
getStatus()
The status that will be part of the response when sent.
|
Response |
noCompress()
Prevents the response from being compressed.
|
void |
send()
Sends the response back to the client, with no body.
|
void |
send(byte[] bytes)
Sends the response, using "
application/octet-stream " as the content type (if a content type hasn't
already been set) and the given byte array as the response body. |
void |
send(io.netty.buffer.ByteBuf buffer)
Sends the response, using "
application/octet-stream " as the content type (if a content type hasn't
already been set) and the given bytes as the response body. |
void |
send(java.lang.CharSequence contentType,
byte[] bytes)
Sends the response, using the given content type and byte array as the response body.
|
void |
send(java.lang.CharSequence contentType,
io.netty.buffer.ByteBuf buffer)
Sends the response, using the given content type and bytes as the response body.
|
void |
send(java.lang.CharSequence contentType,
java.lang.String body)
Sends the response, using the given content type and string as the response body.
|
void |
send(java.lang.String text)
Sends the response, using "
text/plain " as the content type and the given string as the response body. |
void |
sendFile(java.nio.file.Path file)
Sends the response, using the file as the response body.
|
void |
sendStream(Publisher<? extends io.netty.buffer.ByteBuf> stream)
Sends the response, streaming the bytes emitted by the given publisher.
|
default Response |
status(int code)
Sets the status line of the response.
|
Response |
status(Status status)
Sets the status line of the response.
|
static final com.google.common.reflect.TypeToken<Response> TYPE
io.netty.handler.codec.http.cookie.Cookie cookie(java.lang.String name, java.lang.String value)
The cookie will have no expiry. Use the returned cookie object to fine tune the cookie.
name
- The name of the cookievalue
- The value of the cookieio.netty.handler.codec.http.cookie.Cookie expireCookie(java.lang.String name)
If the cookie that you want to expire has an explicit path, you must use Cookie.setPath(String)
on the return
value of this method to have the cookie expire.
name
- The name of the cookie to expire.java.util.Set<io.netty.handler.codec.http.cookie.Cookie> getCookies()
The cookies are mutable.
MutableHeaders getHeaders()
Status getStatus()
By default, this will return a "200 OK"
response.
status(int)
default Response status(int code)
The message used will be the standard for the code.
code
- The status code of the response to use when it is sent.Response status(Status status)
status
- The status of the response to use when it is sent.@NonBlocking void send()
Response contentTypeIfNotSet(java.util.function.Supplier<java.lang.CharSequence> contentType)
@NonBlocking void send(java.lang.String text)
text/plain
" as the content type and the given string as the response body.
Equivalent to calling "send\("text/plain", text)
.
text
- The text to render as a plain text response.@NonBlocking void send(java.lang.CharSequence contentType, java.lang.String body)
The string will be sent in "utf8" encoding, and the given content type will have this appended.
That is, given a contentType
of "application/json
" the actual value for the Content-Type
header will be "application/json;charset=utf8
".
The value given for content type will override any previously set value for this header.
contentType
- The value of the content type headerbody
- The string to render as the body of the response@NonBlocking void send(byte[] bytes)
application/octet-stream
" as the content type (if a content type hasn't
already been set) and the given byte array as the response body.bytes
- The response body@NonBlocking void send(java.lang.CharSequence contentType, byte[] bytes)
contentType
- The value of the Content-Type
headerbytes
- The response body@NonBlocking void send(io.netty.buffer.ByteBuf buffer)
application/octet-stream
" as the content type (if a content type hasn't
already been set) and the given bytes as the response body.buffer
- The response body@NonBlocking void send(java.lang.CharSequence contentType, io.netty.buffer.ByteBuf buffer)
contentType
- The value of the Content-Type
headerbuffer
- The response bodyResponse contentType(java.lang.CharSequence contentType)
Content-Type
header.contentType
- The value of the Content-Type
headerdefault Response contentTypeIfNotSet(java.lang.CharSequence contentType)
Content-Type
header, if it has not already been set.contentType
- The value of the Content-Type
header@NonBlocking void sendFile(java.nio.file.Path file)
This method does not set the content length, content type or anything else.
It is generally preferable to use the Context.render(Object)
method with a file/path object,
or an Chain.files(Action)
.
file
- the response body@NonBlocking void sendStream(Publisher<? extends io.netty.buffer.ByteBuf> stream)
This method does not perform chunked transfer encoding.
It merely sends the raw bytes emitted by the publisher.
As such, it is generally preferable to render chunks
than use this method directly.
The response headers will be sent as is, without the implicit addition of a Content-Length
header like the other send methods.
Back pressure is applied to the given publisher based on the flow control of the network connection.
That is, items are requested from the publisher as they are able to be sent by the underlying Netty layer.
As such, the given publisher MUST respect back pressure.
If this is not feasible, consider using Streams.buffer(org.reactivestreams.Publisher)
.
The back pressure applied will be irregular, based on factors including:
Data requested of the publisher is not always written immediately to the client. Netty maintains its own buffer that is fed by the given publisher. This means that data is more likely ready to send as soon as the client receives it.
If your data source produces a small amount of data that is expensive to produce (i.e. there is a significant latency between a data request and the production of data) you may want to consider an intermediate buffer to maximize throughput to the client. However, this is rarely necessary.
stream
- a stream of byte bufs to be written to the responseResponse beforeSend(@NonBlocking Action<? super Response> responseFinalizer)
This method is often used to add response headers “at the last second”.
The callbacks are executed after one of the send*
methods.
As such, those methods cannot be called during an action given to this method.
responseFinalizer
- the action to execute on the response.this
Response noCompress()
this
default Response forceCloseConnection()
This method can be used when it is desirable to force the client's connection to close, defeating HTTP keep alive. This can be desirable in some networking environments where rate limiting or throttling is performed via edge routers or similar.
This method simply calls getHeaders().set("Connection", "close")
, which has the same effect.
this