OkHttpClient.Builder (OkHttp 3.12.0 API)

java.lang.Object
- okhttp3.OkHttpClient.Builder

Enclosing class:: OkHttpClient

public static final class OkHttpClient.Builder
extends Object

Constructor Summary

Constructors
Constructor and Description

Builder()

Constructors
Constructor and Description
`Builder()`

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`OkHttpClient.Builder`	`addInterceptor(Interceptor interceptor)`
`OkHttpClient.Builder`	`addNetworkInterceptor(Interceptor interceptor)`
`OkHttpClient.Builder`	`authenticator(Authenticator authenticator)` Sets the authenticator used to respond to challenges from origin servers.
`OkHttpClient`	`build()`
`OkHttpClient.Builder`	`cache(Cache cache)` Sets the response cache to be used to read and write cached responses.
`OkHttpClient.Builder`	`callTimeout(java.time.Duration duration)` Sets the default timeout for complete calls.
`OkHttpClient.Builder`	`callTimeout(long timeout, TimeUnit unit)` Sets the default timeout for complete calls.
`OkHttpClient.Builder`	`certificatePinner(CertificatePinner certificatePinner)` Sets the certificate pinner that constrains which certificates are trusted.
`OkHttpClient.Builder`	`connectionPool(ConnectionPool connectionPool)` Sets the connection pool used to recycle HTTP and HTTPS connections.
`OkHttpClient.Builder`	`connectionSpecs(List<ConnectionSpec> connectionSpecs)`
`OkHttpClient.Builder`	`connectTimeout(java.time.Duration duration)` Sets the default connect timeout for new connections.
`OkHttpClient.Builder`	`connectTimeout(long timeout, TimeUnit unit)` Sets the default connect timeout for new connections.
`OkHttpClient.Builder`	`cookieJar(CookieJar cookieJar)` Sets the handler that can accept cookies from incoming HTTP responses and provides cookies to outgoing HTTP requests.
`OkHttpClient.Builder`	`dispatcher(Dispatcher dispatcher)` Sets the dispatcher used to set policy and execute asynchronous requests.
`OkHttpClient.Builder`	`dns(Dns dns)` Sets the DNS service used to lookup IP addresses for hostnames.
`OkHttpClient.Builder`	`eventListener(EventListener eventListener)` Configure a single client scoped listener that will receive all analytic events for this client.
`OkHttpClient.Builder`	`eventListenerFactory(EventListener.Factory eventListenerFactory)` Configure a factory to provide per-call scoped listeners that will receive analytic events for this client.
`OkHttpClient.Builder`	`followRedirects(boolean followRedirects)` Configure this client to follow redirects.
`OkHttpClient.Builder`	`followSslRedirects(boolean followProtocolRedirects)` Configure this client to follow redirects from HTTPS to HTTP and from HTTP to HTTPS.
`OkHttpClient.Builder`	`hostnameVerifier(HostnameVerifier hostnameVerifier)` Sets the verifier used to confirm that response certificates apply to requested hostnames for HTTPS connections.
`List<Interceptor>`	`interceptors()` Returns a modifiable list of interceptors that observe the full span of each call: from before the connection is established (if any) until after the response source is selected (either the origin server, cache, or both).
`List<Interceptor>`	`networkInterceptors()` Returns a modifiable list of interceptors that observe a single network request and response.
`OkHttpClient.Builder`	`pingInterval(java.time.Duration duration)` Sets the interval between HTTP/2 and web socket pings initiated by this client.
`OkHttpClient.Builder`	`pingInterval(long interval, TimeUnit unit)` Sets the interval between HTTP/2 and web socket pings initiated by this client.
`OkHttpClient.Builder`	`protocols(List<Protocol> protocols)` Configure the protocols used by this client to communicate with remote servers.
`OkHttpClient.Builder`	`proxy(Proxy proxy)` Sets the HTTP proxy that will be used by connections created by this client.
`OkHttpClient.Builder`	`proxyAuthenticator(Authenticator proxyAuthenticator)` Sets the authenticator used to respond to challenges from proxy servers.
`OkHttpClient.Builder`	`proxySelector(ProxySelector proxySelector)` Sets the proxy selection policy to be used if no `proxy` is specified explicitly.
`OkHttpClient.Builder`	`readTimeout(java.time.Duration duration)` Sets the default read timeout for new connections.
`OkHttpClient.Builder`	`readTimeout(long timeout, TimeUnit unit)` Sets the default read timeout for new connections.
`OkHttpClient.Builder`	`retryOnConnectionFailure(boolean retryOnConnectionFailure)` Configure this client to retry or not when a connectivity problem is encountered.
`OkHttpClient.Builder`	`socketFactory(SocketFactory socketFactory)` Sets the socket factory used to create connections.
`OkHttpClient.Builder`	`sslSocketFactory(SSLSocketFactory sslSocketFactory)` Deprecated. `SSLSocketFactory` does not expose its `X509TrustManager`, which is a field that OkHttp needs to build a clean certificate chain. This method instead must use reflection to extract the trust manager. Applications should prefer to call `sslSocketFactory(SSLSocketFactory, X509TrustManager)`, which avoids such reflection.
`OkHttpClient.Builder`	`sslSocketFactory(SSLSocketFactory sslSocketFactory, X509TrustManager trustManager)` Sets the socket factory and trust manager used to secure HTTPS connections.
`OkHttpClient.Builder`	`writeTimeout(java.time.Duration duration)` Sets the default write timeout for new connections.
`OkHttpClient.Builder`	`writeTimeout(long timeout, TimeUnit unit)` Sets the default write timeout for new connections.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Builder
```
public Builder()
```
- Method Detail
  - callTimeout
