Class List Method List File List

# Class: Vertx::HttpClientRequest

Inherits:
  Object
  - Object
  - Vertx::HttpClientRequest
  show all
Includes:
  WriteStream
Defined in:
  src/main/ruby_scripts/core/http.rb

## Overview

Encapsulates 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 Vertx::HttpClient#request method. Once an instance of this class 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 must called. Nothing is 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. An example of using this class is as follows:

Examples:

    req = httpClient.post("/some-url") do |response|
      puts "Got response #{response.status_code}"
    end

    req.put_header("some-header", "hello")

    req.chunked = true
    req.write(Buffer.create_from_str("chunk of body 1");
    req.write(Buffer.create_from_str("chunk of body 2");

    req.end(); # This actually sends the request

Author:

- Tim Fox

## Instance Method Summary (collapse)

- - (HttpClientRequest) chunked=(val)
  Sets whether the request should used HTTP chunked encoding or not.
- - (Object) continue_handler(proc = nil, &hndlr)
  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.
- - (Object) end
  Ends the request.
- - (Object) headers
  Hash of headers for the request.
- - (HttpClientRequest) put_header(key, value)
  Inserts a header into the request.
- - (HttpClientRequest) send_head
  Forces the head of the request to be written before #end is called on the request.
- - (HttpClientRequest) write_buffer(chunk, &hndlr)
  Write a [Buffer] to the request body.
- - (Object) write_buffer_and_end(chunk)
  Same as #end but writes some data to the response body before ending.
- - (HttpClientRequest) write_str(str, enc = "UTF-8", &hndlr)
  Write a [String] to the request body.
- - (Object) write_str_and_end(str, enc = "UTF-8")
  Same as #write_buffer_and_end but writes a String.

### Methods included from WriteStream

#drain_handler, #exception_handler, #write_queue_full?, #write_queue_max_size=

## Instance Method Details

### - (`HttpClientRequest`) chunked=(val)

Sets whether the request should used HTTP chunked encoding or not. 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 request. If chunked is false, this request will not use HTTP chunked encoding, and therefore if any data is written the body of the request, the total size of that data must be set in the 'Content-Length' header before any data is written to the request body.

Parameters:

- val. (`Boolean`) —
  If val is true, this request will use HTTP chunked encoding, and each call to write to the body

Returns:

- (`HttpClientRequest`) —
  self So multiple operations can be chained.

    390
    391
    392
    393
    # File 'src/main/ruby_scripts/core/http.rb', line 390

    def chunked=(val)
      @j_del.setChunked(val)
      self
    end

### - (`Object`) continue_handler(proc = nil, &hndlr)

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 #send_head method to force the request header to be written before the request has ended.

Parameters:

- proc. (`Proc`) —
  The handler
- hndlr. (`Block`) —
  The handler

    402
    403
    404
    405
    # File 'src/main/ruby_scripts/core/http.rb', line 402

    def continue_handler(proc = nil, &hndlr)
      hndlr = proc if proc
      @j_del.continueHandler(hndlr)
    end

### - (`Object`) end

Ends the request. If no data has been written to the request body, and #send_head 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 Vertx::HttpClient pool so it can be assigned to another request.

    364
    # File 'src/main/ruby_scripts/core/http.rb', line 364

    def end

### - (`Object`) headers

Hash of headers for the request

    317
    318
    319
    320
    321
    322
    # File 'src/main/ruby_scripts/core/http.rb', line 317

    def headers
      if !@headers
        @headers = @j_del.headers
      end
      @headers
    end

### - (`HttpClientRequest`) put_header(key, value)

Inserts a header into the request.

Parameters:

- key (`String`) —
  The header key
- value (`Object`) —
  The header value. to_s will be called on the value to determine the actual String value to insert.

Returns:

- (`HttpClientRequest`) —
  self So multiple operations can be chained.

    328
    329
    330
    331
    # File 'src/main/ruby_scripts/core/http.rb', line 328

    def put_header(key, value)
      @j_del.putHeader(key, value.to_s)
      self
    end

### - (`HttpClientRequest`) send_head

Forces the head of the request to be written before #end is called on the request. This is normally used to implement HTTP 100-continue handling, see #continue_handler for more information.

Returns:

- (`HttpClientRequest`) —
  self So multiple operations can be chained.

    355
    356
    357
    358
    # File 'src/main/ruby_scripts/core/http.rb', line 355

    def send_head
      @j_del.sendHead
      self
    end

### - (`HttpClientRequest`) write_buffer(chunk, &hndlr)

Write a [Buffer] to the request body.

Parameters:

- chunk. (`Buffer`) —
  The buffer to write.
- hndlr. (`Block`) —
  The handler will be called when the buffer has actually been written to the wire.

Returns:

- (`HttpClientRequest`) —
  self So multiple operations can be chained.

    337
    338
    339
    340
    # File 'src/main/ruby_scripts/core/http.rb', line 337

    def write_buffer(chunk, &hndlr)
      @j_del.writeBuffer(chunk._to_java_buffer)
      self
    end

### - (`Object`) write_buffer_and_end(chunk)

Same as #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 Content-Length header will be automatically set

Parameters:

- chunk (`Buffer`) —
  The Buffer to write

    378
    379
    380
    # File 'src/main/ruby_scripts/core/http.rb', line 378

    def write_buffer_and_end(chunk)
      @j_del.end(chunk._to_java_buffer)
    end

### - (`HttpClientRequest`) write_str(str, enc = "UTF-8", &hndlr)

Write a [String] to the request body.

Parameters:

- str. (`String`) —
  The string to write.
- enc. (`String`) —
  The encoding to use.
- hndlr. (`Block`) —
  The handler will be called when the buffer has actually been written to the wire.

Returns:

- (`HttpClientRequest`) —
  self So multiple operations can be chained.

    347
    348
    349
    350
    # File 'src/main/ruby_scripts/core/http.rb', line 347

    def write_str(str, enc = "UTF-8", &hndlr)
      @j_del.write(str, enc)
      self
    end

### - (`Object`) write_str_and_end(str, enc = "UTF-8")

Same as #write_buffer_and_end but writes a String

Parameters:

- str (`String`) —
  The String to write
- enc (`String`) (defaults to: `"UTF-8"`) —
  The encoding

    371
    372
    373
    # File 'src/main/ruby_scripts/core/http.rb', line 371

    def write_str_and_end(str, enc = "UTF-8")
      @j_del.end(str, enc)
    end