Caching
=======

OkHttp implements an optional, off by default, Cache. OkHttp aims for RFC correct and
pragmatic caching behaviour, following common real-world browser like Firefox/Chrome and 
server behaviour when ambiguous.

# Basic Usage

```kotlin
  private val client: OkHttpClient = OkHttpClient.Builder()
      .cache(Cache(
          directory = File(application.cacheDir, "http_cache"),
          // $0.05 worth of phone storage in 2020

 */
// These benchmarks allocate a lot of data so use a large heap
@VmOptions({"-Xms12g", "-Xmx12g", "-d64"})
public class ByteSourceAsCharSourceReadBenchmark {
  enum ReadStrategy {
    TO_BYTE_ARRAY_NEW_STRING {
      @Override
      String read(ByteSource byteSource, Charset cs) throws IOException {
        return new String(byteSource.read(), cs);
      }
    },

     * whether the DependencyCoordinates is used in dependency management, in which case it means the scope is not
     * explicitly managed by this managed dependency, or as a real dependency, in which case, the scope
     * will default to {@link #COMPILE}.
     */
    UNDEFINED("", false),

    /**
     * Compile only.
     */
    COMPILE_ONLY("compile-only", false),

    /**

 * MoreExecutors#listeningDecorator(ExecutorService)}.
 *
 * @author Chris Povirk
 * @since 10.0
 */
@DoNotMock(
    "Use TestingExecutors.sameThreadScheduledExecutor, or wrap a real Executor from "
        + "java.util.concurrent.Executors with MoreExecutors.listeningDecorator")
@GwtIncompatible
@ElementTypesAreNonnullByDefault
public interface ListeningExecutorService extends ExecutorService {
  /**

///

/// info

In this example we use invented custom headers `X-Key` and `X-Token`.

But in real cases, when implementing security, you would get more benefits from using the integrated [Security utilities (the next chapter)](../security/index.md){.internal-link target=_blank}.

///

## Dependencies errors and return values

import okhttp3.internal.http2.Http2.formatFlags
import okhttp3.internal.http2.Http2.frameLog
import okhttp3.internal.http2.Http2.frameLogWindowUpdate
import org.junit.jupiter.api.Test

class FrameLogTest {
  /** Real stream traffic applied to the log format.  */
  @Test
  fun exampleStream() {
    assertThat(frameLog(false, 0, 5, TYPE_SETTINGS, FLAG_NONE))
      .isEqualTo(">> 0x00000000     5 SETTINGS      ")

    suite.addTestSuite(MutableClassToInstanceMapTest.class);

    suite.addTest(
        MapTestSuiteBuilder.using(
                new TestClassToInstanceMapGenerator() {
                  // Other tests will verify what real, warning-free usage looks like
                  // but here we have to do some serious fudging
                  @Override
                  @SuppressWarnings({"unchecked", "rawtypes"})

     * Windows under Java 8, at least as of this writing.
     *
     * Under Windows in particular, we want to test that:
     *
     * - Under Java 9+, createTempDir() succeeds because it can look up the *real* username, rather
     * than relying on the one from the system property.
     *
     * - Under Java 8, createTempDir() fails because it falls back to the bogus username from the
     * system property.
     */

input size | lib | MB/s | Allocated
--- | --- | --- | ---
regular | standard | 97 | 3.6MB
regular | jstream | 175 | 2.1MB
large | standard | 92 | 305MB
large | jstream | 404 | 69MB

In a real world scenario, including initialization and reader overhead from varying blob sizes, performance can be expected as below:

   * next} field is lazily initialized. The type of that field would be {@code @Nullable T}, and the
   * code would be responsible for populating a "real" {@code T} (which might still be the value
   * {@code null}!) before returning it to callers. Depending on how the code is structured, a
   * nullness analysis might not understand that the field has been populated. To avoid that problem