public interface HttpServerResponse extends WriteStream<Buffer>
An instance of this is created and associated to every instance of
HttpServerRequest
that.
It allows the developer to control the HTTP response that is sent back to the client for a particular HTTP request.
It contains methods that allow HTTP headers and trailers to be set, and for a body to be written out to the response.
It also allows files to be streamed by the kernel directly from disk to the outgoing HTTP connection, bypassing user space altogether (where supported by the underlying operating system). This is a very efficient way of serving files from the server since buffers do not have to be read one by one from the file and written to the outgoing socket.
It implements WriteStream
so it can be used with
Pump
to pump data with flow control.
Modifier and Type | Method and Description |
---|---|
HttpServerResponse |
addCookie(Cookie cookie)
Add a cookie.
|
HttpServerResponse |
bodyEndHandler(Handler<Void> handler)
Provides a handler that will be called after the last part of the body is written to the wire.
|
long |
bytesWritten() |
void |
close()
Close the underlying TCP connection corresponding to the request.
|
boolean |
closed() |
HttpServerResponse |
closeHandler(Handler<Void> handler)
Set a close handler for the response, this is called when the underlying connection is closed and the response
was still using the connection.
|
HttpServerResponse |
drainHandler(Handler<Void> handler)
Set a drain handler on the stream.
|
void |
end()
Ends the response.
|
void |
end(Buffer chunk)
Same as
end() but writes some data to the response body before ending. |
void |
end(Buffer chunk,
Handler<AsyncResult<Void>> handler)
Same as
end(Buffer) but with an handler called when the operation completes |
void |
end(String chunk)
Same as
end(Buffer) but writes a String in UTF-8 encoding before ending the response. |
void |
end(String chunk,
Handler<AsyncResult<Void>> handler)
Same as
end(String) but with an handler called when the operation completes |
void |
end(String chunk,
String enc)
Same as
end(Buffer) but writes a String with the specified encoding before ending the response. |
void |
end(String chunk,
String enc,
Handler<AsyncResult<Void>> handler)
Same as
end(String, String) but with an handler called when the operation completes |
boolean |
ended() |
HttpServerResponse |
endHandler(Handler<Void> handler)
Set an end handler for the response.
|
HttpServerResponse |
exceptionHandler(Handler<Throwable> handler)
Set an exception handler on the write stream.
|
int |
getStatusCode() |
String |
getStatusMessage() |
MultiMap |
headers() |
HttpServerResponse |
headersEndHandler(Handler<Void> handler)
Provide a handler that will be called just before the headers are written to the wire.
|
boolean |
headWritten() |
boolean |
isChunked() |
HttpServerResponse |
push(HttpMethod method,
String path,
Handler<AsyncResult<HttpServerResponse>> handler)
Like
push(HttpMethod, String, String, MultiMap, Handler) with the host copied from the current request. |
HttpServerResponse |
push(HttpMethod method,
String path,
MultiMap headers,
Handler<AsyncResult<HttpServerResponse>> handler)
Like
push(HttpMethod, String, String, MultiMap, Handler) with the host copied from the current request. |
HttpServerResponse |
push(HttpMethod method,
String host,
String path,
Handler<AsyncResult<HttpServerResponse>> handler)
Like
push(HttpMethod, String, String, MultiMap, Handler) with no headers. |
HttpServerResponse |
push(HttpMethod method,
String host,
String path,
MultiMap headers,
Handler<AsyncResult<HttpServerResponse>> handler)
Push a response to the client.
The
handler will be notified with a success when the push can be sent and with
a failure when the client has disabled push or reset the push before it has been sent.
The handler may be queued if the client has reduced the maximum number of streams the server can push
concurrently.
Push can be sent only for peer initiated streams and if the response is not ended. |
HttpServerResponse |
putHeader(CharSequence name,
CharSequence value)
Like
putHeader(String, String) but using CharSequence |
HttpServerResponse |
putHeader(CharSequence name,
Iterable<CharSequence> values)
Like
putHeader(String, Iterable) but with CharSequence Iterable |
HttpServerResponse |
putHeader(String name,
Iterable<String> values)
Like
putHeader(String, String) but providing multiple values via a String Iterable |
HttpServerResponse |
putHeader(String name,
String value)
Put an HTTP header
|
HttpServerResponse |
putTrailer(CharSequence name,
CharSequence value)
Like
putTrailer(String, String) but using CharSequence |
HttpServerResponse |
putTrailer(CharSequence name,
Iterable<CharSequence> value)
Like
putTrailer(String, Iterable) but with CharSequence Iterable |
HttpServerResponse |
putTrailer(String name,
Iterable<String> values)
Like
putTrailer(String, String) but providing multiple values via a String Iterable |
HttpServerResponse |
putTrailer(String name,
String value)
Put an HTTP trailer
|
default Cookie |
removeCookie(String name)
Expire a cookie, notifying a User Agent to remove it from its cookie jar.
|
Cookie |
removeCookie(String name,
boolean invalidate)
Remove a cookie from the cookie set.
|
default void |
reset()
Reset this HTTP/2 stream with the error code
0 . |
void |
reset(long code)
Reset this HTTP/2 stream with the error
code . |
default HttpServerResponse |
sendFile(String filename)
Same as
sendFile(String, long) using offset @code{0} which means starting from the beginning of the file. |
default HttpServerResponse |
sendFile(String filename,
Handler<AsyncResult<Void>> resultHandler)
Like
sendFile(String) but providing a handler which will be notified once the file has been completely
written to the wire. |
default HttpServerResponse |
sendFile(String filename,
long offset)
Same as
sendFile(String, long, long) using length @code{Long.MAX_VALUE} which means until the end of the
file. |
default HttpServerResponse |
sendFile(String filename,
long offset,
Handler<AsyncResult<Void>> resultHandler)
Like
sendFile(String, long) but providing a handler which will be notified once the file has been completely
written to the wire. |
HttpServerResponse |
sendFile(String filename,
long offset,
long length)
Ask the OS to stream a file as specified by
filename directly
from disk to the outgoing connection, bypassing userspace altogether
(where supported by the underlying operating system. |
HttpServerResponse |
sendFile(String filename,
long offset,
long length,
Handler<AsyncResult<Void>> resultHandler)
Like
sendFile(String, long, long) but providing a handler which will be notified once the file has been
completely written to the wire. |
HttpServerResponse |
setChunked(boolean chunked)
If
chunked is true , this response will use HTTP chunked encoding, and each call to write to the body
will correspond to a new HTTP chunk sent on the wire. |
HttpServerResponse |
setStatusCode(int statusCode)
Set the status code.
|
HttpServerResponse |
setStatusMessage(String statusMessage)
Set the status message
|
default HttpServerResponse |
setStreamPriority(StreamPriority streamPriority)
Sets the priority of the associated stream
This is not implemented for HTTP/1.x.
|
HttpServerResponse |
setWriteQueueMaxSize(int maxSize)
Set the maximum size of the write queue to
maxSize . |
int |
streamId() |
MultiMap |
trailers() |
HttpServerResponse |
write(Buffer data)
Write some data to the stream.
|
HttpServerResponse |
write(Buffer data,
Handler<AsyncResult<Void>> handler)
Same as
write(Buffer) but with an handler called when the operation completes |
HttpServerResponse |
write(String chunk)
Write a
String to the response body, encoded in UTF-8. |
HttpServerResponse |
write(String chunk,
Handler<AsyncResult<Void>> handler)
Same as
write(String) but with an handler called when the operation completes |
HttpServerResponse |
write(String chunk,
String enc)
Write a
String to the response body, encoded using the encoding enc . |
HttpServerResponse |
write(String chunk,
String enc,
Handler<AsyncResult<Void>> handler)
Same as
write(String, String) but with an handler called when the operation completes |
HttpServerResponse |
writeContinue()
Used to write an interim 100 Continue response to signify that the client should send the rest of the request.
|
default HttpServerResponse |
writeCustomFrame(HttpFrame frame)
Like
writeCustomFrame(int, int, Buffer) but with an HttpFrame . |
HttpServerResponse |
writeCustomFrame(int type,
int flags,
Buffer payload)
Write an HTTP/2 frame to the response, allowing to extend the HTTP/2 protocol.
|
end, writeQueueFull
HttpServerResponse exceptionHandler(Handler<Throwable> handler)
WriteStream
exceptionHandler
in interface StreamBase
exceptionHandler
in interface WriteStream<Buffer>
handler
- the exception handlerHttpServerResponse write(Buffer data)
WriteStream
WriteStream.writeQueueFull()
method before writing. This is done automatically if using a Pump
.write
in interface WriteStream<Buffer>
data
- the data to writeHttpServerResponse write(Buffer data, Handler<AsyncResult<Void>> handler)
write(Buffer)
but with an handler
called when the operation completeswrite
in interface WriteStream<Buffer>
HttpServerResponse setWriteQueueMaxSize(int maxSize)
WriteStream
maxSize
. You will still be able to write to the stream even
if there is more than maxSize
items in the write queue. This is used as an indicator by classes such as
Pump
to provide flow control.
The value is defined by the implementation of the stream, e.g in bytes for a
NetSocket
, the number of Message
for a
MessageProducer
, etc...setWriteQueueMaxSize
in interface WriteStream<Buffer>
maxSize
- the max size of the write streamHttpServerResponse drainHandler(Handler<Void> handler)
WriteStream
Pump
for an example of this being used.
The stream implementation defines when the drain handler, for example it could be when the queue size has been
reduced to maxSize / 2
.drainHandler
in interface WriteStream<Buffer>
handler
- the handlerint getStatusCode()
200
representing OK
.HttpServerResponse setStatusCode(int statusCode)
String getStatusMessage()
setStatusCode(int)
has been set to.HttpServerResponse setStatusMessage(String statusMessage)
HttpServerResponse setChunked(boolean chunked)
chunked
is true
, this response will use HTTP chunked encoding, and each call to write to the body
will correspond to a new HTTP chunk sent on the wire.
If chunked encoding is used the HTTP header Transfer-Encoding
with a value of Chunked
will be
automatically inserted in the response.
If chunked
is false
, this response will not use HTTP chunked encoding, and therefore the total size
of any data that is written in the respone body must be set in the Content-Length
header before any
data is written out.
An HTTP chunked response is typically used when you do not know the total size of the request body up front.
boolean isChunked()
MultiMap headers()
HttpServerResponse putHeader(String name, String value)
name
- the header namevalue
- the header value.HttpServerResponse putHeader(CharSequence name, CharSequence value)
putHeader(String, String)
but using CharSequenceHttpServerResponse putHeader(String name, Iterable<String> values)
putHeader(String, String)
but providing multiple values via a String IterableHttpServerResponse putHeader(CharSequence name, Iterable<CharSequence> values)
putHeader(String, Iterable)
but with CharSequence IterableMultiMap trailers()
HttpServerResponse putTrailer(String name, String value)
name
- the trailer namevalue
- the trailer valueHttpServerResponse putTrailer(CharSequence name, CharSequence value)
putTrailer(String, String)
but using CharSequenceHttpServerResponse putTrailer(String name, Iterable<String> values)
putTrailer(String, String)
but providing multiple values via a String IterableHttpServerResponse putTrailer(CharSequence name, Iterable<CharSequence> value)
putTrailer(String, Iterable)
but with CharSequence IterableHttpServerResponse closeHandler(Handler<Void> handler)
For HTTP/1.x it is called when the connection is closed before end()
is called, therefore it is not
guaranteed to be called.
For HTTP/2 it is called when the related stream is closed, and therefore it will be always be called.
handler
- the handlerHttpServerResponse endHandler(Handler<Void> handler)
handler
- the handlerHttpServerResponse write(String chunk, String enc)
String
to the response body, encoded using the encoding enc
.chunk
- the string to writeenc
- the encoding to useHttpServerResponse write(String chunk, String enc, Handler<AsyncResult<Void>> handler)
write(String, String)
but with an handler
called when the operation completesHttpServerResponse write(String chunk)
String
to the response body, encoded in UTF-8.chunk
- the string to writeHttpServerResponse write(String chunk, Handler<AsyncResult<Void>> handler)
write(String)
but with an handler
called when the operation completesHttpServerResponse writeContinue()
void end(String chunk)
end(Buffer)
but writes a String in UTF-8 encoding before ending the response.chunk
- the string to write before ending the responsevoid end(String chunk, Handler<AsyncResult<Void>> handler)
end(String)
but with an handler
called when the operation completesvoid end(String chunk, String enc)
end(Buffer)
but writes a String with the specified encoding before ending the response.chunk
- the string to write before ending the responseenc
- the encoding to usevoid end(String chunk, String enc, Handler<AsyncResult<Void>> handler)
end(String, String)
but with an handler
called when the operation completesvoid end(Buffer chunk)
end()
but writes some data to the response body before ending. If the response is not chunked and
no other data has been written then the @code{Content-Length} header will be automatically set.end
in interface WriteStream<Buffer>
chunk
- the buffer to write before ending the responsevoid end(Buffer chunk, Handler<AsyncResult<Void>> handler)
end(Buffer)
but with an handler
called when the operation completesend
in interface WriteStream<Buffer>
void end()
Once the response has ended, it cannot be used any more.
end
in interface WriteStream<Buffer>
default HttpServerResponse sendFile(String filename)
sendFile(String, long)
using offset @code{0} which means starting from the beginning of the file.filename
- path to the file to servedefault HttpServerResponse sendFile(String filename, long offset)
sendFile(String, long, long)
using length @code{Long.MAX_VALUE} which means until the end of the
file.filename
- path to the file to serveoffset
- offset to start serving fromHttpServerResponse sendFile(String filename, long offset, long length)
filename
directly
from disk to the outgoing connection, bypassing userspace altogether
(where supported by the underlying operating system.
This is a very efficient way to serve files.The actual serve is asynchronous and may not complete until some time after this method has returned.
filename
- path to the file to serveoffset
- offset to start serving fromlength
- the number of bytes to senddefault HttpServerResponse sendFile(String filename, Handler<AsyncResult<Void>> resultHandler)
sendFile(String)
but providing a handler which will be notified once the file has been completely
written to the wire.filename
- path to the file to serveresultHandler
- handler that will be called on completiondefault HttpServerResponse sendFile(String filename, long offset, Handler<AsyncResult<Void>> resultHandler)
sendFile(String, long)
but providing a handler which will be notified once the file has been completely
written to the wire.filename
- path to the file to serveoffset
- the offset to serve fromresultHandler
- handler that will be called on completionHttpServerResponse sendFile(String filename, long offset, long length, Handler<AsyncResult<Void>> resultHandler)
sendFile(String, long, long)
but providing a handler which will be notified once the file has been
completely written to the wire.filename
- path to the file to serveoffset
- the offset to serve fromlength
- the length to serve toresultHandler
- handler that will be called on completionvoid close()
boolean ended()
boolean closed()
boolean headWritten()
HttpServerResponse headersEndHandler(Handler<Void> handler)
This provides a hook allowing you to add any more headers or do any more operations before this occurs.
handler
- the handlerHttpServerResponse bodyEndHandler(Handler<Void> handler)
handler
- the handlerlong bytesWritten()
int streamId()
HttpServerResponse push(HttpMethod method, String host, String path, Handler<AsyncResult<HttpServerResponse>> handler)
push(HttpMethod, String, String, MultiMap, Handler)
with no headers.HttpServerResponse push(HttpMethod method, String path, MultiMap headers, Handler<AsyncResult<HttpServerResponse>> handler)
push(HttpMethod, String, String, MultiMap, Handler)
with the host copied from the current request.HttpServerResponse push(HttpMethod method, String path, Handler<AsyncResult<HttpServerResponse>> handler)
push(HttpMethod, String, String, MultiMap, Handler)
with the host copied from the current request.HttpServerResponse push(HttpMethod method, String host, String path, MultiMap headers, Handler<AsyncResult<HttpServerResponse>> handler)
handler
will be notified with a success when the push can be sent and with
a failure when the client has disabled push or reset the push before it has been sent.
The handler
may be queued if the client has reduced the maximum number of streams the server can push
concurrently.
Push can be sent only for peer initiated streams and if the response is not ended.method
- the method of the promised requesthost
- the host of the promised requestpath
- the path of the promised requestheaders
- the headers of the promised requesthandler
- the handler notified when the response can be writtendefault void reset()
0
.void reset(long code)
code
.code
- the error codeHttpServerResponse writeCustomFrame(int type, int flags, Buffer payload)
The frame is sent immediatly and is not subject to flow control.
type
- the 8-bit frame typeflags
- the 8-bit frame flagspayload
- the frame payloaddefault HttpServerResponse writeCustomFrame(HttpFrame frame)
writeCustomFrame(int, int, Buffer)
but with an HttpFrame
.frame
- the frame to writedefault HttpServerResponse setStreamPriority(StreamPriority streamPriority)
streamPriority
- the priority for this request's streamHttpServerResponse addCookie(Cookie cookie)
cookie
- the cookiedefault Cookie removeCookie(String name)
name
- the name of the cookieCopyright © 2023 Eclipse. All rights reserved.