```
public OkHttpClient.Builder callTimeout(long timeout,
                                        TimeUnit unit)
```
    Sets the default timeout for complete calls. A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE when converted to milliseconds.
    The call timeout spans the entire call: resolving DNS, connecting, writing the request body, server processing, and reading the response body. If the call requires redirects or retries all must complete within one timeout period.
  - callTimeout
```
@IgnoreJRERequirement
public OkHttpClient.Builder callTimeout(java.time.Duration duration)
```
    Sets the default timeout for complete calls. A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE when converted to milliseconds.
    The call timeout spans the entire call: resolving DNS, connecting, writing the request body, server processing, and reading the response body. If the call requires redirects or retries all must complete within one timeout period.
  - connectTimeout
```
public OkHttpClient.Builder connectTimeout(long timeout,
                                           TimeUnit unit)
```
    Sets the default connect timeout for new connections. A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE when converted to milliseconds.
    The connect timeout is applied when connecting a TCP socket to the target host. The default value is 10 seconds.
  - connectTimeout
```
@IgnoreJRERequirement
public OkHttpClient.Builder connectTimeout(java.time.Duration duration)
```
    Sets the default connect timeout for new connections. A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE when converted to milliseconds.
    The connect timeout is applied when connecting a TCP socket to the target host. The default value is 10 seconds.
  - readTimeout
```
public OkHttpClient.Builder readTimeout(long timeout,
                                        TimeUnit unit)
```
    Sets the default read timeout for new connections. A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE when converted to milliseconds.
    The read timeout is applied to both the TCP socket and for individual read IO operations including on Source of the Response. The default value is 10 seconds.
    
    See Also:
    
    Socket.setSoTimeout(int), Source.timeout()
  - readTimeout
```
@IgnoreJRERequirement
public OkHttpClient.Builder readTimeout(java.time.Duration duration)
```
    Sets the default read timeout for new connections. A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE when converted to milliseconds.
    The read timeout is applied to both the TCP socket and for individual read IO operations including on Source of the Response. The default value is 10 seconds.
    
    See Also:
    
    Socket.setSoTimeout(int), Source.timeout()
  - writeTimeout
```
public OkHttpClient.Builder writeTimeout(long timeout,
                                         TimeUnit unit)
```
    Sets the default write timeout for new connections. A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE when converted to milliseconds.
    The write timeout is applied for individual write IO operations. The default value is 10 seconds.
    
    See Also:
    
    Sink.timeout()
  - writeTimeout
```
@IgnoreJRERequirement
public OkHttpClient.Builder writeTimeout(java.time.Duration duration)
```
    Sets the default write timeout for new connections. A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE when converted to milliseconds.
    The write timeout is applied for individual write IO operations. The default value is 10 seconds.
    
    See Also:
    
    Sink.timeout()
  - pingInterval
```
public OkHttpClient.Builder pingInterval(long interval,
                                         TimeUnit unit)
```
    Sets the interval between HTTP/2 and web socket pings initiated by this client. Use this to automatically send ping frames until either the connection fails or it is closed. This keeps the connection alive and may detect connectivity failures.
    If the server does not respond to each ping with a pong within interval, this client will assume that connectivity has been lost. When this happens on a web socket the connection is canceled and its listener is notified of the failure. When it happens on an HTTP/2 connection the connection is closed and any calls it is carrying will fail with an IOException.
    The default value of 0 disables client-initiated pings.
  - pingInterval
```
@IgnoreJRERequirement
public OkHttpClient.Builder pingInterval(java.time.Duration duration)
```
    Sets the interval between HTTP/2 and web socket pings initiated by this client. Use this to automatically send ping frames until either the connection fails or it is closed. This keeps the connection alive and may detect connectivity failures.
    If the server does not respond to each ping with a pong within interval, this client will assume that connectivity has been lost. When this happens on a web socket the connection is canceled and its listener is notified of the failure. When it happens on an HTTP/2 connection the connection is closed and any calls it is carrying will fail with an IOException.
    The default value of 0 disables client-initiated pings.
  - proxy
