Package io.vertx.rxjava3.core.http

Class HttpServerResponse

  • All Implemented Interfaces:
    StreamBase, WriteStream<Buffer>
    public class HttpServerResponse
extends Object
implements 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.

    NOTE: This class has been automatically generated from the original non RX-ified interface using Vert.x codegen.

    • Constructor Detail

      • HttpServerResponse

        public HttpServerResponse​(Object delegate)

    • Method Detail

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • write

        public io.reactivex.rxjava3.core.Completable write​(Buffer data)
        Same as but with an handler called when the operation completes
        Specified by:
        write in interface WriteStream<Buffer>
        Parameters:
        data -
        Returns:

      • rxWrite

        public io.reactivex.rxjava3.core.Completable rxWrite​(Buffer data)
        Same as but with an handler called when the operation completes
        Specified by:
        rxWrite in interface WriteStream<Buffer>
        Parameters:
        data -
        Returns:

      • end

        public io.reactivex.rxjava3.core.Completable end()
        Same as end() but with an handler called when the operation completes
        Specified by:
        end in interface WriteStream<Buffer>
        Returns:

      • rxEnd

        public io.reactivex.rxjava3.core.Completable rxEnd()
        Same as end() but with an handler called when the operation completes
        Specified by:
        rxEnd in interface WriteStream<Buffer>
        Returns:

      • setWriteQueueMaxSize

        public 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

        public 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

        public int getStatusCode()
        Returns:
        the HTTP status code of the response. The default is 200 representing OK.

      • setStatusCode

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

      • getStatusMessage

        public 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

        public HttpServerResponse setStatusMessage​(String statusMessage)
        Set the status message
        Parameters:
        statusMessage -
        Returns:
        a reference to this, so the API can be used fluently

      • setChunked

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

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

      • isChunked

        public boolean isChunked()
        Returns:
        is the response chunked?

      • headers

        public MultiMap headers()
        Returns:
        The HTTP headers

      • putHeader

        public 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

      • trailers

        public MultiMap trailers()
        Returns:
        The HTTP trailers

      • putTrailer

        public 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

      • closeHandler

        public 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

        public 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

      • writeContinue

        public 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

        public io.reactivex.rxjava3.core.Completable end​(String chunk)
        Same as end() but with an handler called when the operation completes
        Parameters:
        chunk -
        Returns:

      • rxEnd

        public io.reactivex.rxjava3.core.Completable rxEnd​(String chunk)
        Same as end() but with an handler called when the operation completes
        Parameters:
        chunk -
        Returns:

      • end

        public io.reactivex.rxjava3.core.Completable end​(String chunk,
                                                 String enc)
        Same as end() but with an handler called when the operation completes
        Parameters:
        chunk -
        enc -
        Returns:

      • rxEnd

        public io.reactivex.rxjava3.core.Completable rxEnd​(String chunk,
                                                   String enc)
        Same as end() but with an handler called when the operation completes
        Parameters:
        chunk -
        enc -
        Returns:

      • end

        public io.reactivex.rxjava3.core.Completable end​(Buffer chunk)
        Same as end() but with an handler called when the operation completes
        Specified by:
        end in interface WriteStream<Buffer>
        Parameters:
        chunk -
        Returns:

      • rxEnd

        public io.reactivex.rxjava3.core.Completable rxEnd​(Buffer chunk)
        Same as end() but with an handler called when the operation completes
        Specified by:
        rxEnd in interface WriteStream<Buffer>
        Parameters:
        chunk -
        Returns:

      • send

        public io.reactivex.rxjava3.core.Completable send()
        Send the request with an empty body.
        Returns:

      • rxSend

        public io.reactivex.rxjava3.core.Completable rxSend()
        Send the request with an empty body.
        Returns:

      • send

        public io.reactivex.rxjava3.core.Completable send​(String body)
        Send the request with a string body.
        Parameters:
        body -
        Returns:

      • rxSend

        public io.reactivex.rxjava3.core.Completable rxSend​(String body)
        Send the request with a string body.
        Parameters:
        body -
        Returns:

      • send

        public io.reactivex.rxjava3.core.Completable send​(Buffer body)
        Send the request with a buffer body.
        Parameters:
        body -
        Returns:

      • rxSend

        public io.reactivex.rxjava3.core.Completable rxSend​(Buffer body)
        Send the request with a buffer body.
        Parameters:
        body -
        Returns:

      • send

        public io.reactivex.rxjava3.core.Completable send​(io.reactivex.rxjava3.core.Flowable<Buffer> body)
        Send the request with a stream body.

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

        Parameters:
        body -
        Returns:

      • rxSend

        public io.reactivex.rxjava3.core.Completable rxSend​(io.reactivex.rxjava3.core.Flowable<Buffer> body)
        Send the request with a stream body.

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

        Parameters:
        body -
        Returns:

      • sendFile

        public io.reactivex.rxjava3.core.Completable sendFile​(String filename)
        Like sendFile(java.lang.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
        Returns:
        a reference to this, so the API can be used fluently

      • rxSendFile

        public io.reactivex.rxjava3.core.Completable rxSendFile​(String filename)
        Like sendFile(java.lang.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
        Returns:
        a reference to this, so the API can be used fluently

      • sendFile

        public io.reactivex.rxjava3.core.Completable sendFile​(String filename,
                                                      long offset)
        Like sendFile(java.lang.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
        offset - the offset to serve from
        Returns:
        a reference to this, so the API can be used fluently

      • rxSendFile

        public io.reactivex.rxjava3.core.Completable rxSendFile​(String filename,
                                                        long offset)
        Like sendFile(java.lang.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
        offset - the offset to serve from
        Returns:
        a reference to this, so the API can be used fluently

      • sendFile

        public io.reactivex.rxjava3.core.Completable sendFile​(String filename,
                                                      long offset,
                                                      long length)
        Like sendFile(java.lang.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
        offset - the offset to serve from
        length - length the number of bytes to send
        Returns:
        a reference to this, so the API can be used fluently

      • rxSendFile

        public io.reactivex.rxjava3.core.Completable rxSendFile​(String filename,
                                                        long offset,
                                                        long length)
        Like sendFile(java.lang.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
        offset - the offset to serve from
        length - length the number of bytes to send
        Returns:
        a reference to this, so the API can be used fluently

      • close

        @Deprecated
public void close()
        Deprecated.
        Close the underlying TCP connection corresponding to the request.

      • ended

        public boolean ended()
        Returns:
        has the response already ended?

      • closed

        public boolean closed()
        Returns:
        has the underlying TCP connection corresponding to the request already been closed?

      • headWritten

        public boolean headWritten()
        Returns:
        have the headers for the response already been written?

      • headersEndHandler

        public 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

        public 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

        public long bytesWritten()
        Returns:
        the total number of bytes written for the body of the response.

      • streamId

        public int streamId()
        Returns:
        the id of the stream of this response, for HTTP/1.x

      • push

        public io.reactivex.rxjava3.core.Single<HttpServerResponse> push​(HttpMethod method,
                                                                 String host,
                                                                 String path,
                                                                 MultiMap headers)
        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 -
        path - the path of the promised request
        headers - the headers of the promised request
        Returns:
        a reference to this, so the API can be used fluently

      • rxPush

        public io.reactivex.rxjava3.core.Single<HttpServerResponse> rxPush​(HttpMethod method,
                                                                   String host,
                                                                   String path,
                                                                   MultiMap headers)
        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 -
        path - the path of the promised request
        headers - the headers of the promised request
        Returns:
        a reference to this, so the API can be used fluently

      • reset

        public boolean reset()
        Reset this HTTP/2 stream with the error code 0.
        Returns:

      • reset

        public 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

        public 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

      • setStreamPriority

        public 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
        Returns:

      • addCookie

        public 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

        public Cookie removeCookie​(String name)
        Expire a cookie, notifying a User Agent to remove it from its cookie jar. NOTE: This method will only remove the first occurrence of the given name. Users probably may want to use: removeCookies(java.lang.String)
        Parameters:
        name - the name of the cookie
        Returns:
        the cookie, if it existed, or null

      • removeCookie

        public 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. NOTE: This method will only expire the first occurrence of the given name. Users probably may want to use: removeCookies(java.lang.String)
        Parameters:
        name - the name of the cookie
        invalidate -
        Returns:
        the cookie, if it existed, or null

      • removeCookies

        public Set<Cookie> removeCookies​(String name)
        Expire all cookies, notifying a User Agent to remove it from its cookie jar. NOTE: the returned is read-only. This means any attempt to modify (add or remove to the set), will throw UnsupportedOperationException.
        Parameters:
        name - the name of the cookie
        Returns:
        a read only set of affected cookies, if they existed, or an empty set.

      • removeCookies

        public Set<Cookie> removeCookies​(String name,
                                 boolean invalidate)
        Remove all cookies 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. NOTE: the returned is read-only. This means any attempt to modify (add or remove to the set), will throw UnsupportedOperationException.
        Parameters:
        name - the name of the cookie
        invalidate - invalidate from the user agent
        Returns:
        a read only set of affected cookies, if they existed, or an empty set.

      • removeCookie

        public Cookie removeCookie​(String name,
                           String domain,
                           String path)
        Expires a cookie from the cookie set. This will notify a User Agent to remove it from its cookie jar.
        Parameters:
        name - the name of the cookie
        domain - the domain of the cookie
        path - the path of the cookie
        Returns:
        the cookie, if it existed, or null

      • removeCookie

        public Cookie removeCookie​(String name,
                           String domain,
                           String path,
                           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
        domain - the domain of the cookie
        path - the path of the cookie
        invalidate -
        Returns:
        the cookie, if it existed, or null