io.vertx.core.http

Interface HttpServerResponse

All Superinterfaces:

StreamBase, WriteStream<Buffer>

public interface HttpServerResponse
extends WriteStream<Buffer>

Represents a server-side HTTP response.

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 Pipe to pipe data with flow control.

Author:

Tim Fox

Method Summary

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.
Future<Void>	end() Ends the response.
Future<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
Future<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
Future<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()
default Future<HttpServerResponse>	push(HttpMethod method, String path) Same as push(HttpMethod, String, Handler) but with an handler called when the operation completes
default 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.
default Future<HttpServerResponse>	push(HttpMethod method, String path, MultiMap headers) Same as push(HttpMethod, String, MultiMap, Handler) but with an handler called when the operation completes
default 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.
default Future<HttpServerResponse>	push(HttpMethod method, String host, String path) Same as push(HttpMethod, String, String, Handler) but with an handler called when the operation completes
default HttpServerResponse	push(HttpMethod method, String host, String path, Handler<AsyncResult<HttpServerResponse>> handler) Like push(HttpMethod, String, String, MultiMap, Handler) with no headers.
Future<HttpServerResponse>	push(HttpMethod method, String host, String path, MultiMap headers) Same as push(HttpMethod, String, String, MultiMap, Handler) but with an handler called when the operation completes
default 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 boolean	reset() Reset this HTTP/2 stream with the error code 0.
boolean	reset(long code) Reset this response: for HTTP/2, send an HTTP/2 reset frame with the specified error code for HTTP/1.x, close the connection when the current response has not yet been sent When the response has already been sent nothing happens and false is returned as indicator.
default Future<Void>	send() Like send(Handler) but returns a Future of the asynchronous result
default Future<Void>	send(Buffer body) Like send(Buffer, Handler) but returns a Future of the asynchronous result
default void	send(Buffer body, Handler<AsyncResult<Void>> handler) Send the request with a buffer body.
default void	send(Handler<AsyncResult<Void>> handler) Send the request with an empty body.
default Future<Void>	send(ReadStream<Buffer> body) Like send(ReadStream, Handler) but returns a Future of the asynchronous result
default void	send(ReadStream<Buffer> body, Handler<AsyncResult<Void>> handler) Send the request with a stream body.
default Future<Void>	send(String body) Like send(String, Handler) but returns a Future of the asynchronous result
default void	send(String body, Handler<AsyncResult<Void>> handler) Send the request with a string body.
default Future<Void>	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 Future<Void>	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.
Future<Void>	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()
Future<Void>	write(String chunk) Write a String to the response body, encoded in UTF-8.
void	write(String chunk, Handler<AsyncResult<Void>> handler) Same as write(String) but with an handler called when the operation completes
Future<Void>	write(String chunk, String enc) Write a String to the response body, encoded using the encoding enc.
void	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.

Methods inherited from interface io.vertx.core.streams.WriteStream

end, write, write, writeQueueFull

Method Detail

exceptionHandler

HttpServerResponse exceptionHandler(Handler<Throwable> handler)

Description copied from interface: WriteStream

Set an exception handler on the write stream.

Specified by:

exceptionHandler in interface StreamBase

Specified by:

exceptionHandler in interface WriteStream<Buffer>

Parameters:

handler - the exception handler

Returns:

a reference to this, so the API can be used fluently

setWriteQueueMaxSize

HttpServerResponse setWriteQueueMaxSize(int maxSize)

Description copied from interface: WriteStream

Set the maximum size of the write queue to 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 Pipe to provide flow control.

The value is defined by the implementation of the stream, e.g in bytes for a NetSocket, etc...

Specified by:

setWriteQueueMaxSize in interface WriteStream<Buffer>

Parameters:

maxSize - the max size of the write stream

Returns:

a reference to this, so the API can be used fluently

drainHandler

HttpServerResponse drainHandler(Handler<Void> handler)

Description copied from interface: WriteStream

