class web::WebClient

sys::Obj
  web::WebClient

Source

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 pod doc and examples.

authBasic

This authBasic(Str username, Str password)

Source

Authenticate request using HTTP Basic with given username and password.

close

This close()

Source

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

cookies

List<Cookie> cookies := List<>.defVal

Source

Cookies to pass for "Cookie" request header. If set to an empty list then the "Cookie" request header is removed. After a request has been completed if the "Set-Cookie" response header specified one or more cookies then this field is automatically updated with the server specified cookies.

followRedirects

Bool followRedirects := true

Source

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.

getBuf

Buf getBuf()

Source

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.

getIn

InStream getIn()

Source

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.

getStr

Str getStr()

Source

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.

isConnected

Bool isConnected()

Source

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

make

new make(Uri? reqUri := null)

Source

Construct with optional request URI.

postFile

This postFile(File file)

Source

Convenience for writeFile("POST", file).readRes

postForm

This postForm(Map<Str,Str> form)

Source

Convenience for writeForm("POST", form).readRes

postStr

This postStr(Str content)

Source

Convenience for writeStr("POST", content).readRes

proxy

Uri? proxy := proxyDef

Source

If non-null, then all requests are routed through this proxy address (host and port). Default is configured in "etc/web/config.props" with the key "proxy". Proxy exceptions can be configured with the "proxy.exceptions" config key as comma separated list of Regex globs.

readRes

This readRes()

Source

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.

reqHeaders

Map<Str,Str> reqHeaders := CaseInsensitiveMap<Str,Str>.<ctor>()

Source

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.

reqMethod

Str reqMethod := "GET"

Source

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

reqOut

OutStream reqOut()

Source

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.

reqUri

Uri reqUri := ``

Source

The absolute URI of request.

reqVersion

Version reqVersion := ver11

Source

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

resBuf

Buf resBuf()

Source

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

resCode

Int resCode

Source

HTTP status code returned by response.

resHeader

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

Source

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

resHeaders

Map<Str,Str> resHeaders := noHeaders

Source

HTTP headers returned by response.

resIn

InStream resIn()

Source

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.

resPhrase

Str resPhrase := ""

Source

HTTP status reason phrase returned by response.

resStr

Str resStr()

Source

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

resVersion

Version resVersion := ver11

Source

HTTP version returned by response.

socketConfig

SocketConfig socketConfig := SocketConfig.cur

Source

The SocketConfig to use for creating sockets

socketOptions

@Deprecated { msg=... }
SocketOptions socketOptions()

Source

writeFile

This writeFile(Str method, File file)

Source

Write a file using the given HTTP method to the URI. If Content-Type header is not already set, then it is set from the file extension's MIME type. This method does not support the "Expect" header (it writes full file before reading response). Should primarily be used for "POST" and "PATCH" requests.

writeForm

This writeForm(Str method, Map<Str,Str> form)

Source

Make a request with the given HTTP method to the URI with the given form data. Set the Content-Type to application/x-www-form-urlencoded. This method does not support the "Expect" header (it writes all form data before reading response). Should primarily be used for POST and PATCH requests.

writeReq

This writeReq()

Source

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.

writeStr

This writeStr(Str method, Str content)

Source

Make a request with the given HTTP method to the URI using UTF-8 encoding of given string. If Content-Type is not already set, then set it to "text/plain; charset=utf-8". This method does not support the "Expect" header (it writes full string before reading response). Should primarily be used for "POST" and "PATCH" requests.