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 Pump to pump data with flow control.

no subtypes hierarchy

Initializer
HttpServerResponse(HttpServerResponse unknown)
Inherited Attributes
Attributes inherited from: Object
hash, string
Methods
bodyEndHandlershared default HttpServerResponse bodyEndHandler(Anything()? 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

bytesWrittenshared default Integer bytesWritten()
closeshared default void close()

Close the underlying TCP connection corresponding to the request.

closeHandlershared default HttpServerResponse closeHandler(Anything()? 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

closedshared default Boolean closed()
drainHandlershared actual default HttpServerResponse drainHandler(Anything()? handler)

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

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

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

Parameters:
  • chunk

    the buffer to write before ending the response

endshared default void end(String chunk)

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

Parameters:
  • chunk

    the string to write before ending the response

endshared default void end(String chunk, String enc)

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

endHandlershared default HttpServerResponse endHandler(Anything()? 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

endedshared default Boolean ended()
exceptionHandlershared actual default HttpServerResponse exceptionHandler(Anything(Throwable)? handler)

Set an exception handler.

getStatusCodeshared default Integer getStatusCode()
getStatusMessageshared default String getStatusMessage()
headWrittenshared default Boolean headWritten()
headersshared default MultiMap headers()
headersEndHandlershared default HttpServerResponse headersEndHandler(Anything()? 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

isChunkedshared default Boolean isChunked()
pushshared default HttpServerResponse push(HttpMethod method, String path, Anything(Throwable|HttpServerResponse) handler)

Like push with the host copied from the current request.

pushshared default HttpServerResponse push(HttpMethod method, String host, String path, Anything(Throwable|HttpServerResponse) handler)

Like push with no headers.

pushshared default HttpServerResponse push(HttpMethod method, String path, MultiMap headers, Anything(Throwable|HttpServerResponse) handler)

Like push with the host copied from the current request.

pushshared default HttpServerResponse push(HttpMethod method, String host, String path, MultiMap headers, Anything(Throwable|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

putHeadershared default HttpServerResponse putHeader(String name, String value)

Put an HTTP header

Parameters:
  • name

    the header name

  • value

    the header value.

putTrailershared default HttpServerResponse putTrailer(String name, String value)

Put an HTTP trailer

Parameters:
  • name

    the trailer name

  • value

    the trailer value

resetshared default void reset()

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

resetshared default void reset(Integer code)

Reset this HTTP/2 stream with the error code.

Parameters:
  • code

    the error code

sendFileshared default HttpServerResponse sendFile(String filename)

Same as sendFile using offset @code{0} which means starting from the beginning of the file.

Parameters:
  • filename

    path to the file to serve

sendFileshared default HttpServerResponse sendFile(String filename, Anything(Throwable?) resultHandler)

Like sendFile 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

sendFileshared default HttpServerResponse sendFile(String filename, Integer offset)

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

sendFileshared default HttpServerResponse sendFile(String filename, Integer offset, Anything(Throwable?) resultHandler)

Like sendFile 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

sendFileshared default HttpServerResponse sendFile(String filename, Integer offset, Integer 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

    length to serve to

sendFileshared default HttpServerResponse sendFile(String filename, Integer offset, Integer length, Anything(Throwable?) resultHandler)

Like sendFile 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

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

setStatusCodeshared default HttpServerResponse setStatusCode(Integer 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.

setStatusMessageshared default HttpServerResponse setStatusMessage(String statusMessage)

Set the status message

setWriteQueueMaxSizeshared actual default HttpServerResponse setWriteQueueMaxSize(Integer maxSize)

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 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…

streamIdshared default Integer streamId()
trailersshared default MultiMap trailers()
writeshared actual default HttpServerResponse write(Buffer data)
writeshared default HttpServerResponse write(String chunk)

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

Parameters:
  • chunk

    the string to write

writeshared default HttpServerResponse 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

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

writeCustomFrameshared default HttpServerResponse writeCustomFrame(HttpFrame frame)

Like writeCustomFrame but with an HttpFrame.

Parameters:
  • frame

    the frame to write

writeCustomFrameshared default HttpServerResponse writeCustomFrame(Integer type, Integer 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

writeQueueFullshared actual default Boolean writeQueueFull()

This will return true if there are more bytes in the write queue than the value set using setWriteQueueMaxSize

Inherited Methods
Methods inherited from: Object
equals
Methods inherited from: StreamBase
Methods inherited from: WriteStream<T>