Fan

 

class

web::WebClient

sys::Obj
  web::WebClient

The WebClient class is used to manage client side HTTP requests and responses. The basic lifecycle of WebClient:

  1. configure request fields such as reqUri, reqMethod, and reqHeaders
  2. send request headers via writeReq
  3. optionally write request body via reqOut
  4. read response status and headers via readRes
  5. process response fields such as resCode and resHeaders
  6. optionally read response body via resIn

Using the low level methods writeReq and readRes enables HTTP pipelining (multiple requests and responses on the same TCP socket connection). There are also a series of convenience methods which make common cases easier.

See docLib::Web and docCookbook::Web.

Slots

closeSource

This close()

Close the HTTP request and the underlying socket. Return this.

followRedirectsSource

Bool followRedirects := true

When set to true a 3xx response with a Location header will automatically update the reqUri field and retry the request using the alternate URI. Redirects are not followed if the request has a content body.

getBufSource

Buf getBuf()

Make a GET request and return the response content as an in-memory byte buffer. The web client is automatically closed. Throw IOErr is response is not 200.

getInSource

InStream getIn()

Make a GET request and return the input stream to the response or throw IOErr if response is not 200. It is the caller's responsibility to close this web client.

getStrSource

Str getStr()

Make a GET request and return the response content as an in-memory string. The web client is automatically closed. Throw IOErr is response is not 200.

isConnectedSource

Bool isConnected()

Return if this web client is currently connected to the remote host.

makeSource

new make(Uri? reqUri := null)

Construct with optional request URI.

postFormSource

This postForm(Str:Str form)

Make a post request to the URI with the given form data. Set the Content-Type to application/x-www-form-urlencoded. Upon completion the response is ready to be read.

readResSource

This readRes()

Read the response status line and response headers. This method may be called after the request has been written via writeReq and reqOut. Once this method completes the response status and headers are available. If there is a response body, it is available for reading via resIn. Throw IOErr if there is a network or protocol error. Return this.

reqHeadersSource

Str:Str reqHeaders := ...

The HTTP headers to use for the next request. This map uses case insensitive keys. The "Host" header is implicitly defined by reqUri and must not be defined in this map.

reqMethodSource

Str reqMethod := "GET"

The HTTP method for the request. Defaults to "GET".

reqOutSource

OutStream reqOut()

Get the output stream used to write the request body. This stream is only available if the request headers included a "Content-Type" header. If an explicit "Content-Length" was specified then this is a fixed length output stream, otherwise the request is automatically configured to use a chunked transfer encoding. This stream should be closed once the content has been fully written.

reqUriSource

Uri reqUri := ``

The absolute URI of request.

reqVersionSource

Version reqVersion := ver11

HTTP version to use for request must be 1.0 or 1.1. Default is 1.1.

resBufSource

Buf resBuf()

Return the entire response back as an in-memory byte buffer. Convenience for resIn.readAllBuf.

resCodeSource

Int resCode

HTTP status code returned by response.

resHeaderSource

Str? resHeader(Str key, Bool checked := true)

Get a response header. If not found and checked is false then return true, otherwise throw Err.

resHeadersSource

Str:Str resHeaders := noHeaders

HTTP headers returned by response.

resInSource

InStream resIn()

Input stream to read response content. The input stream will correctly handle end of stream when the content has been fully read. If the "Content-Length" header was specified the end of stream is based on the fixed number of bytes. If the "Transfer-Encoding" header defines a chunked encoding, then chunks are automatically handled. If the response has no content body, then throw IOErr.

The response input stream is automatically configured with the correct character encoding if one is specified in the "Content-Type" response header.

Also see convenience methods: resStr and resBuf.

resPhraseSource

Str resPhrase := ""

HTTP status reason phrase returned by response.

resStrSource

Str resStr()

Return the entire response back as an in-memory string. Convenience for resIn.readAllStr.

resVersionSource

Version resVersion := ver11

HTTP version returned by response.

socketOptionsSource

SocketOptions socketOptions()

Socket options for the TCP socket used for requests.

writeReqSource

This writeReq()

Write the request line and request headers. Once this method completes the request body may be written via reqOut, or the response may be immediately read via readRes. Throw IOErr if there is a network or protocol error. Return this.