Set a drain handler on the stream. If the write queue is full, then the handler will be called when the write queue is ready to accept buffers again. See Pipe 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.

Specified by:

drainHandler in interface WriteStream<Buffer>

Parameters:

handler - the handler

Returns:

a reference to this, so the API can be used fluently

getStatusCode

int getStatusCode()

Returns:

the HTTP status code of the response. The default is 200 representing OK.

setStatusCode

HttpServerResponse setStatusCode(int statusCode)

Set the status code. If the status message hasn't been explicitly set, a default status message corresponding to the code will be looked-up and used.

Returns:

a reference to this, so the API can be used fluently

getStatusMessage

String getStatusMessage()

Returns:

the HTTP status message of the response. If this is not specified a default value will be used depending on what setStatusCode(int) has been set to.

setStatusMessage

HttpServerResponse setStatusMessage(String statusMessage)

Set the status message

Returns:

a reference to this, so the API can be used fluently

setChunked

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.

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.

Returns:

a reference to this, so the API can be used fluently

isChunked

boolean isChunked()

Returns:

is the response chunked?

headers

MultiMap headers()

Returns:

The HTTP headers

putHeader

HttpServerResponse putHeader(String name,
                             String value)

Put an HTTP header

Parameters:

name - the header name

value - the header value.

Returns:

a reference to this, so the API can be used fluently

putHeader

HttpServerResponse putHeader(CharSequence name,
                             CharSequence value)

Like putHeader(String, String) but using CharSequence

putHeader

HttpServerResponse putHeader(String name,
                             Iterable<String> values)

Like putHeader(String, String) but providing multiple values via a String Iterable

putHeader

HttpServerResponse putHeader(CharSequence name,
                             Iterable<CharSequence> values)

Like putHeader(String, Iterable) but with CharSequence Iterable

trailers

MultiMap trailers()

Returns:

The HTTP trailers

putTrailer

HttpServerResponse putTrailer(String name,
                              String value)

Put an HTTP trailer

Parameters:

name - the trailer name

value - the trailer value

Returns:

a reference to this, so the API can be used fluently

putTrailer

HttpServerResponse putTrailer(CharSequence name,
                              CharSequence value)

Like putTrailer(String, String) but using CharSequence

putTrailer

HttpServerResponse putTrailer(String name,
                              Iterable<String> values)

Like putTrailer(String, String) but providing multiple values via a String Iterable

putTrailer

HttpServerResponse putTrailer(CharSequence name,
                              Iterable<CharSequence> value)

Like putTrailer(String, Iterable) but with CharSequence Iterable

closeHandler

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.

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.

Parameters:

handler - the handler

Returns:

a reference to this, so the API can be used fluently

endHandler

HttpServerResponse endHandler(Handler<Void> handler)

Set an end handler for the response. This will be called when the response is disposed to allow consistent cleanup of the response.

Parameters:

handler - the handler

Returns:

a reference to this, so the API can be used fluently

write

Future<Void> write(String chunk,
                   String enc)

Write a String to the response body, encoded using the encoding enc.

Parameters:

chunk - the string to write

enc - the encoding to use

Returns:

a future completed with the body result

write

void write(String chunk,
           String enc,
           Handler<AsyncResult<Void>> handler)

Same as write(String, String) but with an handler called when the operation completes

write

Future<Void> write(String chunk)

Write a String to the response body, encoded in UTF-8.

Parameters:

chunk - the string to write

Returns:

a future completed with the body result

write

void write(String chunk,
           Handler<AsyncResult<Void>> handler)

Same as write(String) but with an handler called when the operation completes

writeContinue

HttpServerResponse writeContinue()

Used to write an interim 100 Continue response to signify that the client should send the rest of the request. Must only be used if the request contains an "Expect:100-Continue" header

Returns:

a reference to this, so the API can be used fluently

end

Future<Void> end(String chunk)

Same as end(Buffer) but writes a String in UTF-8 encoding before ending the response.

Parameters:

chunk - the string to write before ending the response

Returns:

