Class WebClient

java.lang.Object
com.codename1.backend.WebClient
public final class WebClient extends Object

An outbound HTTP client with its own configuration: a client certificate for mutual TLS, an HTTP/2 requirement, timeouts, and a pool of connections that belongs to it alone.

The static methods on Web are a client with every default and no pool. Create one of these when a request needs more than that:

WebClient bank = new WebClient()
        .setClientCertificate(ClientCertificate.pkcs12(p12, password))
        .setRequireHttp2(true)
        .setRequestTimeoutMillis(10000);
Web.Result r = bank.getJson("https://api.bank.example/v1/balance", token);

Create it once and share it -- it is safe to use from every handler at once -- because the pool is what makes a second request to the same host skip the TCP and TLS handshakes. close() releases the pool.

The configuration is fixed by the first request. A setter called after one throws IllegalStateException. Changing the credential of a client whose pool already holds connections authenticated as somebody else is exactly how two identities end up sharing a connection, so it is not possible; make a second client instead. Two clients never share a connection, whatever their configuration.

Certificate and hostname verification are always on, as they are for Web: there is no option to turn them off, and a client certificate does not change how the server's certificate is checked.

HTTP/2. With setRequireHttp2(boolean) the request is made over HTTP/2 or not at all: a peer that does not speak it fails the request with an IOException saying so, and the request is not sent to it as HTTP/1.1. Without it the packaged binary offers HTTP/2 over TLS and falls back to HTTP/1.1 when the server declines; Web.Result.getProtocol() says which was used. The local Java SE runtime speaks HTTP/1.1 only (its client is HttpURLConnection, the one every JDK this runs on has), so there a client that REQUIRES HTTP/2 fails every request with an IOException that says so, rather than quietly succeeding over a protocol the caller ruled out.

  • Constructor Details

    • WebClient

      public WebClient()

  • Method Details

    • setRequireHttp2

      public WebClient setRequireHttp2(boolean requireHttp2)
      Requires HTTP/2: a peer that does not negotiate it fails the request. Default false.

    • isRequireHttp2

      public boolean isRequireHttp2()

    • setClientCertificate

      public WebClient setClientCertificate(ClientCertificate clientCertificate)
      The certificate presented when a server asks for one, or null for none.

    • getClientCertificate

      public ClientCertificate getClientCertificate()

    • setConnectTimeoutMillis

      public WebClient setConnectTimeoutMillis(int millis)
      How long establishing the connection -- TCP and TLS -- may take. Default 30000; 0 means no limit.

    • getConnectTimeoutMillis

      public int getConnectTimeoutMillis()

    • setReadTimeoutMillis

      public WebClient setReadTimeoutMillis(int millis)

      How long the transfer may make NO progress before it is abandoned. Default 30000; 0 means no limit. A transfer that keeps moving is never cut off by this, however long it takes -- that is the request timeout.

      The packaged binary measures this in whole seconds (libcurl's low-speed limit), so a value is rounded UP to the next second there.

    • getReadTimeoutMillis

      public int getReadTimeoutMillis()

    • setRequestTimeoutMillis

      public WebClient setRequestTimeoutMillis(int millis)
      The ceiling on a whole request, connection to last byte. Default 0, no ceiling. A request still running when it is reached fails with an IOException.

    • getRequestTimeoutMillis

      public int getRequestTimeoutMillis()

    • setReuseConnections

      public WebClient setReuseConnections(boolean reuseConnections)
      Whether a finished request's connection is kept for the next request to the same server. Default true. With false every request opens, and closes, a connection of its own.

    • isReuseConnections

      public boolean isReuseConnections()

    • get

      public Web.Result get(String url) throws IOException
      Throws:
      IOException

    • getJson

      public Web.Result getJson(String url, String bearerToken) throws IOException
      Throws:
      IOException

    • postJson

      public Web.Result postJson(String url, String json, String bearerToken) throws IOException
      Throws:
      IOException

    • request

      public Web.Result request(String method, String url, List headers, byte[] body) throws IOException
      As [Web#request(String, String, List, byte[])], through this client.
      Throws:
      IOException

    • close

      public void close()
      Releases the client's pooled connections. A request made after this fails; one already running finishes first, and the last of them releases the connections.