skip to content

Why should an Android app share one OkHttpClient instance, and how does newBuilder() let you customize it without losing that sharing?

level: juniorimportance: must knowfreq 70%

answer

  1. pools and threads live inside
  2. a new client starts cold
  3. derive, don't rebuild
  4. newBuilder keeps pool, dispatcher, cache
  5. reuse needs matching connection settings

basics

~20 s

Each OkHttpClient owns a connection pool and a dispatcher with its own threads, so one shared instance lets calls reuse warm connections. newBuilder() derives a client that keeps the same pool, dispatcher and cache while overriding settings like timeouts.

solid answer

~40 s

An `OkHttpClient` is not just configuration: it holds a `ConnectionPool`, a `Dispatcher` with its executor, and optionally a `Cache`. Since OkHttp 3 every new client gets its own private pool, so a client per request repeats TCP and TLS setup, multiplies idle sockets and threads, and spreads the dispatcher's per-host limit across clients that cannot see each other. The fix is one client at app scope. When one call path needs different settings, call `sharedClient.newBuilder()`: the derived client points at the same pool, dispatcher and cache, gets a copy of the interceptor lists, and lets you override values such as `readTimeout`. Connections are reused across the two only when settings that form the connection's address, such as DNS, protocols or proxy, still match; timeouts are not among them.

go deeper

for a junior

Recall that the client holds a connection pool and a dispatcher, so one shared instance is the rule and newBuilder() is how you vary it.

for a middle

Explain what newBuilder() shares and what it copies: same pool, dispatcher and cache; copied interceptor lists and timeout values.

for a senior

Show you can spot the per-request client in a code review and explain its cost in handshakes, sockets and dispatcher limits that stop working.

for a principal

Frame the shared client as a team default: one app-scope instance, derived variants for the few paths that need them, and a review rule against ad hoc clients.

## What one OkHttpClient owns `OkHttpClient` reads like a bag of settings, but it carries state that is expensive to build and valuable to keep warm: - **A `ConnectionPool`.** Open HTTP/1.1 and HTTP/2 connections are parked here after a response so the next request to the same server skips the TCP and TLS handshakes. By default the pool keeps up to **5 idle connections** and evicts each after **5 minutes** without use. - **A `Dispatcher`.** It runs calls made with `enqueue()` on its executor and enforces two limits: **64** concurrent asynchronous calls in total and **5** per host by default. Its default thread pool creates threads on demand and lets an idle thread exit after 60 seconds. - **An optional `Cache`.** Response caching is off until you pass a `Cache` with a directory and a size. - **Interceptors and an `EventListener.Factory`.** The lists of application and network interceptors, and the factory that creates a metrics listener per call. Everything else on the client, such as timeouts, redirect policy and `retryOnConnectionFailure`, is plain configuration. ## What a client per request costs OkHttp 2 shared one global pool across all clients. Since OkHttp 3 **each new `OkHttpClient` gets its own private pool**, and the 3.0 release notes call out the consequence: many pools prevent connection reuse and each keeps its own idle connections alive. Building a client inside every repository method therefore means: 1. **Cold connections every time.** A brand-new pool is empty, so each call pays DNS, TCP and the TLS handshake again, which on a mobile network is often the slowest part of the request. 2. **More sockets and threads.** Each pool holds its idle connections for up to five minutes and each dispatcher grows its own threads, so resource use scales with the number of clients rather than the number of servers. 3. **Limits that no longer limit.** The per-host cap of 5 lives in one dispatcher; ten clients each enforce their own cap, so a server can see 50 concurrent requests from one app. 4. **Cache hazards.** A `Cache` directory must be owned by exactly one `Cache` instance. Code that creates a client and a new `Cache` on the same directory per call risks corrupting it. ## Customizing with newBuilder() `newBuilder()` returns a builder seeded from an existing client. Building from it produces a new, independent configuration that still shares the expensive parts: | Part of the client | After `sharedClient.newBuilder().build()` | |---|---| | `ConnectionPool` | the same instance | | `Dispatcher` | the same instance, so the same limits and threads | | `Cache` | the same instance | | Interceptor lists | copied into new lists holding the same interceptor objects | | Timeouts, redirects, `retryOnConnectionFailure` | copied as values you may override | So `sharedClient.newBuilder().readTimeout(60, TimeUnit.SECONDS).build()` gives a long-download client whose calls ride the same pool and obey the same dispatcher limits. Adding an interceptor on the derived builder changes only the derived client, because the lists were copied. One nuance decides whether a derived client actually reuses the shared connections. A pooled connection is handed out only when the request's **address** matches: host and port plus the client's `Dns`, proxy settings, `protocols`, connection specs, TLS socket factory, hostname verifier and certificate pinner. Timeouts, interceptors and the cache are not part of the address, so a client that differs only in those reuses everything. A derived client with a different `Dns` or protocol list still shares the pool object, but opens its own connections inside it. ## On Android in practice - **Build it once at app scope**, as a lazily created property of the `Application` or an app-wide singleton from whatever dependency injection the app uses, and build every Retrofit instance on top of it. - **Derive per-purpose clients** for the few call paths that need it: a longer read timeout for large downloads, an extra interceptor for one backend. - **Prefer per-call overrides when a whole client is overkill**: `call.timeout()` sets one call's overall deadline, and an application interceptor can shorten a timeout for a single request. - **Shutting down is not necessary.** Idle threads and connections are released on their own. An app that must release resources aggressively can call `dispatcher.executorService.shutdown()` (future calls are then rejected), `connectionPool.evictAll()` and `cache?.close()`; calls made against a closed cache crash. The interview answer in one line: the client is a resource holder, so you share one and derive variants from it rather than constructing new ones.

  • Do you need to shut down a shared OkHttpClient when the app goes to the background?
    No. OkHttp releases idle resources on its own: the default dispatcher's threads exit after 60 seconds idle and the pool evicts connections after 5 minutes unused. If an app must free them immediately, it can shut down `dispatcher.executorService` (which makes the client reject later calls), call `connectionPool.evictAll()`, and close the cache, accepting that a closed cache makes later calls crash.
  • A client derived with newBuilder() sets its own Dns implementation. Does it reuse the shared client's open connections?
    It shares the same `ConnectionPool` object, but not those connections. A pooled connection is reused only when the request's address matches, and the address includes the client's `Dns`, proxy settings, protocols, connection specs and TLS configuration. A different `Dns` makes a different address, so the derived client opens its own connections inside the shared pool. A derived client that changes only timeouts reuses them.
  • Can two OkHttpClients use one Cache, and can two Cache objects use one directory?
    One `Cache` instance may be shared by several clients, which is exactly what `newBuilder()` does by keeping the same instance. Two `Cache` objects must never point at the same directory: the cache needs exclusive access to it, and two owners can corrupt it or fail at runtime.

  • Create a new OkHttpClient per request so settings never leak between calls.
  • newBuilder() copies the connection pool, so a derived client starts with no warm connections.
  • All OkHttpClient instances share one global connection pool automatically.
  • A shared OkHttpClient must be shut down explicitly or the app leaks threads.
  • Adding an interceptor to a derived builder also adds it to the original client.