org.vertx.java.core.http

## Interface HttpClientRequest

- All Superinterfaces:
    WriteStream

      public interface HttpClientRequest
      extends WriteStream

  Represents a client-side HTTP request.

  Instances of this class are created by an `HttpClient` instance, via one of the methods corresponding to the specific HTTP methods, or the generic `HttpClient.request(java.lang.String, java.lang.String, org.vertx.java.core.Handler<org.vertx.java.core.http.HttpClientResponse>)` method.

  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, the `end()` method 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 actually sent 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.

  Instances of this class are not thread-safe

  An example of using this class is as follows:

       HttpClientRequest req = httpClient.post("/some-url", new Handler() {
         public void handle(HttpClientResponse response) {
           System.out.println("Got response: " + response.statusCode);
         }
       });

       req.headers().put("some-header", "hello")
           .put("Content-Length", 5)
           .write(new Buffer(new byte[]{1, 2, 3, 4, 5}))
           .write(new Buffer(new byte[]{6, 7, 8, 9, 10}))
           .end();

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `continueHandler(Handler<java.lang.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.
    `void` | `end()` Ends the request.
    `void` | `end(Buffer chunk)` Same as `end()` but writes some data to the request body before ending.
    `void` | `end(java.lang.String chunk)` Same as `end(Buffer)` but writes a String with the default encoding
    `void` | `end(java.lang.String chunk, java.lang.String enc)` Same as `end(Buffer)` but writes a String with the specified encoding
    `java.util.Map<java.lang.String,java.lang.Object>` | `headers()`
    `HttpClientRequest` | `putHeader(java.lang.String name, java.lang.Object value)` Put an HTTP header - fluent API
    `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` | `setChunked(boolean chunked)` If chunked is true then the request will be set into HTTP chunked mode
    `HttpClientRequest` | `setTimeout(long timeoutMs)` Set's the amount of time after which if a response is not received TimeoutException() will be sent to the exception handler of this request.
    `HttpClientRequest` | `write(Buffer chunk)` Write a `Buffer` to the request body.
    `HttpClientRequest` | `write(Buffer chunk, Handler<java.lang.Void> doneHandler)` Write a `Buffer` to the request body.
    `HttpClientRequest` | `write(java.lang.String chunk)` Write a `String` to the request body, encoded in UTF-8.
    `HttpClientRequest` | `write(java.lang.String chunk, Handler<java.lang.Void> doneHandler)` Write a `String` to the request body, encoded in UTF-8.
    `HttpClientRequest` | `write(java.lang.String chunk, java.lang.String enc)` Write a `String` to the request body, encoded using the encoding `enc`.
    `HttpClientRequest` | `write(java.lang.String chunk, java.lang.String enc, Handler<java.lang.Void> doneHandler)` Write a `String` to the request body, encoded with encoding `enc`.

    - ### Methods inherited from interface org.vertx.java.core.streams.WriteStream

      `drainHandler, exceptionHandler, setWriteQueueMaxSize, writeBuffer, writeQueueFull`

- - ### Method Detail

    - #### setChunked

          HttpClientRequest setChunked(boolean chunked)

      If chunked is true then the request will be set into HTTP chunked mode
      Parameters:
        `chunked` -
      Returns:
        A reference to this, so multiple method calls can be chained.

    - #### headers

          java.util.Map<java.lang.String,java.lang.Object> headers()

      Returns:
        The HTTP headers

    - #### putHeader

          HttpClientRequest putHeader(java.lang.String name,
                                    java.lang.Object value)

      Put an HTTP header - fluent API
      Parameters:
        `name` - The header name
        `value` - The header value
      Returns:
        A reference to this, so multiple method calls can be chained.

    - #### write

          HttpClientRequest write(Buffer chunk)

      Write a `Buffer` to the request body.
      Returns:
        A reference to this, so multiple method calls can be chained.

    - #### write

          HttpClientRequest write(java.lang.String chunk)

      Write a `String` to the request body, encoded in UTF-8.
      Returns:
        A reference to this, so multiple method calls can be chained.

    - #### write

          HttpClientRequest write(java.lang.String chunk,
                                java.lang.String enc)

      Write a `String` to the request body, encoded using the encoding `enc`.
      Returns:
        A reference to this, so multiple method calls can be chained.

    - #### write

          HttpClientRequest write(Buffer chunk,
                                Handler<java.lang.Void> doneHandler)

      Write a `Buffer` to the request body. The `doneHandler` is called after the buffer is actually written to the wire.
      Returns:
        A reference to this, so multiple method calls can be chained.

    - #### write

          HttpClientRequest write(java.lang.String chunk,
                                Handler<java.lang.Void> doneHandler)

      Write a `String` to the request body, encoded in UTF-8. The `doneHandler` is called after the buffer is actually written to the wire.
      Returns:
        A reference to this, so multiple method calls can be chained.

    - #### write

          HttpClientRequest write(java.lang.String chunk,
                                java.lang.String enc,
                                Handler<java.lang.Void> doneHandler)

      Write a `String` to the request body, encoded with encoding `enc`. The `doneHandler` is called after the buffer is actually written to the wire.
      Returns:
        A reference to this, so multiple method calls can be chained.

    - #### continueHandler

          void continueHandler(Handler<java.lang.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.

    - #### 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(org.vertx.java.core.Handler)` for more information.
      Returns:
        A reference to this, so multiple method calls can be chained.

    - #### end

          void end(java.lang.String chunk)

      Same as `end(Buffer)` but writes a String with the default encoding

    - #### end

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

      Same as `end(Buffer)` but writes a String with the specified encoding

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

    - #### 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, and if keep alive is true the underlying connection will be returned to the `HttpClient` pool so it can be assigned to another request.

    - #### setTimeout

          HttpClientRequest setTimeout(long timeoutMs)

      Set's the amount of time after which if a response is not received TimeoutException() will be sent to the exception handler of this request. 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 multiple method calls can be chained.