Package: io.vertx.groovy.core.http

## [Groovy] Class HttpServerResponse

- io.vertx.groovy.core.http.HttpServerResponse

- All Implemented Interfaces and Traits:
    WriteStream

      @groovy.transform.CompileStatic
      class HttpServerResponse
      extends java.lang.Object

  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.

- - ### Constructor Summary

    Constructors
    Constructor and description
    `HttpServerResponse (java.lang.Object delegate)`

  - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `HttpServerResponse` | `bodyEndHandler(io.vertx.core.Handler<java.lang.Void> 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.
    `long` | `bytesWritten()` Returns: the total number of bytes written for the body of the response.
    `void` | `close()` Close the underlying TCP connection corresponding to the request.
    `HttpServerResponse` | `closeHandler(io.vertx.core.Handler<java.lang.Void> handler)` Set a close handler for the response.
    `boolean` | `closed()` Returns: has the underlying TCP connection corresponding to the request already been closed?
    `HttpServerResponse` | `drainHandler(io.vertx.core.Handler<java.lang.Void> handler)`
    `void` | `end(java.lang.String chunk)` Same as HttpServerResponse.end but writes a String in UTF-8 encoding before ending the response.
    `void` | `end(java.lang.String chunk, java.lang.String enc)` Same as HttpServerResponse.end but writes a String with the specified encoding before ending the response.
    `void` | `end(Buffer chunk)` Same as HttpServerResponse.end but writes some data to the response body before ending.
    `void` | `end()` Ends the response.
    `boolean` | `ended()` Returns: has the response already ended?
    `HttpServerResponse` | `exceptionHandler(io.vertx.core.Handler<java.lang.Throwable> handler)`
    `java.lang.Object` | `getDelegate()`
    `int` | `getStatusCode()` Returns: the HTTP status code of the response.
    `java.lang.String` | `getStatusMessage()` Returns: the HTTP status message of the response.
    `boolean` | `headWritten()` Returns: have the headers for the response already been written?
    `MultiMap` | `headers()` @return Returns: The HTTP headers
    `HttpServerResponse` | `headersEndHandler(io.vertx.core.Handler<java.lang.Void> handler)` Provide a handler that will be called just before the headers are written to the wire.
    `boolean` | `isChunked()` Returns: is the response chunked?
    `HttpServerResponse` | `push(io.vertx.core.http.HttpMethod method, java.lang.String host, java.lang.String path, io.vertx.core.Handler<io.vertx.core.AsyncResult<HttpServerResponse>> handler)` Like HttpServerResponse.push with no headers.
    `HttpServerResponse` | `push(io.vertx.core.http.HttpMethod method, java.lang.String path, MultiMap headers, io.vertx.core.Handler<io.vertx.core.AsyncResult<HttpServerResponse>> handler)` Like HttpServerResponse.push with the host copied from the current request.
    `HttpServerResponse` | `push(io.vertx.core.http.HttpMethod method, java.lang.String path, io.vertx.core.Handler<io.vertx.core.AsyncResult<HttpServerResponse>> handler)` Like HttpServerResponse.push with the host copied from the current request.
    `HttpServerResponse` | `push(io.vertx.core.http.HttpMethod method, java.lang.String host, java.lang.String path, MultiMap headers, io.vertx.core.Handler<io.vertx.core.AsyncResult<HttpServerResponse>> handler)` Push a response to the client.
    `HttpServerResponse` | `putHeader(java.lang.String name, java.lang.String value)` Put an HTTP header
    `HttpServerResponse` | `putTrailer(java.lang.String name, java.lang.String value)` Put an HTTP trailer
    `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`.
    `HttpServerResponse` | `sendFile(java.lang.String filename)` Same as HttpServerResponse.sendFile using offset @code{0} which means starting from the beginning of the file.
    `HttpServerResponse` | `sendFile(java.lang.String filename, long offset)` Same as HttpServerResponse.sendFile using length @code{Long.MAX_VALUE} which means until the end of the file.
    `HttpServerResponse` | `sendFile(java.lang.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(java.lang.String filename, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.lang.Void>> resultHandler)` Like HttpServerResponse.sendFile but providing a handler which will be notified once the file has been completely written to the wire.
    `HttpServerResponse` | `sendFile(java.lang.String filename, long offset, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.lang.Void>> resultHandler)` Like HttpServerResponse.sendFile but providing a handler which will be notified once the file has been completely written to the wire.
    `HttpServerResponse` | `sendFile(java.lang.String filename, long offset, long length, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.lang.Void>> resultHandler)` Like HttpServerResponse.sendFile 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(java.lang.String statusMessage)` Set the status message
    `HttpServerResponse` | `setWriteQueueMaxSize(int maxSize)`
    `int` | `streamId()` @return Returns: the id of the stream of this response, for HTTP/1.x
    `MultiMap` | `trailers()` @return Returns: The HTTP trailers
    `HttpServerResponse` | `write(Buffer data)`
    `HttpServerResponse` | `write(java.lang.String chunk, java.lang.String enc)` Write a java.lang.String to the response body, encoded using the encoding `enc`.
    `HttpServerResponse` | `write(java.lang.String chunk)` Write a java.lang.String to the response body, encoded in UTF-8.
    `HttpServerResponse` | `writeContinue()` Used to write an interim 100 Continue response to signify that the client should send the rest of the request.
    `HttpServerResponse` | `writeCustomFrame(int type, int flags, Buffer payload)` Write an HTTP/2 frame to the response, allowing to extend the HTTP/2 protocol.
    `HttpServerResponse` | `writeCustomFrame(HttpFrame frame)` Like HttpServerResponse.writeCustomFrame but with an HttpFrame.
    `boolean` | `writeQueueFull()` This will return `true` if there are more bytes in the write queue than the value set using HttpServerResponse.setWriteQueueMaxSize

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class java.lang.Object` | `java.lang.Object#wait(long, int), java.lang.Object#wait(long), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll()`

- - ### Constructor Detail

    - #### HttpServerResponse(java.lang.Object delegate)

  - ### Method Detail

    - #### HttpServerResponse bodyEndHandler(io.vertx.core.Handler<java.lang.Void> 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.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `handler` - the handler

    - #### long bytesWritten()

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

    - #### void close()

      Close the underlying TCP connection corresponding to the request.

    - #### HttpServerResponse closeHandler(io.vertx.core.Handler<java.lang.Void> handler)

      Set a close handler for the response. This will be called if the underlying connection closes before the response is complete.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `handler` - the handler

    - #### boolean closed()

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

    - #### HttpServerResponse drainHandler(io.vertx.core.Handler<java.lang.Void> handler)

    - #### void end(java.lang.String chunk)

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

      Parameters:
        `chunk` - the string to write before ending the response

    - #### void end(java.lang.String chunk, java.lang.String enc)

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

    - #### void end(Buffer chunk)

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

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

    - #### boolean ended()

      Returns:
        has the response already ended?

    - #### HttpServerResponse exceptionHandler(io.vertx.core.Handler<java.lang.Throwable> handler)

    - #### java.lang.Object getDelegate()

    - #### int getStatusCode()

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

    - #### java.lang.String getStatusMessage()

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

    - #### boolean headWritten()

      Returns:
        have the headers for the response already been written?

    - #### MultiMap headers()

      Returns:
        The HTTP headers

    - #### HttpServerResponse headersEndHandler(io.vertx.core.Handler<java.lang.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.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `handler` - the handler

    - #### boolean isChunked()

      Returns:
        is the response chunked?

    - #### HttpServerResponse push(io.vertx.core.http.HttpMethod method, java.lang.String host, java.lang.String path, io.vertx.core.Handler<io.vertx.core.AsyncResult<HttpServerResponse>> handler)

      Like HttpServerResponse.push with no headers.

      Returns:
      Parameters:
        method
        host
        path
        handler

    - #### HttpServerResponse push(io.vertx.core.http.HttpMethod method, java.lang.String path, MultiMap headers, io.vertx.core.Handler<io.vertx.core.AsyncResult<HttpServerResponse>> handler)

      Like HttpServerResponse.push with the host copied from the current request.

      Returns:
      Parameters:
        method
        path
        headers
        handler

    - #### HttpServerResponse push(io.vertx.core.http.HttpMethod method, java.lang.String path, io.vertx.core.Handler<io.vertx.core.AsyncResult<HttpServerResponse>> handler)

      Like HttpServerResponse.push with the host copied from the current request.

      Returns:
      Parameters:
        method
        path
        handler

    - #### HttpServerResponse push(io.vertx.core.http.HttpMethod method, java.lang.String host, java.lang.String path, MultiMap headers, io.vertx.core.Handler<io.vertx.core.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.
      Returns:
        a reference to this, so the API can be used fluently
      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

    - #### HttpServerResponse putHeader(java.lang.String name, java.lang.String value)

      Put an HTTP header

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `name` - the header name
        `value` - the header value.

    - #### HttpServerResponse putTrailer(java.lang.String name, java.lang.String value)

      Put an HTTP trailer

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `name` - the trailer name
        `value` - the trailer value

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

      Parameters:
        `code` - the error code

    - #### HttpServerResponse sendFile(java.lang.String filename)

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

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `filename` - path to the file to serve

    - #### HttpServerResponse sendFile(java.lang.String filename, long offset)

      Same as HttpServerResponse.sendFile using length @code{Long.MAX_VALUE} which means until the end of the file.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `filename` - path to the file to serve
        `offset` - offset to start serving from

    - #### HttpServerResponse sendFile(java.lang.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.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `filename` - path to the file to serve
        `offset` - offset to start serving from
        `length` - length to serve to

    - #### HttpServerResponse sendFile(java.lang.String filename, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.lang.Void>> resultHandler)

      Like HttpServerResponse.sendFile but providing a handler which will be notified once the file has been completely written to the wire.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `filename` - path to the file to serve
        `resultHandler` - handler that will be called on completion

    - #### HttpServerResponse sendFile(java.lang.String filename, long offset, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.lang.Void>> resultHandler)

      Like HttpServerResponse.sendFile but providing a handler which will be notified once the file has been completely written to the wire.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `filename` - path to the file to serve
        `offset` - the offset to serve from
        `resultHandler` - handler that will be called on completion

    - #### HttpServerResponse sendFile(java.lang.String filename, long offset, long length, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.lang.Void>> resultHandler)

      Like HttpServerResponse.sendFile but providing a handler which will be notified once the file has been completely written to the wire.

      Returns:
        a reference to this, so the API can be used fluently
      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

    - #### 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
      Parameters:
        chunked

    - #### 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
      Parameters:
        statusCode

    - #### HttpServerResponse setStatusMessage(java.lang.String statusMessage)

      Set the status message

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        statusMessage

    - #### HttpServerResponse setWriteQueueMaxSize(int maxSize)

    - #### int streamId()

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

    - #### MultiMap trailers()

      Returns:
        The HTTP trailers

    - #### HttpServerResponse write(Buffer data)

    - #### HttpServerResponse write(java.lang.String chunk, java.lang.String enc)

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

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `chunk` - the string to write
        `enc` - the encoding to use

    - #### HttpServerResponse write(java.lang.String chunk)

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

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `chunk` - the string to write

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

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

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `type` - the 8-bit frame type
        `flags` - the 8-bit frame flags
        `payload` - the frame payload

    - #### HttpServerResponse writeCustomFrame(HttpFrame frame)

      Like HttpServerResponse.writeCustomFrame but with an HttpFrame.

      Returns:
      Parameters:
        `frame` - the frame to write

    - #### boolean writeQueueFull()

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

      Returns:
        true if write queue is full