public interface Response
The headers and status are configured, before committing the response with one of the send()
methods.
Modifier and Type | Method and Description |
---|---|
Response |
contentType(String contentType)
Sets the response
Content-Type header. |
Cookie |
cookie(String name,
String value)
Creates a new cookie with the given name and value.
|
Cookie |
expireCookie(String name)
Adds a cookie to the response with a 0 max-age, forcing the client to expire it.
|
Set<Cookie> |
getCookies()
The cookies that are to be part of the response.
|
MutableHeaders |
getHeaders()
The response headers.
|
MutableStatus |
getStatus()
The status that will be part of the response when sent.
|
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(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(InputStream inputStream)
Sends the response, using "
application/octet-stream " as the content type (if a content type hasn't
already been set) and the contents of the given input stream as the response body. |
void |
send(String text)
Sends the response, using "
text/plain " as the content type and the given string as the response body. |
void |
send(String contentType,
byte[] bytes)
Sends the response, using the given content type and byte array as the response body.
|
void |
send(String contentType,
ByteBuf buffer)
Sends the response, using the given content type and bytes as the response body.
|
void |
send(String contentType,
InputStream inputStream)
Sends the response, using the given content type and the content of the given input stream as the response body.
|
void |
send(String contentType,
String body)
Sends the response, using the given content type and string as the response body.
|
void |
sendFile(ExecControl execContext,
BasicFileAttributes attributes,
Path file)
Sends the response, using the given content type and the content of the given type as the response body.
|
void |
sendFile(ExecControl execContext,
Path file)
Sends the response, using the given content type and the content of the given type as the response body.
|
void |
sendStream(ExecControl execControl,
org.reactivestreams.Publisher<? extends ByteBuf> stream)
Sends the response, streaming the bytes emitted by the given publisher.
|
Response |
status(int code)
Sets the status line of the response.
|
Response |
status(int code,
String message)
Sets the status line of the response.
|
Response |
status(Status status)
Sets the status line of the response.
|
MutableStatus getStatus()
By default, this will return a "200 OK"
response.
status(int)
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(int code, String message)
code
- The status code of the response to use when it is sent.message
- The status message 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.MutableHeaders getHeaders()
@NonBlocking void send()
@NonBlocking void send(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(String contentType, 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(String contentType, byte[] bytes)
contentType
- The value of the Content-Type
headerbytes
- The response body@NonBlocking void send(InputStream inputStream) throws IOException
application/octet-stream
" as the content type (if a content type hasn't
already been set) and the contents of the given input stream as the response body.inputStream
- The response bodyIOException
- if the input stream cannot be consumed@NonBlocking void send(String contentType, InputStream inputStream) throws IOException
contentType
- The value of the Content-Type
headerinputStream
- response bodyIOException
- if the input stream cannot be consumed@NonBlocking void send(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(String contentType, ByteBuf buffer)
contentType
- The value of the Content-Type
headerbuffer
- The response bodyResponse contentType(String contentType)
Content-Type
header.contentType
- The value of the Content-Type
headerSet<Cookie> getCookies()
The cookies are mutable.
Cookie cookie(String name, 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 cookieCookie expireCookie(String name)
name
- The name of the cookie to expire.@NonBlocking void sendFile(ExecControl execContext, Path file)
Prefer sendFile(ExecControl, java.nio.file.attribute.BasicFileAttributes, java.nio.file.Path)
where
the file attributes have already been retrieved to avoid another IO operation.
execContext
- the execution context to perform any blocking operations withfile
- The file whose contents are to be used as the response body@NonBlocking void sendFile(ExecControl execContext, BasicFileAttributes attributes, Path file)
execContext
- the execution context to perform any blocking operations withattributes
- The attributes of the file, used for the headersfile
- The file whose contents are to be used as the response body@NonBlocking void sendStream(ExecControl execControl, org.reactivestreams.Publisher<? extends 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.throttle(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 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.
The subscription to the publisher will occur via ExecControl.stream(org.reactivestreams.Publisher, org.reactivestreams.Subscriber)
.
execControl
- the execution control to subscribe to the publisher viastream
- a stream of byte bufs to be written to the response