a future completed with the body result

end

void end(String chunk,
         Handler<AsyncResult<Void>> handler)

Same as end(String) but with an handler called when the operation completes

end

Future<Void> end(String chunk,
                 String enc)

Same as end(Buffer) but writes a String with the specified encoding before ending the response.

Parameters:

chunk - the string to write before ending the response

enc - the encoding to use

Returns:

a future completed with the body result

end

void end(String chunk,
         String enc,
         Handler<AsyncResult<Void>> handler)

Same as end(String, String) but with an handler called when the operation completes

end

Future<Void> end(Buffer chunk)

Same as 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.

Specified by:

end in interface WriteStream<Buffer>

Parameters:

chunk - the buffer to write before ending the response

Returns:

a future completed with the body result

end

void end(Buffer chunk,
         Handler<AsyncResult<Void>> handler)

Same as end(Buffer) but with an handler called when the operation completes

Specified by:

end in interface WriteStream<Buffer>

end

Future<Void> end()

Ends the response. If no data has been written to the response body, the actual response won't get written until this method gets called.

Once the response has ended, it cannot be used any more.

Specified by:

end in interface WriteStream<Buffer>

Returns:

a future completed with the body result

send

default void send(Handler<AsyncResult<Void>> handler)

Send the request with an empty body.

Parameters:

handler - the completion handler

send

default Future<Void> send()

Like send(Handler) but returns a Future of the asynchronous result

send

default void send(String body,
                  Handler<AsyncResult<Void>> handler)

Send the request with a string body.

Parameters:

handler - the completion handler

send

default Future<Void> send(String body)

Like send(String, Handler) but returns a Future of the asynchronous result

send

default void send(Buffer body,
                  Handler<AsyncResult<Void>> handler)

Send the request with a buffer body.

Parameters:

handler - the completion handler

send

default Future<Void> send(Buffer body)

Like send(Buffer, Handler) but returns a Future of the asynchronous result

send

default void send(ReadStream<Buffer> body,
                  Handler<AsyncResult<Void>> handler)

Send the request with a stream body.

If the HttpHeaders.CONTENT_LENGTH is set then the request assumes this is the length of the {stream}, otherwise the request will set a chunked HttpHeaders.CONTENT_ENCODING.

Parameters:

handler - the completion handler

send

default Future<Void> send(ReadStream<Buffer> body)

Like send(ReadStream, Handler) but returns a Future of the asynchronous result

sendFile

default Future<Void> sendFile(String filename)

Same as sendFile(String, long) using offset @code{0} which means starting from the beginning of the file.

Parameters:

filename - path to the file to serve

Returns:

a future completed with the body result

sendFile

default Future<Void> 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.

Parameters:

filename - path to the file to serve

offset - offset to start serving from

Returns:

a future completed with the body result

sendFile

Future<Void> 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. 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.

Parameters:

filename - path to the file to serve

offset - offset to start serving from

length - the number of bytes to send

Returns:

a future completed with the body result

sendFile

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.

Parameters:

filename - path to the file to serve

resultHandler - handler that will be called on completion

Returns:

a reference to this, so the API can be used fluently

sendFile

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.

Parameters:

filename - path to the file to serve

offset - the offset to serve from

resultHandler - handler that will be called on completion

Returns:

a reference to this, so the API can be used fluently

sendFile

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.

Parameters:

filename - path to the file to serve

offset - the offset to serve from

length - the length to serve to

resultHandler - handler that will be called on completion

Returns:

a reference to this, so the API can be used fluently

close

void close()

Close the underlying TCP connection corresponding to the request.

ended

boolean ended()

Returns:

has the response already ended?

closed

boolean closed()

Returns:

has the underlying TCP connection corresponding to the request already been closed?

headWritten

boolean headWritten()

Returns:

have the headers for the response already been written?

headersEndHandler

HttpServerResponse headersEndHandler(Handler<Void> handler)

Provide a handler that will be called just before the headers are written to the wire.

