Avoid giving the result of loads a non-null type.

#1805

caffeine/src/main/java/com/github/benmanes/caffeine/cache/AsyncCache.java

@@ -23,7 +23,9 @@
 import java.util.function.BiFunction;
 import java.util.function.Function;
 
+import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -71,7 +73,9 @@ public interface AsyncCache<K, V> {
    * @return the current (existing or computed) future value associated with the specified key
    * @throws NullPointerException if the specified key or mappingFunction is null
    */
-  CompletableFuture<V> get(K key, Function<? super K, ? extends V> mappingFunction);
+  @NullUnmarked
+  @NonNull CompletableFuture<V> get(
+      @NonNull K key, @NonNull Function<? super @NonNull K, ? extends @Nullable V> mappingFunction);
 
   /**
    * Returns the future associated with the {@code key} in this cache, obtaining that value from
@@ -96,8 +100,15 @@ public interface AsyncCache<K, V> {
    * @throws RuntimeException or Error if the mappingFunction does when constructing the future,
    *         in which case the mapping is left unestablished
    */
-  CompletableFuture<V> get(K key, BiFunction<? super K, ? super Executor,
-      ? extends CompletableFuture<? extends V>> mappingFunction);
+  @NullUnmarked
+  @NonNull CompletableFuture<V> get(
+      @NonNull K key,
+      @NonNull
+          BiFunction<
+              ? super @NonNull K,
+              ? super @NonNull Executor,
+              ? extends @NonNull CompletableFuture<? extends @Nullable V>>
+          mappingFunction);
 
   /**
    * Returns the future of a map of the values associated with the {@code keys}, creating or
@@ -170,7 +181,7 @@ CompletableFuture<Map<K, V>> getAll(Iterable<? extends K> keys,
    * @param valueFuture the value to be associated with the specified key
    * @throws NullPointerException if the specified key or value is null
    */
-  void put(K key, CompletableFuture<? extends V> valueFuture);
+  void put(K key, CompletableFuture<? extends @Nullable V> valueFuture);
 
   /**
    * Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to
@@ -187,7 +198,8 @@ CompletableFuture<Map<K, V>> getAll(Iterable<? extends K> keys,
    *
    * @return a thread-safe view of this cache supporting all of the optional {@link Map} operations
    */
-  ConcurrentMap<K, CompletableFuture<V>> asMap();
+  @NullUnmarked
+  @NonNull ConcurrentMap<@NonNull K, @NonNull CompletableFuture<V>> asMap();
 
   /**
    * Returns a view of the entries stored in this cache as a synchronous {@link Cache}. A mapping is

caffeine/src/main/java/com/github/benmanes/caffeine/cache/AsyncCacheLoader.java

@@ -25,6 +25,7 @@
 import java.util.function.Function;
 
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Computes or retrieves values asynchronously based on a key, for use in populating a
@@ -62,7 +63,7 @@ public interface AsyncCacheLoader<K, V> {
    *         treated like any other {@code Exception} in all respects except that, when it is
    *         caught, the thread's interrupt status is set
    */
-  CompletableFuture<? extends V> asyncLoad(K key, Executor executor) throws Exception;
+  CompletableFuture<? extends @Nullable V> asyncLoad(K key, Executor executor) throws Exception;
 
   /**
    * Asynchronously computes or retrieves the values corresponding to {@code keys}. This method is
@@ -114,7 +115,7 @@ public interface AsyncCacheLoader<K, V> {
    *         treated like any other {@code Exception} in all respects except that, when it is
    *         caught, the thread's interrupt status is set
    */
-  default CompletableFuture<? extends V> asyncReload(
+  default CompletableFuture<? extends @Nullable V> asyncReload(
       K key, V oldValue, Executor executor) throws Exception {
     return asyncLoad(key, executor);
   }

caffeine/src/main/java/com/github/benmanes/caffeine/cache/AsyncLoadingCache.java

@@ -18,7 +18,9 @@
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 
+import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
 
 /**
  * A semi-persistent mapping from keys to values. Values are automatically loaded by the cache
@@ -50,7 +52,8 @@ public interface AsyncLoadingCache<K, V> extends AsyncCache<K, V> {
    * @throws RuntimeException or Error if the {@link AsyncCacheLoader} does when constructing the
    *         future, in which case the mapping is left unestablished
    */
-  CompletableFuture<V> get(K key);
+  @NullUnmarked
+  @NonNull CompletableFuture<V> get(@NonNull K key);
 
   /**
    * Returns the future of a map of the values associated with {@code keys}, creating or retrieving

caffeine/src/main/java/com/github/benmanes/caffeine/cache/Cache.java

@@ -20,7 +20,9 @@
 import java.util.concurrent.ConcurrentMap;
 import java.util.function.Function;
 
+import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
 import org.jspecify.annotations.Nullable;
 
 import com.github.benmanes.caffeine.cache.stats.CacheStats;
@@ -77,7 +79,8 @@ public interface Cache<K, V> {
    * @throws RuntimeException or Error if the mappingFunction does so, in which case the mapping is
    *         left unestablished
    */
-  V get(K key, Function<? super K, ? extends V> mappingFunction);
+  @NullUnmarked
+  V get(@NonNull K key, Function<? super @NonNull K, ? extends @Nullable V> mappingFunction);
 
   /**
    * Returns a map of the values associated with the {@code keys} in this cache. The returned map

caffeine/src/main/java/com/github/benmanes/caffeine/cache/CacheLoader.java

@@ -101,7 +101,7 @@ public interface CacheLoader<K, V> extends AsyncCacheLoader<K, V> {
    * @return the future value associated with {@code key}
    */
   @Override
-  default CompletableFuture<? extends V> asyncLoad(K key, Executor executor) throws Exception {
+  default CompletableFuture<? extends @Nullable V> asyncLoad(K key, Executor executor) throws Exception {
     requireNonNull(key);
     requireNonNull(executor);
     return CompletableFuture.supplyAsync(() -> {
@@ -193,7 +193,7 @@ default CompletableFuture<? extends V> asyncLoad(K key, Executor executor) throw
    *         {@code null} if the mapping is to be removed
    */
   @Override
-  default CompletableFuture<? extends V> asyncReload(
+  default CompletableFuture<? extends @Nullable V> asyncReload(
       K key, V oldValue, Executor executor) throws Exception {
     requireNonNull(key);
     requireNonNull(executor);

caffeine/src/main/java/com/github/benmanes/caffeine/cache/LoadingCache.java

@@ -19,7 +19,9 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionException;
 
+import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 
@@ -62,7 +64,8 @@ public interface LoadingCache<K, V> extends Cache<K, V> {
    * @throws RuntimeException or Error if the {@link CacheLoader} does so, in which case the mapping
    *         is left unestablished
    */
-  V get(K key);
+  @NullUnmarked
+  V get(@NonNull K key);
 
   /**
    * Returns a map of the values associated with the {@code keys}, creating or retrieving those
@@ -110,7 +113,8 @@ public interface LoadingCache<K, V> extends Cache<K, V> {
    * @throws NullPointerException if the specified key is null
    */
   @CanIgnoreReturnValue
-  CompletableFuture<V> refresh(K key);
+  @NullUnmarked
+  @NonNull CompletableFuture<V> refresh(@NonNull K key);
 
   /**
    * Loads a new value for each {@code key}, asynchronously. While the new value is loading the