io.vertx.core.http

## Interface HttpClientRequest

- All Superinterfaces:
    ReadStream<HttpClientResponse>, StreamBase, WriteStream<Buffer>

      public interface HttpClientRequest
      extends WriteStream<Buffer>, ReadStream<HttpClientResponse>

  Represents a client-side HTTP request.

  Instances are created by an `HttpClient` instance, via one of the methods corresponding to the specific HTTP methods, or the generic request methods. On creation the request will not have been written to the wire.

  Once a request has been obtained, headers can be set on it, and data can be written to its body if required. Once you are ready to send the request, one of the `end()` methods should be called.

  Nothing is actually sent until the request has been internally assigned an HTTP connection.

  The `HttpClient` instance will return an instance of this class immediately, even if there are no HTTP connections available in the pool. Any requests sent before a connection is assigned will be queued internally and actually sent when an HTTP connection becomes available from the pool.

  The headers of the request are queued for writing either when the `end()` method is called, or, when the first part of the body is written, whichever occurs first.

  This class supports both chunked and non-chunked HTTP.

  It implements `WriteStream` so it can be used with `Pump` to pump data with flow control.

  An example of using this class is as follows:

  Author:
    Tim Fox

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `absoluteURI()`
    `HttpConnection` | `connection()`
    `HttpClientRequest` | `connectionHandler(Handler<HttpConnection> handler)` Deprecated. instead use `HttpClient.connectionHandler(Handler)`
    `HttpClientRequest` | `continueHandler(Handler<Void> handler)` If you send an HTTP request with the header `Expect` set to the value `100-continue` and the server responds with an interim HTTP response with a status code of `100` and a continue handler has been set using this method, then the `handler` will be called.
    `HttpClientRequest` | `drainHandler(Handler<Void> handler)` Set a drain handler on the stream.
    `void` | `end()` Ends the request.
    `void` | `end(Buffer chunk)` Same as `end()` but writes some data to the request body before ending.
    `void` | `end(Buffer chunk, Handler<AsyncResult<Void>> handler)` Same as `end(String)` but with an `handler` called when the operation completes
    `void` | `end(Handler<AsyncResult<Void>> handler)` Same as `end()` but with an `handler` called when the operation completes
    `void` | `end(String chunk)` Same as `end(Buffer)` but writes a String in UTF-8 encoding
    `void` | `end(String chunk, Handler<AsyncResult<Void>> handler)` Same as `end(String)` but with an `handler` called when the operation completes
    `void` | `end(String chunk, String enc)` Same as `end(Buffer)` but writes a String with the specified encoding
    `void` | `end(String chunk, String enc, Handler<AsyncResult<Void>> handler)` Same as `end(String,String)` but with an `handler` called when the operation completes
    `HttpClientRequest` | `endHandler(Handler<Void> endHandler)` Deprecated. this method will be removed in Vert.x 4
    `HttpClientRequest` | `exceptionHandler(Handler<Throwable> handler)` Set an exception handler on the write stream.
    `HttpClientRequest` | `fetch(long amount)` Deprecated. this method will be removed in Vert.x 4
    `String` | `getHost()`
    `String` | `getRawMethod()`
    `StreamPriority` | `getStreamPriority()`
    `HttpClientRequest` | `handler(Handler<HttpClientResponse> handler)` Deprecated. this method will break in Vert.x 4, the handler will use an `Handler<AsyncResult<HttpClientResponse>>`
    `MultiMap` | `headers()`
    `boolean` | `isChunked()`
    `HttpMethod` | `method()` The HTTP method for the request.
    `String` | `path()`
    `HttpClientRequest` | `pause()` Deprecated. this method will be removed in Vert.x 4
    `HttpClientRequest` | `pushHandler(Handler<HttpClientRequest> handler)` Set a push handler for this request. The handler is called when the client receives a push promise from the server.
    `HttpClientRequest` | `putHeader(CharSequence name, CharSequence value)` Like `putHeader(String, String)` but using CharSequence
    `HttpClientRequest` | `putHeader(CharSequence name, Iterable<CharSequence> values)` Like `putHeader(String, Iterable)` but using CharSequence
    `HttpClientRequest` | `putHeader(String name, Iterable<String> values)` Put an HTTP header with multiple values
    `HttpClientRequest` | `putHeader(String name, String value)` Put an HTTP header
    `String` | `query()`
    `default boolean` | `reset()` Reset this stream with the error code `0`.
    `boolean` | `reset(long code)` Reset this request: for HTTP/2, this performs send an HTTP/2 reset frame with the specified error `code` for HTTP/1.x, this closes the connection when the current request is inflight When the request has not yet been sent, the request will be aborted and false is returned as indicator.
    `HttpClientRequest` | `resume()` Deprecated. this method will be removed in Vert.x 4
    `HttpClientRequest` | `sendHead()` Forces the head of the request to be written before `end()` is called on the request or any data is written to it.
    `HttpClientRequest` | `sendHead(Handler<HttpVersion> completionHandler)` Like `sendHead()` but with an handler after headers have been sent.
    `HttpClientRequest` | `setChunked(boolean chunked)` If chunked is true then the request will be set into HTTP chunked mode
    `HttpClientRequest` | `setFollowRedirects(boolean followRedirects)` Set the request to follow HTTP redirects up to `HttpClientOptions.getMaxRedirects()`.
    `HttpClientRequest` | `setHost(String host)` Set the request host. For HTTP/2 it sets the :authority pseudo header otherwise it sets the Host header
    `HttpClientRequest` | `setMaxRedirects(int maxRedirects)` Set the max number of HTTP redirects this request will follow.
    `HttpClientRequest` | `setRawMethod(String method)` Set the value the method to send when the method `HttpMethod.OTHER` is used.
    `default HttpClientRequest` | `setStreamPriority(StreamPriority streamPriority)` Sets the priority of the associated stream.
    `HttpClientRequest` | `setTimeout(long timeoutMs)` Set's the amount of time after which if the request does not return any data within the timeout period an `TimeoutException` will be passed to the exception handler (if provided) and the request will be closed.
    `HttpClientRequest` | `setWriteQueueMaxSize(int maxSize)` Set the maximum size of the write queue to `maxSize`.
    `default int` | `streamId()`
    `String` | `uri()`
    `HttpClientRequest` | `write(Buffer data)` Write some data to the stream.
    `HttpClientRequest` | `write(Buffer data, Handler<AsyncResult<Void>> handler)` Same as `write(Buffer)` but with an `handler` called when the operation completes
    `HttpClientRequest` | `write(String chunk)` Write a `String` to the request body, encoded as UTF-8.
    `HttpClientRequest` | `write(String chunk, Handler<AsyncResult<Void>> handler)` Same as `write(String)` but with an `handler` called when the operation completes
    `HttpClientRequest` | `write(String chunk, String enc)` Write a `String` to the request body, encoded using the encoding `enc`.
    `HttpClientRequest` | `write(String chunk, String enc, Handler<AsyncResult<Void>> handler)` Same as `write(String,String)` but with an `handler` called when the operation completes
    `default HttpClientRequest` | `writeCustomFrame(HttpFrame frame)` Like `writeCustomFrame(int, int, Buffer)` but with an `HttpFrame`.
    `HttpClientRequest` | `writeCustomFrame(int type, int flags, Buffer payload)` Write an HTTP/2 frame to the request, allowing to extend the HTTP/2 protocol.

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

      `writeQueueFull`

    - ### Methods inherited from interface io.vertx.core.streams.ReadStream

      `pipe, pipeTo, pipeTo`