This provides a hook allowing you to add any more headers or do any more operations before this occurs.

Parameters:

handler - the handler

Returns:

a reference to this, so the API can be used fluently

bodyEndHandler

HttpServerResponse bodyEndHandler(Handler<Void> handler)

Provides a handler that will be called after the last part of the body is written to the wire. The handler is called asynchronously of when the response has been received by the client. This provides a hook allowing you to do more operations once the request has been sent over the wire such as resource cleanup.

Parameters:

handler - the handler

Returns:

a reference to this, so the API can be used fluently

bytesWritten

long bytesWritten()

Returns:

the total number of bytes written for the body of the response.

streamId

int streamId()

Returns:

the id of the stream of this response, -1 for HTTP/1.x

push

default HttpServerResponse push(HttpMethod method,
                                String host,
                                String path,
                                Handler<AsyncResult<HttpServerResponse>> handler)

Like push(HttpMethod, String, String, MultiMap, Handler) with no headers.

push

default Future<HttpServerResponse> push(HttpMethod method,
                                        String host,
                                        String path)

Same as push(HttpMethod, String, String, Handler) but with an handler called when the operation completes

push

default 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.

push

default Future<HttpServerResponse> push(HttpMethod method,
                                        String path,
                                        MultiMap headers)

Same as push(HttpMethod, String, MultiMap, Handler) but with an handler called when the operation completes

push

default 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.

push

default Future<HttpServerResponse> push(HttpMethod method,
                                        String path)

Same as push(HttpMethod, String, Handler) but with an handler called when the operation completes

push

default 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.

Parameters:

method - the method of the promised request

host - the host of the promised request

path - the path of the promised request

headers - the headers of the promised request

handler - the handler notified when the response can be written

Returns:

a reference to this, so the API can be used fluently

push

Future<HttpServerResponse> push(HttpMethod method,
                                String host,
                                String path,
                                MultiMap headers)

Same as push(HttpMethod, String, String, MultiMap, Handler) but with an handler called when the operation completes

reset

default boolean reset()

Reset this HTTP/2 stream with the error code 0.

reset

boolean reset(long code)

Reset this response:

• for HTTP/2, send an HTTP/2 reset frame with the specified error code
• for HTTP/1.x, close the connection when the current response has not yet been sent

When the response has already been sent nothing happens and false is returned as indicator.

Parameters:

code - the error code

Returns:

true when reset has been performed

writeCustomFrame

HttpServerResponse writeCustomFrame(int type,
                                    int flags,
                                    Buffer payload)

Write an HTTP/2 frame to the response, allowing to extend the HTTP/2 protocol.

The frame is sent immediatly and is not subject to flow control.

Parameters:

type - the 8-bit frame type

flags - the 8-bit frame flags

payload - the frame payload

Returns:

a reference to this, so the API can be used fluently

writeCustomFrame

default HttpServerResponse writeCustomFrame(HttpFrame frame)

Like writeCustomFrame(int, int, Buffer) but with an HttpFrame.

Parameters:

frame - the frame to write

setStreamPriority

default HttpServerResponse setStreamPriority(StreamPriority streamPriority)

Sets the priority of the associated stream

This is not implemented for HTTP/1.x.

Parameters:

streamPriority - the priority for this request's stream

addCookie

HttpServerResponse addCookie(Cookie cookie)

Add a cookie. This will be sent back to the client in the response.

Parameters:

cookie - the cookie

Returns:

a reference to this, so the API can be used fluently

removeCookie

default Cookie removeCookie(String name)

Expire a cookie, notifying a User Agent to remove it from its cookie jar.

Parameters:

name - the name of the cookie

Returns:

the cookie, if it existed, or null

removeCookie

Cookie removeCookie(String name,
                    boolean invalidate)

Remove a cookie from the cookie set. If invalidate is true then it will expire a cookie, notifying a User Agent to remove it from its cookie jar.

Parameters:

name - the name of the cookie

Returns:

the cookie, if it existed, or null