Class HttpClientRequest

java.lang.Object
io.vertx.reactivex.core.http.HttpClientRequest
All Implemented Interfaces:
io.vertx.lang.rx.RxDelegate, StreamBase, WriteStream<Buffer>
public class HttpClientRequest extends Object implements io.vertx.lang.rx.RxDelegate, WriteStream<Buffer>
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(String) 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(String) 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 Pipe to pipe data with flow control.

An example of using this class is as follows:

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

  • Field Details

    • __TYPE_ARG

      public static final io.vertx.lang.rx.TypeArg<HttpClientRequest> __TYPE_ARG

  • Constructor Details

    • HttpClientRequest

      public HttpClientRequest(HttpClientRequest delegate)

    • HttpClientRequest

      public HttpClientRequest(Object delegate)

  • Method Details

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getDelegate

      public HttpClientRequest getDelegate()
      Specified by:
      getDelegate in interface io.vertx.lang.rx.RxDelegate
      Specified by:
      getDelegate in interface StreamBase
      Specified by:
      getDelegate in interface WriteStream<Buffer>

    • toObserver

      public WriteStreamObserver<Buffer> toObserver()
      Specified by:
      toObserver in interface WriteStream<Buffer>

    • toSubscriber

      public WriteStreamSubscriber<Buffer> toSubscriber()
      Specified by:
      toSubscriber in interface WriteStream<Buffer>

    • write

      public Future<Void> write(Buffer data)
      Write some data to the stream.

      The data is usually 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 .

      When the data is moved from the queue to the actual medium, the returned will be completed with the write result, e.g the future is succeeded when a server HTTP response buffer is written to the socket and failed if the remote client has closed the socket while the data was still pending for write.

      Specified by:
      write in interface WriteStream<Buffer>
      Parameters:
      data - the data to write
      Returns:
      a future completed with the write result

    • rxWrite

      public Completable rxWrite(Buffer data)
      Write some data to the stream.

      The data is usually 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 .

      When the data is moved from the queue to the actual medium, the returned will be completed with the write result, e.g the future is succeeded when a server HTTP response buffer is written to the socket and failed if the remote client has closed the socket while the data was still pending for write.

      Specified by:
      rxWrite in interface WriteStream<Buffer>
      Parameters:
      data - the data to write
      Returns:
      a future completed with the write result

    • writeQueueFull

      public boolean writeQueueFull()
      This will return true if there are more bytes in the write queue than the value set using setWriteQueueMaxSize(int)
      Specified by:
      writeQueueFull in interface WriteStream<Buffer>
      Returns:
      true if write queue is full

    • exceptionHandler

      public HttpClientRequest exceptionHandler(Handler<Throwable> handler)
      Description copied from interface: WriteStream
      Set an exception handler on the write stream.
      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

    • setWriteQueueMaxSize

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

    • authority

      public HttpClientRequest authority(HostAndPort authority)
      Override the request authority, when using HTTP/1.x this overrides the request host header, when using HTTP/2 this sets the authority pseudo header. When the port is a negative value, the default scheme port will be used.

      The default request authority is the server host and port when connecting to the server.

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

    • setFollowRedirects

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

    • isFollowRedirects

      public boolean isFollowRedirects()
      Returns:
      whether HTTP redirections should be followed

    • setMaxRedirects

      public 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

    • getMaxRedirects

      public int getMaxRedirects()
      Returns:
      the maximum number of HTTP redirections to follow

    • numberOfRedirections

      public int numberOfRedirections()
      Returns:
      the number of followed redirections for the current HTTP request

    • setChunked

      public 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

      public boolean isChunked()
      Returns:
      Is the request chunked?

    • getMethod

      public HttpMethod getMethod()
      The HTTP method for the request.
      Returns:

    • setMethod

      public HttpClientRequest setMethod(HttpMethod method)
      Set the HTTP method for this request.
      Parameters:
      method - the HTTP method
      Returns:
      a reference to this, so the API can be used fluently

    • absoluteURI

      public String absoluteURI()
      Returns:
      the absolute URI corresponding to the HTTP request

    • getURI

      public String getURI()
      Returns:
      The URI of the request.

    • setURI

      public HttpClientRequest setURI(String uri)
      Set the request uri.
      Parameters:
      uri - the request uri
      Returns:
      a reference to this, so the API can be used fluently

    • path

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

    • query

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

    • headers

      public MultiMap headers()
      Returns:
      The HTTP headers

    • putHeader

      public 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

    • traceOperation

      public HttpClientRequest traceOperation(String op)
      Set the trace operation of this request.
      Parameters:
      op - the operation
      Returns:
      @return a reference to this, so the API can be used fluently

    • traceOperation

      public String traceOperation()
      Returns:
      the trace operation of this request

    • version

      public HttpVersion version()
      Returns:
      the HTTP version for this request

    • write

      public Future<Void> write(String chunk)
      Write a String to the request body, encoded as UTF-8.
      Parameters:
      chunk - the data chunk
      Returns:
      a future completed with the result

    • rxWrite

      public Completable rxWrite(String chunk)
      Write a String to the request body, encoded as UTF-8.
      Parameters:
      chunk - the data chunk
      Returns:
      a future completed with the result

    • write

      public Future<Void> write(String chunk, String enc)
      Write a String to the request body, encoded using the encoding enc.
      Parameters:
      chunk - the data chunk
      enc - the encoding
      Returns:
      a future completed with the result

    • rxWrite

      public Completable rxWrite(String chunk, String enc)
      Write a String to the request body, encoded using the encoding enc.
      Parameters:
      chunk - the data chunk
      enc - the encoding
      Returns:
      a future completed with the result

    • continueHandler

      public 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 writeHead() method to force the request header to be written before the request has ended.

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

    • earlyHintsHandler

      public HttpClientRequest earlyHintsHandler(Handler<MultiMap> handler)
      If the server responds with an interim HTTP response with a status code of 103 and a Early Hints handler has been set using this method, then the handler will be called.
      Parameters:
      handler -
      Returns:
      a reference to this, so the API can be used fluently

    • redirectHandler

      public HttpClientRequest redirectHandler(Function<HttpClientResponse, Future<HttpClientRequest>> handler)

    • redirectHandler

      public HttpClientRequest redirectHandler(Function<HttpClientResponse, Single<HttpClientRequest>> handler)

    • sendHead

      @Deprecated public Future<Void> sendHead()
      Deprecated.
      Forces the head of the request to be written before end(String) is called on the request or any data is written to it.

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

      Returns:
      a future notified with the result of the write operation

    • rxSendHead

      @Deprecated public Completable rxSendHead()
      Deprecated.
      Forces the head of the request to be written before end(String) is called on the request or any data is written to it.

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

      Returns:
      a future notified with the result of the write operation

    • writeHead

      public Future<Void> writeHead()
      Write the head of the request.

      This can be used to implement HTTP 100-continue handling, see continueHandler(Handler) for more information.

      Returns:
      a future notified with the result of the write operation

    • rxWriteHead

      public Completable rxWriteHead()
      Write the head of the request.

      This can be used to implement HTTP 100-continue handling, see continueHandler(Handler) for more information.

      Returns:
      a future notified with the result of the write operation

    • connect

      public Future<HttpClientResponse> connect()
      Create an HTTP tunnel to the server.

      Send HTTP request headers to the server, then configures the transport to exchange raw buffers when the server replies with an appropriate response:

      • 200 for HTTP CONNECT method
      • 101 for HTTP/1.1 GET with Upgrade connection header

      The handler is called after response headers are received.

      Use HttpClientResponse.netSocket() to get a for interacting more conveniently with the server.

      HTTP/1.1 pipe-lined requests are not supported.f

      Returns:
      a future notified with the server response

    • rxConnect

      public Single<HttpClientResponse> rxConnect()
      Create an HTTP tunnel to the server.

      Send HTTP request headers to the server, then configures the transport to exchange raw buffers when the server replies with an appropriate response:

      • 200 for HTTP CONNECT method
      • 101 for HTTP/1.1 GET with Upgrade connection header

      The handler is called after response headers are received.

      Use HttpClientResponse.netSocket() to get a for interacting more conveniently with the server.

      HTTP/1.1 pipe-lined requests are not supported.f

      Returns:
      a future notified with the server response

    • response

      public Future<HttpClientResponse> response()
      Returns:
      a future of the HttpClientResponse, this method does not modify the current request being sent.

    • rxResponse

      public Single<HttpClientResponse> rxResponse()
      Returns:
      a future of the HttpClientResponse, this method does not modify the current request being sent.

    • send

      public Future<HttpClientResponse> send()
      Send the request with an empty body.
      Returns:
      a future notified when the HTTP response is available

    • rxSend

      public Single<HttpClientResponse> rxSend()
      Send the request with an empty body.
      Returns:
      a future notified when the HTTP response is available

    • send

      public Future<HttpClientResponse> send(String body)
      Send the request with a string body.
      Parameters:
      body -
      Returns:
      a future notified when the HTTP response is available

    • rxSend

      public Single<HttpClientResponse> rxSend(String body)
      Send the request with a string body.
      Parameters:
      body -
      Returns:
      a future notified when the HTTP response is available

    • send

      public Future<HttpClientResponse> send(Buffer body)
      Send the request with a buffer body.
      Parameters:
      body -
      Returns:
      a future notified when the HTTP response is available

    • rxSend

      public Single<HttpClientResponse> rxSend(Buffer body)
      Send the request with a buffer body.
      Parameters:
      body -
      Returns:
      a future notified when the HTTP response is available

    • send

      public Future<HttpClientResponse> send(ClientForm form)
      Like send() but with a form. The content will be set to application/x-www-form-urlencoded or multipart/form-data according to the nature of the form.
      Parameters:
      form - the form to send
      Returns:
      a future notified when the HTTP response is available

    • rxSend

      public Single<HttpClientResponse> rxSend(ClientForm form)
      Like send() but with a form. The content will be set to application/x-www-form-urlencoded or multipart/form-data according to the nature of the form.
      Parameters:
      form - the form to send
      Returns:
      a future notified when the HTTP response is available

    • send

      public Future<HttpClientResponse> send(ReadStream<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:
      a future notified when the HTTP response is available

    • rxSend

      public Single<HttpClientResponse> rxSend(ReadStream<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:
      a future notified when the HTTP response is available

    • send

      public Future<HttpClientResponse> send(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:
      a future notified when the HTTP response is available

    • rxSend

      public Single<HttpClientResponse> rxSend(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:
      a future notified when the HTTP response is available

    • end

      public Future<Void> end(String chunk)
      Same as end(String) but writes a String in UTF-8 encoding
      Parameters:
      chunk - the data chunk
      Returns:
      a future completed with the result

    • rxEnd

      public Completable rxEnd(String chunk)
      Same as end(String) but writes a String in UTF-8 encoding
      Parameters:
      chunk - the data chunk
      Returns:
      a future completed with the result

    • end

      public Future<Void> end(String chunk, String enc)
      Same as end(String) but writes a String with the specified encoding
      Parameters:
      chunk - the data chunk
      enc - the encoding
      Returns:
      a future completed with the result

    • rxEnd

      public Completable rxEnd(String chunk, String enc)
      Same as end(String) but writes a String with the specified encoding
      Parameters:
      chunk - the data chunk
      enc - the encoding
      Returns:
      a future completed with the result

    • end

      public Future<Void> end(Buffer chunk)
      Same as end(String) 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 -
      Returns:
      a future completed with the result

    • rxEnd

      public Completable rxEnd(Buffer chunk)
      Same as end(String) 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:
      rxEnd in interface WriteStream<Buffer>
      Parameters:
      chunk -
      Returns:
      a future completed with the result

    • end

      public Future<Void> end()
      Ends the request. If no data has been written to the request body, and writeHead() 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>
      Returns:
      a future completed with the result

    • rxEnd

      public Completable rxEnd()
      Ends the request. If no data has been written to the request body, and writeHead() 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:
      rxEnd in interface WriteStream<Buffer>
      Returns:
      a future completed with the result

    • idleTimeout

      public HttpClientRequest idleTimeout(long timeout)
      Sets the amount of time after which, if the request does not return any data within the timeout period, the request/response is closed and the related futures are failed with a TimeoutException, e.g. Future or Future response body.
      Parameters:
      timeout - the amount of time in milliseconds.
      Returns:
      a reference to this, so the API can be used fluently

    • pushHandler

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

      In addition the handler should call the response() 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

      public Future<Void> reset()
      Reset this stream with the error code 0.
      Returns:

    • rxReset

      public Completable rxReset()
      Reset this stream with the error code 0.
      Returns:

    • reset

      public Future<Void> reset(long code)
      Reset this request:

      • for HTTP/1.x, this closes the connection when the current request is inflight
      • for HTTP/2, this performs send an HTTP/2 reset frame with the specified error code
      • for HTTP/3, this is only effective if the stream has not been fully sent

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

      Stream reset should be avoided because the implementation works partially for HTTP/3 and reset error codes depends on the version of the protocol, cancel() should be used instead.

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

    • rxReset

      public Completable rxReset(long code)
      Reset this request:

      • for HTTP/1.x, this closes the connection when the current request is inflight
      • for HTTP/2, this performs send an HTTP/2 reset frame with the specified error code
      • for HTTP/3, this is only effective if the stream has not been fully sent

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

      Stream reset should be avoided because the implementation works partially for HTTP/3 and reset error codes depends on the version of the protocol, cancel() should be used instead.

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

    • cancel

      public Future<Boolean> cancel()
      Attempt to cancel the request according to the semantics of the underlying HTTP implementation.
      • for HTTP/1.x, this closes the connection when the current request is inflight
      • for HTTP/2, this performs send an HTTP/2 reset frame with the error 0x08
      • for HTTP/3, this resets or abort reading the underlying QUIC stream with code 0x10c
      Returns:
      a future notifying the cancellation outcome

    • rxCancel

      public Single<Boolean> rxCancel()
      Attempt to cancel the request according to the semantics of the underlying HTTP implementation.
      • for HTTP/1.x, this closes the connection when the current request is inflight
      • for HTTP/2, this performs send an HTTP/2 reset frame with the error 0x08
      • for HTTP/3, this resets or abort reading the underlying QUIC stream with code 0x10c
      Returns:
      a future notifying the cancellation outcome

    • reset

      public Future<Void> reset(long code, Throwable cause)
      Reset this request:

      • for HTTP/2, send an HTTP/2 reset frame with the specified error code
      • for HTTP/1.x, close 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
      cause - an optional cause that can be attached to the error code
      Returns:
      true when reset has been performed

    • rxReset

      public Completable rxReset(long code, Throwable cause)
      Reset this request:

      • for HTTP/2, send an HTTP/2 reset frame with the specified error code
      • for HTTP/1.x, close 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
      cause - an optional cause that can be attached to the error code
      Returns:
      true when reset has been performed

    • connection

      public HttpConnection connection()
      Returns:
      the HttpConnection associated with this request

    • writeCustomFrame

      public Future<Void> 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 writeHead() 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

    • rxWriteCustomFrame

      public Completable rxWriteCustomFrame(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 writeHead() 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

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

    • writeCustomFrame

      public Future<Void> writeCustomFrame(HttpFrame frame)
      Like writeCustomFrame(int, int, Buffer) but with an HttpFrame.
      Parameters:
      frame - the frame to write
      Returns:

    • rxWriteCustomFrame

      public Completable rxWriteCustomFrame(HttpFrame frame)
      Like writeCustomFrame(int, int, Buffer) but with an HttpFrame.
      Parameters:
      frame - the frame to write
      Returns:

    • setStreamPriority

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

    • getStreamPriority

      public StreamPriority getStreamPriority()
      Returns:
      the priority of the associated HTTP/2 stream for HTTP/2 otherwise null

    • putHeader

      public HttpClientRequest putHeader(CharSequence name, CharSequence value)
      Like putHeader(String, String) but using CharSequence
      Parameters:
      name -
      value -
      Returns:

    • putHeader

      public 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

      public HttpClientRequest putHeader(CharSequence name, Iterable<CharSequence> values)
      Like putHeader(String, String) but using CharSequence
      Parameters:
      name -
      values -
      Returns:

    • newInstance

      public static HttpClientRequest newInstance(HttpClientRequest arg)