- - ### Method Detail

    - #### exceptionHandler

          HttpClientRequest exceptionHandler(Handler<Throwable> handler)

      Description copied from interface: `WriteStream`
      Set an exception handler on the write stream.
      Specified by:
        `exceptionHandler` in interface `ReadStream<HttpClientResponse>`
      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

    - #### write

          HttpClientRequest write(Buffer data)

      Description copied from interface: `WriteStream`
      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 `WriteStream.writeQueueFull()` method before writing. This is done automatically if using a `Pump`.
      Specified by:
        `write` in interface `WriteStream<Buffer>`
      Parameters:
        `data` - the data to write
      Returns:
        a reference to this, so the API can be used fluently
      Throws:
        `IllegalStateException` - when no response handler is set

    - #### write

          HttpClientRequest write(Buffer data,
                                  Handler<AsyncResult<Void>> handler)

      Same as `write(Buffer)` but with an `handler` called when the operation completes
      Specified by:
        `write` in interface `WriteStream<Buffer>`

    - #### setWriteQueueMaxSize

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

          HttpClientRequest 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 `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`.
      Specified by:
        `drainHandler` in interface `WriteStream<Buffer>`
      Parameters:
        `handler` - the handler
      Returns:
        a reference to this, so the API can be used fluently

    - #### handler

          @Deprecated
          HttpClientRequest handler(Handler<HttpClientResponse> handler)

      Deprecated. this method will break in Vert.x 4, the handler will use an `Handler<AsyncResult<HttpClientResponse>>`
      Description copied from interface: `ReadStream`
      Set a data handler. As data is read, the handler will be called with the data.
      Specified by:
        `handler` in interface `ReadStream<HttpClientResponse>`
      Returns:
        a reference to this, so the API can be used fluently

    - #### pause

          @Deprecated
          HttpClientRequest pause()

      Deprecated. this method will be removed in Vert.x 4
      Description copied from interface: `ReadStream`
      Pause the `ReadStream`, it sets the buffer in `fetch` mode and clears the actual demand.

      While it's paused, no data will be sent to the data `handler`.

      Specified by:
        `pause` in interface `ReadStream<HttpClientResponse>`
      Returns:
        a reference to this, so the API can be used fluently

    - #### resume

          @Deprecated
          HttpClientRequest resume()

      Deprecated. this method will be removed in Vert.x 4
      Description copied from interface: `ReadStream`
      Resume reading, and sets the buffer in `flowing` mode.

      If the `ReadStream` has been paused, reading will recommence on it.
      Specified by:
        `resume` in interface `ReadStream<HttpClientResponse>`
      Returns:
        a reference to this, so the API can be used fluently

    - #### fetch

          @Deprecated
          HttpClientRequest fetch(long amount)

      Deprecated. this method will be removed in Vert.x 4
      Description copied from interface: `ReadStream`
      Fetch the specified `amount` of elements. If the `ReadStream` has been paused, reading will recommence with the specified `amount` of items, otherwise the specified `amount` will be added to the current stream demand.
      Specified by:
        `fetch` in interface `ReadStream<HttpClientResponse>`
      Returns:
        a reference to this, so the API can be used fluently

    - #### endHandler

          @Deprecated
          HttpClientRequest endHandler(Handler<Void> endHandler)

      Deprecated. this method will be removed in Vert.x 4
      Description copied from interface: `ReadStream`
      Set an end handler. Once the stream has ended, and there is no more data to be read, this handler will be called.
      Specified by:
        `endHandler` in interface `ReadStream<HttpClientResponse>`
      Returns:
        a reference to this, so the API can be used fluently

    - #### setFollowRedirects

          HttpClientRequest setFollowRedirects(boolean followRedirects)

      Set the request to follow HTTP redirects up to `HttpClientOptions.getMaxRedirects()`.
      Parameters:
        `followRedirects` - `true` to follow HTTP redirects
      Returns:
        a reference to this, so the API can be used fluently

    - #### setMaxRedirects

          HttpClientRequest setMaxRedirects(int maxRedirects)

      Set the max number of HTTP redirects this request will follow. The default is `0` which means no redirects.
      Parameters:
        `maxRedirects` - the number of HTTP redirect to follow
      Returns:
        a reference to this, so the API can be used fluently

    - #### setChunked

          HttpClientRequest setChunked(boolean chunked)

      If chunked is true then the request will be set into HTTP chunked mode
      Parameters:
        `chunked` - true if chunked encoding
      Returns:
        a reference to this, so the API can be used fluently

    - #### isChunked

          boolean isChunked()

      Returns:
        Is the request chunked?

    - #### method

          HttpMethod method()

      The HTTP method for the request.

    - #### getRawMethod

          String getRawMethod()

      Returns:
        the raw value of the method this request sends

    - #### setRawMethod

          HttpClientRequest setRawMethod(String method)

      Set the value the method to send when the method `HttpMethod.OTHER` is used.
      Parameters:
        `method` - the raw method
      Returns:
        a reference to this, so the API can be used fluently

    - #### absoluteURI

          String absoluteURI()

      Returns:
        the absolute URI corresponding to the the HTTP request

    - #### uri

          String uri()

      Returns:
        The URI of the request.

    - #### path

          String path()

      Returns:
        The path part of the uri. For example /somepath/somemorepath/someresource.foo

    - #### query

          String query()

      Returns:
        the query part of the uri. For example someparam=32&someotherparam=x

    - #### setHost

          HttpClientRequest setHost(String host)

      Set the request host.

      For HTTP/2 it sets the :authority pseudo header otherwise it sets the Host header

    - #### getHost

          String getHost()

      Returns:
        the request host. For HTTP/2 it returns the :authority pseudo header otherwise it returns the Host header

    - #### headers

          MultiMap headers()

      Returns:
        The HTTP headers

    - #### putHeader

          HttpClientRequest 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

          HttpClientRequest putHeader(CharSequence name,
                                      CharSequence value)

      Like `putHeader(String, String)` but using CharSequence

    - #### putHeader

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

      Put an HTTP header with multiple values
      Parameters:
        `name` - The header name
        `values` - The header values
      Returns:
        @return a reference to this, so the API can be used fluently

    - #### putHeader

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

      Like `putHeader(String, Iterable)` but using CharSequence

    - #### write

          HttpClientRequest write(String chunk)

      Write a `String` to the request body, encoded as UTF-8.
      Returns:
        @return a reference to this, so the API can be used fluently
      Throws:
        `IllegalStateException` - when no response handler is set

    - #### write

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

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

    - #### write

          HttpClientRequest write(String chunk,
                                  String enc)

      Write a `String` to the request body, encoded using the encoding `enc`.
      Returns:
        @return a reference to this, so the API can be used fluently
      Throws:
        `IllegalStateException` - when no response handler is set

    - #### write

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

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

    - #### continueHandler

          HttpClientRequest continueHandler(Handler<Void> handler)

      If you send an HTTP request with the header `Expect` set to the value `100-continue` and the server responds with an interim HTTP response with a status code of `100` and a continue handler has been set using this method, then the `handler` will be called.

      You can then continue to write data to the request body and later end it. This is normally used in conjunction with the `sendHead()` method to force the request header to be written before the request has ended.

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

    - #### sendHead

          HttpClientRequest sendHead()

      Forces the head of the request to be written before `end()` is called on the request or any data is written to it.

      This is normally used to implement HTTP 100-continue handling, see `continueHandler(io.vertx.core.Handler)` for more information.

      Returns:
        a reference to this, so the API can be used fluently
      Throws:
        `IllegalStateException` - when no response handler is set

    - #### sendHead

          HttpClientRequest sendHead(Handler<HttpVersion> completionHandler)

      Like `sendHead()` but with an handler after headers have been sent. The handler will be called with the `HttpVersion` if it can be determined or null otherwise.

    - #### end

          void end(String chunk)

      Same as `end(Buffer)` but writes a String in UTF-8 encoding
      Throws:
        `IllegalStateException` - when no response handler is set

    - #### end

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

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

    - #### end

          void end(String chunk,
                   String enc)

      Same as `end(Buffer)` but writes a String with the specified encoding
      Throws:
        `IllegalStateException` - when no response handler is set

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

          void end(Buffer chunk)

      Same as `end()` but writes some data to the request body before ending. If the request is not chunked and no other data has been written then the `Content-Length` header will be automatically set
      Specified by:
        `end` in interface `WriteStream<Buffer>`
      Parameters:
        `chunk` - the data to write
      Throws:
        `IllegalStateException` - when no response handler is set

    - #### end

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

      Same as `end(String)` but with an `handler` called when the operation completes
      Specified by:
        `end` in interface `WriteStream<Buffer>`

    - #### end

          void end()

      Ends the request. If no data has been written to the request body, and `sendHead()` has not been called then the actual request won't get written until this method gets called.

      Once the request has ended, it cannot be used any more,

      Specified by:
        `end` in interface `WriteStream<Buffer>`
      Throws:
        `IllegalStateException` - when no response handler is set

    - #### end

          void end(Handler<AsyncResult<Void>> handler)

      Same as `end()` but with an `handler` called when the operation completes
      Specified by:
        `end` in interface `WriteStream<Buffer>`

    - #### setTimeout

          HttpClientRequest setTimeout(long timeoutMs)

      Set's the amount of time after which if the request does not return any data within the timeout period an `TimeoutException` will be passed to the exception handler (if provided) and the request will be closed.

      Calling this method more than once has the effect of canceling any existing timeout and starting the timeout from scratch.

      Parameters:
        `timeoutMs` - The quantity of time in milliseconds.
      Returns:
        a reference to this, so the API can be used fluently

    - #### pushHandler

          HttpClientRequest pushHandler(Handler<HttpClientRequest> handler)

      Set a push handler for this request.

      The handler is called when the client receives a push promise from the server. The handler can be called multiple times, for each push promise.

      The handler is called with a read-only `HttpClientRequest`, the following methods can be called:

      - `method()`
      - `uri()`
      - `headers()`
      - `getHost()`
      In addition the handler should call the `handler(io.vertx.core.Handler<io.vertx.core.http.HttpClientResponse>)` method to set an handler to process the response.

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

    - #### reset

          default boolean reset()

      Reset this stream with the error code `0`.
      See Also:
        `reset(long)`

    - #### reset

          boolean reset(long code)

      Reset this request:

      - for HTTP/2, this performs send an HTTP/2 reset frame with the specified error `code`
      - for HTTP/1.x, this closes the connection when the current request is inflight

      When the request has not yet been sent, the request will be aborted and false is returned as indicator.

      Parameters:
        `code` - the error code
      Returns:
        true when reset has been performed

    - #### connection

          HttpConnection connection()

      Returns:
        the `HttpConnection` associated with this request

    - #### connectionHandler

          @Deprecated
          HttpClientRequest connectionHandler(Handler<HttpConnection> handler)

      Deprecated. instead use `HttpClient.connectionHandler(Handler)`
      Set a connection handler called when an HTTP connection has been established.
      Parameters:
        `handler` - the handler
      Returns:
        a reference to this, so the API can be used fluently

    - #### writeCustomFrame

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

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

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

      This method must be called after the request headers have been sent and only for the protocol HTTP/2. The `sendHead(Handler)` should be used for this purpose.

      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

    - #### streamId

          default int streamId()

      Returns:
        the id of the stream of this response, -1 when it is not yet determined, i.e the request has not been yet sent or it is not supported HTTP/1.x

    - #### writeCustomFrame

          default HttpClientRequest writeCustomFrame(HttpFrame frame)

      Like `writeCustomFrame(int, int, Buffer)` but with an `HttpFrame`.
      Parameters:
        `frame` - the frame to write

    - #### setStreamPriority

          default HttpClientRequest setStreamPriority(StreamPriority streamPriority)

      Sets the priority of the associated stream.

      This is not implemented for HTTP/1.x.
      Parameters:
        `streamPriority` - the priority of this request's stream

    - #### getStreamPriority

          StreamPriority getStreamPriority()

      Returns:
        the priority of the associated HTTP/2 stream for HTTP/2 otherwise `null`

Copyright © 2022 Eclipse. All rights reserved.