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)

Provide a handler that will be called just before the last part of the body is written to the wire and the response is ended.

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

Parameters:
  • handler

    the handler

bytesWrittenshared default Integer bytesWritten()

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

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 will be called if the underlying connection closes before the response is complete.

Parameters:
  • handler

    the handler

closedshared default Boolean closed()

@return has the underlying TCP connection corresponding to the request already been 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 has been reduced to maxSize / 2. See Pump for an example of this being used.

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

endedshared default Boolean ended()

@return has the response already ended?

exceptionHandlershared actual default HttpServerResponse exceptionHandler(Anything(Throwable)? handler)

Set an exception handler.

getStatusCodeshared default Integer getStatusCode()

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

getStatusMessageshared default String getStatusMessage()

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

headWrittenshared default Boolean headWritten()

@return have the headers for the response already been written?

headersshared default MultiMap headers()

@return The HTTP 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()

@return is the response chunked?

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

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 bytes in the write queue. This is used as an indicator by classes such as Pump to provide flow control.

trailersshared default MultiMap trailers()

@return The HTTP trailers

writeshared actual default HttpServerResponse write(Buffer data)

Write some data to the stream. The data is put on an internal write queue, and the write actually happens asynchronously. To avoid running out of memory by putting too much on the write queue, check the writeQueueFull method before writing. This is done automatically if using a Pump.

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

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>