OkHttpClient¶

[jvm]\ open class OkHttpClient : Call.Factory, WebSocket.Factory

Factory for calls, which can be used to send HTTP requests and read their responses.

OkHttpClients Should Be Shared¶

OkHttp performs best when you create a single OkHttpClient instance and reuse it for all of your HTTP calls. This is because each client holds its own connection pool and thread pools. Reusing connections and threads reduces latency and saves memory. Conversely, creating a client for each request wastes resources on idle pools.

Use new OkHttpClient() to create a shared instance with the default settings:

// The singleton HTTP client.
public final OkHttpClient client = new OkHttpClient();

Or use new OkHttpClient.Builder() to create a shared instance with custom settings:

// The singleton HTTP client.
public final OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(new HttpLoggingInterceptor())
    .cache(new Cache(cacheDir, cacheSize))
    .build();

Customize Your Client With newBuilder()¶

You can customize a shared OkHttpClient instance with newBuilder. This builds a client that shares the same connection pool, thread pools, and configuration. Use the builder methods to add configuration to the derived client for a specific purpose.

This example shows the single instance with default configurations.

public final OkHttpClient client = new OkHttpClient.Builder()
    .readTimeout(1000, TimeUnit.MILLISECONDS)
    .writeTimeout(1000, TimeUnit.MILLISECONDS)
    .build();

This example shows a call with a short 500 millisecond read timeout and a 1000 millisecond write timeout. Original configuration is kept, but can be overriden.

OkHttpClient eagerClient = client.newBuilder()
    .readTimeout(500, TimeUnit.MILLISECONDS)
    .build();
Response response = eagerClient.newCall(request).execute();

Shutdown Isn’t Necessary¶

The threads and connections that are held will be released automatically if they remain idle. But if you are writing a application that needs to aggressively release unused resources you may do so.

Shutdown the dispatcher’s executor service with shutdown(). This will also cause future calls to the client to be rejected.

client.dispatcher().executorService().shutdown();

Clear the connection pool with evictAll(). Note that the connection pool’s daemon thread may not exit immediately.

client.connectionPool().evictAll();

If your client has a cache, call close(). Note that it is an error to create calls against a cache that is closed, and doing so will cause the call to crash.

client.cache().close();

OkHttp also uses daemon threads for HTTP/2 connections. These will exit automatically if they remain idle.

Constructors¶


OkHttpClient	[jvm] fun OkHttpClient()

Types¶

Name	Summary
Builder	[jvm] class Builder
Companion	[jvm] object Companion

Functions¶

Name	Summary
newBuilder	[jvm] open fun newBuilder(): OkHttpClient.Builder
newCall	[jvm] open override fun newCall(request: Request): Call Prepares the request to be executed at some point in the future.
newWebSocket	[jvm] open override fun newWebSocket(request: Request, listener: WebSocketListener): WebSocket Uses request to connect a new web socket.

Properties¶

Name	Summary
authenticator	[jvm] @get:JvmName(name = "authenticator") val authenticator: Authenticator
cache	[jvm] @get:JvmName(name = "cache") val cache: Cache?
callTimeoutMillis	[jvm] @get:JvmName(name = "callTimeoutMillis") val callTimeoutMillis: Int Default call timeout (in milliseconds). By default there is no timeout for complete calls, but there is for the connect, write, and read actions within a call.
certificateChainCleaner	[jvm] @get:JvmName(name = "certificateChainCleaner") val certificateChainCleaner: CertificateChainCleaner?
certificatePinner	[jvm] @get:JvmName(name = "certificatePinner") val certificatePinner: CertificatePinner
connectionPool	[jvm] @get:JvmName(name = "connectionPool") val connectionPool: ConnectionPool
connectionSpecs	[jvm] @get:JvmName(name = "connectionSpecs") val connectionSpecs: List<ConnectionSpec>
connectTimeoutMillis	[jvm] @get:JvmName(name = "connectTimeoutMillis") val connectTimeoutMillis: Int Default connect timeout (in milliseconds). The default is 10 seconds.
cookieJar	[jvm] @get:JvmName(name = "cookieJar") val cookieJar: CookieJar
dispatcher	[jvm] @get:JvmName(name = "dispatcher") val dispatcher: Dispatcher
dns	[jvm] @get:JvmName(name = "dns") val dns: Dns
eventListenerFactory	[jvm] @get:JvmName(name = "eventListenerFactory") val eventListenerFactory: EventListener.Factory
fastFallback	[jvm] @get:JvmName(name = "fastFallback") val fastFallback: Boolean
followRedirects	[jvm] @get:JvmName(name = "followRedirects") val followRedirects: Boolean
followSslRedirects	[jvm] @get:JvmName(name = "followSslRedirects") val followSslRedirects: Boolean
hostnameVerifier	[jvm] @get:JvmName(name = "hostnameVerifier") val hostnameVerifier: HostnameVerifier
interceptors	[jvm] @get:JvmName(name = "interceptors") val interceptors: List<Interceptor> Returns an immutable 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).
minWebSocketMessageToCompress	[jvm] @get:JvmName(name = "minWebSocketMessageToCompress") val minWebSocketMessageToCompress: Long Minimum outbound web socket message size (in bytes) that will be compressed. The default is 1024 bytes.
networkInterceptors	[jvm] @get:JvmName(name = "networkInterceptors") val networkInterceptors: List<Interceptor> Returns an immutable list of interceptors that observe a single network request and response. These interceptors must call Interceptor.Chain.proceed exactly once: it is an error for a network interceptor to short-circuit or repeat a network request.
pingIntervalMillis	[jvm] @get:JvmName(name = "pingIntervalMillis") val pingIntervalMillis: Int Web socket and HTTP/2 ping interval (in milliseconds). By default pings are not sent.
protocols	[jvm] @get:JvmName(name = "protocols") val protocols: List<Protocol>
proxy	[jvm] @get:JvmName(name = "proxy") val proxy: Proxy?
proxyAuthenticator	[jvm] @get:JvmName(name = "proxyAuthenticator") val proxyAuthenticator: Authenticator
proxySelector	[jvm] @get:JvmName(name = "proxySelector") val proxySelector: ProxySelector
readTimeoutMillis	[jvm] @get:JvmName(name = "readTimeoutMillis") val readTimeoutMillis: Int Default read timeout (in milliseconds). The default is 10 seconds.
retryOnConnectionFailure	[jvm] @get:JvmName(name = "retryOnConnectionFailure") val retryOnConnectionFailure: Boolean
socketFactory	[jvm] @get:JvmName(name = "socketFactory") val socketFactory: SocketFactory
sslSocketFactory	[jvm] @get:JvmName(name = "sslSocketFactory") val sslSocketFactory: SSLSocketFactory
writeTimeoutMillis	[jvm] @get:JvmName(name = "writeTimeoutMillis") val writeTimeoutMillis: Int Default write timeout (in milliseconds). The default is 10 seconds.
x509TrustManager	[jvm] @get:JvmName(name = "x509TrustManager") val x509TrustManager: X509TrustManager?