/*
 * Copyright 2014 Ben Manes. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.github.benmanes.caffeine.cache;

import static java.util.Objects.requireNonNull;

import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executor;

import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;

/**
 * Computes or retrieves values, based on a key, for use in populating a {@link LoadingCache}.
 * <p>
 * Most implementations will only need to implement {@link #load}. Other methods may be
 * overridden as desired.
 * <p>
 * Usage example:
 * <pre>{@code
 *   CacheLoader<Key, Graph> loader = key -> createExpensiveGraph(key);
 *   LoadingCache<Key, Graph> cache = Caffeine.newBuilder().build(loader);
 * }</pre>
 *
 * @author ben.manes@gmail.com (Ben Manes)
 */
@FunctionalInterface
public interface CacheLoader<K, V> {

  /**
   * Computes or retrieves the value corresponding to {@code key}.
   *
   * @param key the non-null key whose value should be loaded
   * @return the value associated with {@code key}
   */
  @CheckForNull
  V load(@Nonnull K key);

  /**
   * Computes or retrieves the values corresponding to {@code keys}. This method is called by
   * {@link LoadingCache#getAll}.
   * <p>
   * If the returned map doesn't contain all requested {@code keys} then the entries it does contain
   * will be cached, but {@code getAll} will throw an exception. If the returned map contains extra
   * keys not present in {@code keys} then all returned entries will be cached, but only the entries
   * for {@code keys} will be returned from {@code getAll}.
   * <p>
   * This method should be overriden when bulk retrieval is significantly more efficient than many
   * individual lookups. Note that {@link LoadingCache#getAll} will defer to individual calls to
   * {@link LoadingCache#get} if this method is not overriden.
   *
   * @param keys the unique, non-null keys whose values should be loaded
   * @return a map from each key in {@code keys} to the value associated with that key; <b>may not
   *         contain null values</b>
   * @throws UnsupportedOperationException if bulk loading is not implemented
   */
  @Nonnull
  default Map<K, V> loadAll(@Nonnull Iterable<? extends K> keys) {
    throw new UnsupportedOperationException();
  }

  /**
   * Asynchronously computes or retrieves the value corresponding to {@code key}.
   *
   * @param key the non-null key whose value should be loaded
   * @param executor the executor that asynchronously loads the entry
   * @return the future value associated with {@code key}
   */
  @Nonnull
  default CompletableFuture<V> asyncLoad(@Nonnull K key, @Nonnull Executor executor) {
    requireNonNull(key);
    requireNonNull(executor);
    return CompletableFuture.supplyAsync(() -> load(key), executor);
  }

  /**
   * Asynchronously computes or retrieves the values corresponding to {@code keys}. This method is
   * called by {@link AsyncLoadingCache#getAll}.
   * <p>
   * If the returned map doesn't contain all requested {@code keys} then the entries it does contain
   * will be cached, but {@code getAll} will throw an exception. If the returned map contains extra
   * keys not present in {@code keys} then all returned entries will be cached, but only the entries
   * for {@code keys} will be returned from {@code getAll}.
   * <p>
   * This method should be overridden when bulk retrieval is significantly more efficient than many
   * individual lookups. Note that {@link AsyncLoadingCache#getAll} will defer to individual calls
   * to {@link AsyncLoadingCache#get} if this method is not overridden.
   *
   * @param keys the unique, non-null keys whose values should be loaded
   * @param executor the executor that with asynchronously loads the entries
   * @return a future containing the map from each key in {@code keys} to the value associated with
   *         that key; <b>may not contain null values</b>
   * @throws UnsupportedOperationException if bulk loading is not implemented
   */
  @Nonnull
  default CompletableFuture<Map<K, V>> asyncLoadAll(
      Iterable<? extends K> keys, @Nonnull Executor executor) {
    requireNonNull(keys);
    requireNonNull(executor);
    return CompletableFuture.supplyAsync(() -> loadAll(keys), executor);
  }

  /**
   * Computes or retrieves a replacement value corresponding to an already-cached {@code key}. This
   * method is called when an existing cache entry is refreshed by
   * {@link Caffeine#refreshAfterWrite}, or through a call to {@link LoadingCache#refresh}.
   * <p>
   * <b>Note:</b> <i>all exceptions thrown by this method will be logged and then swallowed</i>.
   *
   * @param key the non-null key whose value should be loaded
   * @param oldValue the non-null old value corresponding to {@code key}
   * @return the new value associated with {@code key}, or null if none
   * @throws RuntimeException or Error, in which case the mapping is unchanged
   */
  @CheckForNull
  default V reload(@Nonnull K key, @Nonnull V oldValue) {
    return load(key);
  }
}

@@ -979,18 +979,50 @@
 ngCache%7D
+ or%0A * %7B@link AsyncLoadingCache%7D
 .%0A
-
  * %3Cp%3E%0A 
@@ -1623,32 +1623,61 @@
 with %7B@code key%7D
+ or %7B@code null%7D if not found
 %0A   */%0A  @CheckF
@@ -1965,37 +1965,32 @@
 * will be cached
-, but
  %7B@code getAll%7D 
@@ -1994,34 +1994,42 @@
 l%7D will 
-throw an exception
+return the partial results
 . If the
@@ -2046,35 +2046,35 @@
 map contains
+%0A   *
  extra
-%0A   *
  keys not pr
@@ -2145,32 +2145,37 @@
 but only the
+%0A   *
  entries
 %0A   * for %7B@
@@ -2154,37 +2154,32 @@
 the%0A   * entries
-%0A   *
  for %7B@code keys
@@ -3713,21 +3713,16 @@
 e cached
-, but
  %7B@code 
@@ -3738,26 +3738,34 @@
 ill 
-throw an exception
+return the partial results
 . If
@@ -3794,19 +3794,19 @@
 ains
+%0A   *
  extra
-%0A   *
  key
@@ -3885,32 +3885,37 @@
 but only the
+%0A   *
  entries
 %0A   * for %7B@
@@ -3902,21 +3902,16 @@
  entries
-%0A   *
  for %7B@c
@@ -5002,17 +5002,122 @@
 y%7D. 
-This%0A   *
+If%0A   * the replacement value is not found then the mapping will be removed if %7B@code null%7D is%0A   * returned. This
  met
@@ -5576,20 +5576,65 @@
  or 
+%7B@code 
 null
+%7D
  if 
-none
+the mapping is to be%0A   *         removed
 %0A   

Fix CacheLoader JavaDoc