Add caching annotation support for CompletableFuture and reactive return values

Includes CompletableFuture-based retrieve operations on Spring's Cache interface.
Includes support for retrieve operations on CaffeineCache and ConcurrentMapCache.
Includes async cache mode option on CaffeineCacheManager.

Closes gh-17559
Closes gh-17920
Closes gh-30122

Author: jhoeller

spring-context-support/src/main/java/org/springframework/cache/caffeine/CaffeineCache.java

@@ -17,8 +17,11 @@
 package org.springframework.cache.caffeine;
 
 import java.util.concurrent.Callable;
+import java.util.concurrent.CompletableFuture;
 import java.util.function.Function;
+import java.util.function.Supplier;
 
+import com.github.benmanes.caffeine.cache.AsyncCache;
 import com.github.benmanes.caffeine.cache.LoadingCache;
 
 import org.springframework.cache.support.AbstractValueAdaptingCache;
@@ -29,7 +32,11 @@
  * Spring {@link org.springframework.cache.Cache} adapter implementation
  * on top of a Caffeine {@link com.github.benmanes.caffeine.cache.Cache} instance.
  *
- * <p>Requires Caffeine 2.1 or higher.
+ * <p>Supports the {@link #retrieve(Object)} and {@link #retrieve(Object, Supplier)}
+ * operations through Caffeine's {@link AsyncCache}, when provided via the
+ * {@link #CaffeineCache(String, AsyncCache, boolean)} constructor.
+ *
+ * <p>Requires Caffeine 3.0 or higher, as of Spring Framework 6.1.
  *
  * @author Ben Manes
  * @author Juergen Hoeller
@@ -43,6 +50,9 @@ public class CaffeineCache extends AbstractValueAdaptingCache {
 
 	private final com.github.benmanes.caffeine.cache.Cache<Object, Object> cache;
 
+	@Nullable
+	private AsyncCache<Object, Object> asyncCache;
+
 
 	/**
 	 * Create a {@link CaffeineCache} instance with the specified name and the
@@ -72,24 +82,74 @@ public CaffeineCache(String name, com.github.benmanes.caffeine.cache.Cache<Objec
 		this.cache = cache;
 	}
 
+	/**
+	 * Create a {@link CaffeineCache} instance with the specified name and the
+	 * given internal {@link AsyncCache} to use.
+	 * @param name the name of the cache
+	 * @param cache the backing Caffeine Cache instance
+	 * @param allowNullValues whether to accept and convert {@code null}
+	 * values for this cache
+	 * @since 6.1
+	 */
+	public CaffeineCache(String name, AsyncCache<Object, Object> cache, boolean allowNullValues) {
+		super(allowNullValues);
+		Assert.notNull(name, "Name must not be null");
+		Assert.notNull(cache, "Cache must not be null");
+		this.name = name;
+		this.cache = cache.synchronous();
+		this.asyncCache = cache;
+	}
+
 
 	@Override
 	public final String getName() {
 		return this.name;
 	}
 
+	/**
+	 * Return the internal Caffeine Cache
+	 * (possibly an adapter on top of an {@link #getAsyncCache()}).
+	 */
 	@Override
 	public final com.github.benmanes.caffeine.cache.Cache<Object, Object> getNativeCache() {
 		return this.cache;
 	}
 
+	/**
+	 * Return the internal Caffeine AsyncCache.
+	 * @throws IllegalStateException if no AsyncCache is available
+	 * @see #CaffeineCache(String, AsyncCache, boolean)
+	 * @see CaffeineCacheManager#setAsyncCacheMode
+	 */
+	public final AsyncCache<Object, Object> getAsyncCache() {
+		Assert.state(this.asyncCache != null,
+				"No Caffeine AsyncCache available: set CaffeineCacheManager.setAsyncCacheMode(true)");
+		return this.asyncCache;
+	}
+
 	@SuppressWarnings("unchecked")
 	@Override
 	@Nullable
 	public <T> T get(Object key, final Callable<T> valueLoader) {
 		return (T) fromStoreValue(this.cache.get(key, new LoadFunction(valueLoader)));
 	}
 
+	@Override
+	@Nullable
+	public CompletableFuture<?> retrieve(Object key) {
+		CompletableFuture<?> result = getAsyncCache().getIfPresent(key);
+		if (result != null && isAllowNullValues()) {
+			result = result.handle((value, ex) -> fromStoreValue(value));
+		}
+		return result;
+	}
+
+	@SuppressWarnings("unchecked")
+	@Override
+	public <T> CompletableFuture<T> retrieve(Object key, Supplier<CompletableFuture<T>> valueLoader) {
+		return (CompletableFuture<T>) getAsyncCache().get(key, (k, e) -> valueLoader.get());
+	}
+
 	@Override
 	@Nullable
 	protected Object lookup(Object key) {

spring-context-support/src/main/java/org/springframework/cache/caffeine/CaffeineCacheManager.java

@@ -22,7 +22,10 @@
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.function.Supplier;
 
+import com.github.benmanes.caffeine.cache.AsyncCache;
+import com.github.benmanes.caffeine.cache.AsyncCacheLoader;
 import com.github.benmanes.caffeine.cache.CacheLoader;
 import com.github.benmanes.caffeine.cache.Caffeine;
 import com.github.benmanes.caffeine.cache.CaffeineSpec;
@@ -45,7 +48,11 @@
  * A {@link CaffeineSpec}-compliant expression value can also be applied
  * via the {@link #setCacheSpecification "cacheSpecification"} bean property.
  *
- * <p>Requires Caffeine 2.1 or higher.
+ * <p>Supports the {@link Cache#retrieve(Object)} and
+ * {@link Cache#retrieve(Object, Supplier)} operations through Caffeine's
+ * {@link AsyncCache}, when configured via {@link #setAsyncCacheMode}.
+ *
+ * <p>Requires Caffeine 3.0 or higher, as of Spring Framework 6.1.
  *
  * @author Ben Manes
  * @author Juergen Hoeller
@@ -54,13 +61,18 @@
  * @author Brian Clozel
  * @since 4.3
  * @see CaffeineCache
+ * @see #setCaffeineSpec
+ * @see #setCacheSpecification
+ * @see #setAsyncCacheMode
  */
 public class CaffeineCacheManager implements CacheManager {
 
 	private Caffeine<Object, Object> cacheBuilder = Caffeine.newBuilder();
 
 	@Nullable
-	private CacheLoader<Object, Object> cacheLoader;
+	private AsyncCacheLoader<Object, Object> cacheLoader;
+
+	private boolean asyncCacheMode = false;
 
 	private boolean allowNullValues = true;
 
@@ -110,7 +122,7 @@ public void setCacheNames(@Nullable Collection<String> cacheNames) {
 	 * Set the Caffeine to use for building each individual
 	 * {@link CaffeineCache} instance.
 	 * @see #createNativeCaffeineCache
-	 * @see com.github.benmanes.caffeine.cache.Caffeine#build()
+	 * @see Caffeine#build()
 	 */
 	public void setCaffeine(Caffeine<Object, Object> caffeine) {
 		Assert.notNull(caffeine, "Caffeine must not be null");
@@ -121,7 +133,7 @@ public void setCaffeine(Caffeine<Object, Object> caffeine) {
 	 * Set the {@link CaffeineSpec} to use for building each individual
 	 * {@link CaffeineCache} instance.
 	 * @see #createNativeCaffeineCache
-	 * @see com.github.benmanes.caffeine.cache.Caffeine#from(CaffeineSpec)
+	 * @see Caffeine#from(CaffeineSpec)
 	 */
 	public void setCaffeineSpec(CaffeineSpec caffeineSpec) {
 		doSetCaffeine(Caffeine.from(caffeineSpec));
@@ -132,7 +144,7 @@ public void setCaffeineSpec(CaffeineSpec caffeineSpec) {
 	 * individual {@link CaffeineCache} instance. The given value needs to
 	 * comply with Caffeine's {@link CaffeineSpec} (see its javadoc).
 	 * @see #createNativeCaffeineCache
-	 * @see com.github.benmanes.caffeine.cache.Caffeine#from(String)
+	 * @see Caffeine#from(String)
 	 */
 	public void setCacheSpecification(String cacheSpecification) {
 		doSetCaffeine(Caffeine.from(cacheSpecification));
@@ -149,7 +161,7 @@ private void doSetCaffeine(Caffeine<Object, Object> cacheBuilder) {
 	 * Set the Caffeine CacheLoader to use for building each individual
 	 * {@link CaffeineCache} instance, turning it into a LoadingCache.
 	 * @see #createNativeCaffeineCache
-	 * @see com.github.benmanes.caffeine.cache.Caffeine#build(CacheLoader)
+	 * @see Caffeine#build(CacheLoader)
 	 * @see com.github.benmanes.caffeine.cache.LoadingCache
 	 */
 	public void setCacheLoader(CacheLoader<Object, Object> cacheLoader) {
@@ -159,6 +171,45 @@ public void setCacheLoader(CacheLoader<Object, Object> cacheLoader) {
 		}
 	}
 
+	/**
+	 * Set the Caffeine AsyncCacheLoader to use for building each individual
+	 * {@link CaffeineCache} instance, turning it into a LoadingCache.
+	 * <p>This implicitly switches the {@link #setAsyncCacheMode "asyncCacheMode"}
+	 * flag to {@code true}.
+	 * @since 6.1
+	 * @see #createAsyncCaffeineCache
+	 * @see Caffeine#buildAsync(AsyncCacheLoader)
+	 * @see com.github.benmanes.caffeine.cache.LoadingCache
+	 */
+	public void setAsyncCacheLoader(AsyncCacheLoader<Object, Object> cacheLoader) {
+		if (!ObjectUtils.nullSafeEquals(this.cacheLoader, cacheLoader)) {
+			this.cacheLoader = cacheLoader;
+			this.asyncCacheMode = true;
+			refreshCommonCaches();
+		}
+	}
+
+	/**
+	 * Set the common cache type that this cache manager builds to async.
+	 * This applies to {@link #setCacheNames} as well as on-demand caches.
+	 * <p>Individual cache registrations (such as {@link #registerCustomCache(String, AsyncCache)}
+	 * and {@link #registerCustomCache(String, com.github.benmanes.caffeine.cache.Cache)}
+	 * are not dependent on this setting.
+	 * <p>By default, this cache manager builds regular native Caffeine caches.
+	 * To switch to async caches which can also be used through the synchronous API
+	 * but come with support for {@code Cache#retrieve}, set this flag to {@code true}.
+	 * @since 6.1
+	 * @see Caffeine#buildAsync()
+	 * @see Cache#retrieve(Object)
+	 * @see Cache#retrieve(Object, Supplier)
+	 */
+	public void setAsyncCacheMode(boolean asyncCacheMode) {
+		if (this.asyncCacheMode != asyncCacheMode) {
+			this.asyncCacheMode = asyncCacheMode;
+			refreshCommonCaches();
+		}
+	}
+
 	/**
 	 * Specify whether to accept and convert {@code null} values for all caches
 	 * in this cache manager.
@@ -211,27 +262,62 @@ public Cache getCache(String name) {
  	 * @param name the name of the cache
 	 * @param cache the custom Caffeine Cache instance to register
 	 * @since 5.2.8
-	 * @see #adaptCaffeineCache
+	 * @see #adaptCaffeineCache(String, com.github.benmanes.caffeine.cache.Cache)
 	 */
 	public void registerCustomCache(String name, com.github.benmanes.caffeine.cache.Cache<Object, Object> cache) {
 		this.customCacheNames.add(name);
 		this.cacheMap.put(name, adaptCaffeineCache(name, cache));
 	}
 
+	/**
+	 * Register the given Caffeine AsyncCache instance with this cache manager,
+	 * adapting it to Spring's cache API for exposure through {@link #getCache}.
+	 * Any number of such custom caches may be registered side by side.
+	 * <p>This allows for custom settings per cache (as opposed to all caches
+	 * sharing the common settings in the cache manager's configuration) and
+	 * is typically used with the Caffeine builder API:
+	 * {@code registerCustomCache("myCache", Caffeine.newBuilder().maximumSize(10).build())}
+	 * <p>Note that any other caches, whether statically specified through
+	 * {@link #setCacheNames} or dynamically built on demand, still operate
+	 * with the common settings in the cache manager's configuration.
+	 * @param name the name of the cache
+	 * @param cache the custom Caffeine Cache instance to register
+	 * @since 6.1
+	 * @see #adaptCaffeineCache(String, AsyncCache)
+	 */
+	public void registerCustomCache(String name, AsyncCache<Object, Object> cache) {
+		this.customCacheNames.add(name);
+		this.cacheMap.put(name, adaptCaffeineCache(name, cache));
+	}
+
 	/**
 	 * Adapt the given new native Caffeine Cache instance to Spring's {@link Cache}
 	 * abstraction for the specified cache name.
 	 * @param name the name of the cache
 	 * @param cache the native Caffeine Cache instance
 	 * @return the Spring CaffeineCache adapter (or a decorator thereof)
 	 * @since 5.2.8
-	 * @see CaffeineCache
+	 * @see CaffeineCache#CaffeineCache(String, com.github.benmanes.caffeine.cache.Cache, boolean)
 	 * @see #isAllowNullValues()
 	 */
 	protected Cache adaptCaffeineCache(String name, com.github.benmanes.caffeine.cache.Cache<Object, Object> cache) {
 		return new CaffeineCache(name, cache, isAllowNullValues());
 	}
 
+	/**
+	 * Adapt the given new Caffeine AsyncCache instance to Spring's {@link Cache}
+	 * abstraction for the specified cache name.
+	 * @param name the name of the cache
+	 * @param cache the Caffeine AsyncCache instance
+	 * @return the Spring CaffeineCache adapter (or a decorator thereof)
+	 * @since 6.1
+	 * @see CaffeineCache#CaffeineCache(String, AsyncCache, boolean)
+	 * @see #isAllowNullValues()
+	 */
+	protected Cache adaptCaffeineCache(String name, AsyncCache<Object, Object> cache) {
+		return new CaffeineCache(name, cache, isAllowNullValues());
+	}
+
 	/**
 	 * Build a common {@link CaffeineCache} instance for the specified cache name,
 	 * using the common Caffeine configuration specified on this cache manager.
@@ -244,7 +330,8 @@ protected Cache adaptCaffeineCache(String name, com.github.benmanes.caffeine.cac
 	 * @see #createNativeCaffeineCache
 	 */
 	protected Cache createCaffeineCache(String name) {
-		return adaptCaffeineCache(name, createNativeCaffeineCache(name));
+		return (this.asyncCacheMode ? adaptCaffeineCache(name, createAsyncCaffeineCache(name)) :
+				adaptCaffeineCache(name, createNativeCaffeineCache(name)));
 	}
 
 	/**
@@ -255,7 +342,29 @@ protected Cache createCaffeineCache(String name) {
 	 * @see #createCaffeineCache
 	 */
 	protected com.github.benmanes.caffeine.cache.Cache<Object, Object> createNativeCaffeineCache(String name) {
-		return (this.cacheLoader != null ? this.cacheBuilder.build(this.cacheLoader) : this.cacheBuilder.build());
+		if (this.cacheLoader != null) {
+			if (this.cacheLoader instanceof CacheLoader<Object, Object> regularCacheLoader) {
+				return this.cacheBuilder.build(regularCacheLoader);
+			}
+			else {
+				throw new IllegalStateException(
+						"Cannot create regular Caffeine Cache with async-only cache loader: " + this.cacheLoader);
+			}
+		}
+		return this.cacheBuilder.build();
+	}
+
+	/**
+	 * Build a common Caffeine AsyncCache instance for the specified cache name,
+	 * using the common Caffeine configuration specified on this cache manager.
+	 * @param name the name of the cache
+	 * @return the Caffeine AsyncCache instance
+	 * @since 6.1
+	 * @see #createCaffeineCache
+	 */
+	protected AsyncCache<Object, Object> createAsyncCaffeineCache(String name) {
+		return (this.cacheLoader != null ? this.cacheBuilder.buildAsync(this.cacheLoader) :
+				this.cacheBuilder.buildAsync());
 	}
 
 	/**

spring-context-support/src/main/java/org/springframework/cache/transaction/TransactionAwareCacheDecorator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2023 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,6 +17,8 @@
 package org.springframework.cache.transaction;
 
 import java.util.concurrent.Callable;
+import java.util.concurrent.CompletableFuture;
+import java.util.function.Supplier;
 
 import org.springframework.cache.Cache;
 import org.springframework.lang.Nullable;
@@ -91,6 +93,17 @@ public <T> T get(Object key, Callable<T> valueLoader) {
 		return this.targetCache.get(key, valueLoader);
 	}
 
+	@Override
+	@Nullable
+	public CompletableFuture<?> retrieve(Object key) {
+		return this.targetCache.retrieve(key);
+	}
+
+	@Override
+	public <T> CompletableFuture<T> retrieve(Object key, Supplier<CompletableFuture<T>> valueLoader) {
+		return this.targetCache.retrieve(key, valueLoader);
+	}
+
 	@Override
 	public void put(final Object key, @Nullable final Object value) {
 		if (TransactionSynchronizationManager.isSynchronizationActive()) {