```
public OkHttpClient.Builder proxy(@Nullable
                                  Proxy proxy)
```
    Sets the HTTP proxy that will be used by connections created by this client. This takes precedence over proxySelector, which is only honored when this proxy is null (which it is by default). To disable proxy use completely, call proxy(Proxy.NO_PROXY).
  - proxySelector
```
public OkHttpClient.Builder proxySelector(ProxySelector proxySelector)
```
    Sets the proxy selection policy to be used if no proxy is specified explicitly. The proxy selector may return multiple proxies; in that case they will be tried in sequence until a successful connection is established.
    If unset, the system-wide default proxy selector will be used.
  - cookieJar
```
public OkHttpClient.Builder cookieJar(CookieJar cookieJar)
```
    Sets the handler that can accept cookies from incoming HTTP responses and provides cookies to outgoing HTTP requests.
    If unset, no cookies will be accepted nor provided.
  - cache
```
public OkHttpClient.Builder cache(@Nullable
                                  Cache cache)
```
    Sets the response cache to be used to read and write cached responses.
  - dns
```
public OkHttpClient.Builder dns(Dns dns)
```
    Sets the DNS service used to lookup IP addresses for hostnames.
    If unset, the system-wide default DNS will be used.
  - socketFactory
```
public OkHttpClient.Builder socketFactory(SocketFactory socketFactory)
```
    Sets the socket factory used to create connections. OkHttp only uses the parameterless createSocket() method to create unconnected sockets. Overriding this method, e. g., allows the socket to be bound to a specific local address.
    If unset, the system-wide default socket factory will be used.
  - sslSocketFactory
```
public OkHttpClient.Builder sslSocketFactory(SSLSocketFactory sslSocketFactory)
```
    Deprecated. SSLSocketFactory does not expose its X509TrustManager, which is a field that OkHttp needs to build a clean certificate chain. This method instead must use reflection to extract the trust manager. Applications should prefer to call sslSocketFactory(SSLSocketFactory, X509TrustManager), which avoids such reflection.
    
    Sets the socket factory used to secure HTTPS connections. If unset, the system default will be used.
  - sslSocketFactory
```
public OkHttpClient.Builder sslSocketFactory(SSLSocketFactory sslSocketFactory,
                                             X509TrustManager trustManager)
```
    Sets the socket factory and trust manager used to secure HTTPS connections. If unset, the system defaults will be used.
    Most applications should not call this method, and instead use the system defaults. Those classes include special optimizations that can be lost if the implementations are decorated.
    If necessary, you can create and configure the defaults yourself with the following code:
```
   

   TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(
       TrustManagerFactory.getDefaultAlgorithm());
   trustManagerFactory.init((KeyStore) null);
   TrustManager[] trustManagers = trustManagerFactory.getTrustManagers();
   if (trustManagers.length != 1 || !(trustManagers[0] instanceof X509TrustManager)) {
     throw new IllegalStateException("Unexpected default trust managers:"
         + Arrays.toString(trustManagers));
   }
   X509TrustManager trustManager = (X509TrustManager) trustManagers[0];

   SSLContext sslContext = SSLContext.getInstance("TLS");
   sslContext.init(null, new TrustManager[] { trustManager }, null);
   SSLSocketFactory sslSocketFactory = sslContext.getSocketFactory();

   OkHttpClient client = new OkHttpClient.Builder()
       .sslSocketFactory(sslSocketFactory, trustManager)
       .build();
 
```
  - hostnameVerifier
```
public OkHttpClient.Builder hostnameVerifier(HostnameVerifier hostnameVerifier)
```
    Sets the verifier used to confirm that response certificates apply to requested hostnames for HTTPS connections.
    If unset, a default hostname verifier will be used.
  - certificatePinner
```
public OkHttpClient.Builder certificatePinner(CertificatePinner certificatePinner)
```
    Sets the certificate pinner that constrains which certificates are trusted. By default HTTPS connections rely on only the SSL socket factory to establish trust. Pinning certificates avoids the need to trust certificate authorities.
  - authenticator
```
public OkHttpClient.Builder authenticator(Authenticator authenticator)
```
    Sets the authenticator used to respond to challenges from origin servers. Use proxyAuthenticator to set the authenticator for proxy servers.
    If unset, the no authentication will be attempted.
  - proxyAuthenticator
```
public OkHttpClient.Builder proxyAuthenticator(Authenticator proxyAuthenticator)
```
    Sets the authenticator used to respond to challenges from proxy servers. Use authenticator to set the authenticator for origin servers.
    If unset, the no authentication will be attempted.
  - connectionPool
```
public OkHttpClient.Builder connectionPool(ConnectionPool connectionPool)
```
    Sets the connection pool used to recycle HTTP and HTTPS connections.
    If unset, a new connection pool will be used.
  - followSslRedirects
```
public OkHttpClient.Builder followSslRedirects(boolean followProtocolRedirects)
```
    Configure this client to follow redirects from HTTPS to HTTP and from HTTP to HTTPS.
    If unset, protocol redirects will be followed. This is different than the built-in HttpURLConnection's default.
  - followRedirects
```
public OkHttpClient.Builder followRedirects(boolean followRedirects)
```
    Configure this client to follow redirects. If unset, redirects will be followed.
  - retryOnConnectionFailure
```
public OkHttpClient.Builder retryOnConnectionFailure(boolean retryOnConnectionFailure)
```
    Configure this client to retry or not when a connectivity problem is encountered. By default, this client silently recovers from the following problems:
    - Unreachable IP addresses. If the URL's host has multiple IP addresses, failure to reach any individual IP address doesn't fail the overall request. This can increase availability of multi-homed services.
    - Stale pooled connections. The ConnectionPool reuses sockets to decrease request latency, but these connections will occasionally time out.
    - Unreachable proxy servers. A ProxySelector can be used to attempt multiple proxy servers in sequence, eventually falling back to a direct connection.
    Set this to false to avoid retrying requests when doing so is destructive. In this case the calling application should do its own recovery of connectivity failures.
  - dispatcher
```
public OkHttpClient.Builder dispatcher(Dispatcher dispatcher)
```
    Sets the dispatcher used to set policy and execute asynchronous requests. Must not be null.
  - protocols
```
public OkHttpClient.Builder protocols(List<Protocol> protocols)
```
    Configure the protocols used by this client to communicate with remote servers. By default this client will prefer the most efficient transport available, falling back to more ubiquitous protocols. Applications should only call this method to avoid specific compatibility problems, such as web servers that behave incorrectly when HTTP/2 is enabled.
    The following protocols are currently supported:
    This is an evolving set. Future releases include support for transitional protocols. The http/1.1 transport will never be dropped.
    If multiple protocols are specified, ALPN will be used to negotiate a transport. Protocol negotiation is only attempted for HTTPS URLs.
    Protocol.HTTP_1_0 is not supported in this set. Requests are initiated with HTTP/1.1. If the server responds with HTTP/1.0, that will be exposed by Response.protocol().
    Parameters:
    
    protocols - the protocols to use, in order of preference. If the list contains Protocol.H2_PRIOR_KNOWLEDGE then that must be the only protocol and HTTPS URLs will not be supported. Otherwise the list must contain Protocol.HTTP_1_1. The list must not contain null or Protocol.HTTP_1_0.
  - connectionSpecs
```
public OkHttpClient.Builder connectionSpecs(List<ConnectionSpec> connectionSpecs)
```
  - interceptors
```
public List<Interceptor> interceptors()
```
    Returns a modifiable list of interceptors that observe the full span of each call: from before the connection is established (if any) until after the response source is selected (either the origin server, cache, or both).
  - addInterceptor
```
public OkHttpClient.Builder addInterceptor(Interceptor interceptor)
```
  - networkInterceptors
```
public List<Interceptor> networkInterceptors()
```
    Returns a modifiable list of interceptors that observe a single network request and response. These interceptors must call Interceptor.Chain.proceed(okhttp3.Request) exactly once: it is an error for a network interceptor to short-circuit or repeat a network request.
  - addNetworkInterceptor
```
public OkHttpClient.Builder addNetworkInterceptor(Interceptor interceptor)
```
  - eventListener
```
public OkHttpClient.Builder eventListener(EventListener eventListener)
```
    Configure a single client scoped listener that will receive all analytic events for this client.
    
    See Also:
    
    for semantics and restrictions on listener implementations.
  - eventListenerFactory
```
public OkHttpClient.Builder eventListenerFactory(EventListener.Factory eventListenerFactory)
```
    Configure a factory to provide per-call scoped listeners that will receive analytic events for this client.
    
    See Also:
    
    for semantics and restrictions on listener implementations.
  - build
```
public OkHttpClient build()
```

Class OkHttpClient.Builder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Builder

Method Detail

callTimeout

callTimeout

connectTimeout

connectTimeout

readTimeout

readTimeout

writeTimeout

writeTimeout

pingInterval

pingInterval

proxy

proxySelector

cookieJar

cache

dns

socketFactory

sslSocketFactory

sslSocketFactory

hostnameVerifier

certificatePinner

authenticator

proxyAuthenticator

connectionPool

followSslRedirects

followRedirects

retryOnConnectionFailure

dispatcher

protocols

connectionSpecs

interceptors

addInterceptor

networkInterceptors

addNetworkInterceptor

eventListener

eventListenerFactory

build