Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add caching annotation support for CompletableFuture and reactive return values

Browse Source 
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
This commit is contained in:
Juergen Hoeller
2023-07-21 20:27:23 +02:00
parent d65d285378
commit f99faac073
9 changed files with 952 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
spring-context-support/src/main/java/org/springframework/cache/caffeine/CaffeineCache.java vendored
View File

@@ -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 @@ import org.springframework.util.Assert;
* 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,17 +82,51 @@ public class CaffeineCache extends AbstractValueAdaptingCache {
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
@@ -90,6 +134,22 @@ public class CaffeineCache extends AbstractValueAdaptingCache {
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) {

129
spring-context-support/src/main/java/org/springframework/cache/caffeine/CaffeineCacheManager.java vendored
View File

@@ -22,7 +22,10 @@ import java.util.Collections;
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 @@ import org.springframework.util.ObjectUtils;
* 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 @@ import org.springframework.util.ObjectUtils;
* @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 class CaffeineCacheManager implements CacheManager {
* 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 class CaffeineCacheManager implements CacheManager {
* 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 class CaffeineCacheManager implements CacheManager {
* 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 @@ public class CaffeineCacheManager implements CacheManager {
* 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 class CaffeineCacheManager implements CacheManager {
}
}
/**
* 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,13 +262,34 @@ public class CaffeineCacheManager implements CacheManager {
* @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.
@@ -225,13 +297,27 @@ public class CaffeineCacheManager implements CacheManager {
* @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 @@ public class CaffeineCacheManager implements CacheManager {
* @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 @@ public class CaffeineCacheManager implements CacheManager {
* @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());
}
/**

15
spring-context-support/src/main/java/org/springframework/cache/transaction/TransactionAwareCacheDecorator.java vendored
View File

@@ -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 class TransactionAwareCacheDecorator implements Cache {
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()) {

96
spring-context-support/src/test/java/org/springframework/cache/caffeine/CaffeineCacheManagerTests.java vendored
View File

@@ -16,6 +16,8 @@
package org.springframework.cache.caffeine;
import java.util.concurrent.CompletableFuture;
import com.github.benmanes.caffeine.cache.CacheLoader;
import com.github.benmanes.caffeine.cache.Caffeine;
import com.github.benmanes.caffeine.cache.CaffeineSpec;
@@ -26,6 +28,7 @@ import org.springframework.cache.CacheManager;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatIllegalArgumentException;
import static org.assertj.core.api.Assertions.assertThatIllegalStateException;
import static org.mockito.Mockito.mock;
/**
@@ -38,22 +41,26 @@ public class CaffeineCacheManagerTests {
@Test
public void testDynamicMode() {
CacheManager cm = new CaffeineCacheManager();
Cache cache1 = cm.getCache("c1");
boolean condition2 = cache1 instanceof CaffeineCache;
assertThat(condition2).isTrue();
assertThat(cache1).isInstanceOf(CaffeineCache.class);
Cache cache1again = cm.getCache("c1");
assertThat(cache1).isSameAs(cache1again);
Cache cache2 = cm.getCache("c2");
boolean condition1 = cache2 instanceof CaffeineCache;
assertThat(condition1).isTrue();
assertThat(cache2).isInstanceOf(CaffeineCache.class);
Cache cache2again = cm.getCache("c2");
assertThat(cache2).isSameAs(cache2again);
Cache cache3 = cm.getCache("c3");
boolean condition = cache3 instanceof CaffeineCache;
assertThat(condition).isTrue();
assertThat(cache3).isInstanceOf(CaffeineCache.class);
Cache cache3again = cm.getCache("c3");
assertThat(cache3).isSameAs(cache3again);
assertThatIllegalStateException().isThrownBy(() -> cache1.retrieve("key1"));
assertThatIllegalStateException().isThrownBy(() -> cache1.retrieve("key2"));
assertThatIllegalStateException().isThrownBy(() -> cache1.retrieve("key3"));
assertThatIllegalStateException().isThrownBy(() -> cache1.retrieve("key3",
() -> CompletableFuture.completedFuture("value3")));
cache1.put("key1", "value1");
assertThat(cache1.get("key1").get()).isEqualTo("value1");
cache1.put("key2", 2);
@@ -62,19 +69,23 @@ public class CaffeineCacheManagerTests {
assertThat(cache1.get("key3").get()).isNull();
cache1.evict("key3");
assertThat(cache1.get("key3")).isNull();
assertThat(cache1.get("key3", () -> "value3")).isEqualTo("value3");
assertThat(cache1.get("key3", () -> "value3")).isEqualTo("value3");
cache1.evict("key3");
assertThat(cache1.get("key3", () -> (String) null)).isNull();
assertThat(cache1.get("key3", () -> (String) null)).isNull();
}
@Test
public void testStaticMode() {
CaffeineCacheManager cm = new CaffeineCacheManager("c1", "c2");
Cache cache1 = cm.getCache("c1");
boolean condition3 = cache1 instanceof CaffeineCache;
assertThat(condition3).isTrue();
assertThat(cache1).isInstanceOf(CaffeineCache.class);
Cache cache1again = cm.getCache("c1");
assertThat(cache1).isSameAs(cache1again);
Cache cache2 = cm.getCache("c2");
boolean condition2 = cache2 instanceof CaffeineCache;
assertThat(condition2).isTrue();
assertThat(cache2).isInstanceOf(CaffeineCache.class);
Cache cache2again = cm.getCache("c2");
assertThat(cache2).isSameAs(cache2again);
Cache cache3 = cm.getCache("c3");
@@ -88,15 +99,24 @@ public class CaffeineCacheManagerTests {
assertThat(cache1.get("key3").get()).isNull();
cache1.evict("key3");
assertThat(cache1.get("key3")).isNull();
assertThat(cache1.get("key3", () -> "value3")).isEqualTo("value3");
assertThat(cache1.get("key3", () -> "value3")).isEqualTo("value3");
cache1.evict("key3");
assertThat(cache1.get("key3", () -> (String) null)).isNull();
assertThat(cache1.get("key3", () -> (String) null)).isNull();
assertThatIllegalStateException().isThrownBy(() -> cache1.retrieve("key1"));
assertThatIllegalStateException().isThrownBy(() -> cache1.retrieve("key2"));
assertThatIllegalStateException().isThrownBy(() -> cache1.retrieve("key3"));
assertThatIllegalStateException().isThrownBy(() -> cache1.retrieve("key3",
() -> CompletableFuture.completedFuture("value3")));
cm.setAllowNullValues(false);
Cache cache1x = cm.getCache("c1");
boolean condition1 = cache1x instanceof CaffeineCache;
assertThat(condition1).isTrue();
assertThat(cache1x).isInstanceOf(CaffeineCache.class);
assertThat(cache1x).isNotSameAs(cache1);
Cache cache2x = cm.getCache("c2");
boolean condition = cache2x instanceof CaffeineCache;
assertThat(condition).isTrue();
assertThat(cache2x).isInstanceOf(CaffeineCache.class);
assertThat(cache2x).isNotSameAs(cache2);
Cache cache3x = cm.getCache("c3");
assertThat(cache3x).isNull();
@@ -115,6 +135,52 @@ public class CaffeineCacheManagerTests {
assertThat(cache1y.get("key3")).isNull();
}
@Test
public void testAsyncMode() {
CaffeineCacheManager cm = new CaffeineCacheManager();
cm.setAsyncCacheMode(true);
Cache cache1 = cm.getCache("c1");
assertThat(cache1).isInstanceOf(CaffeineCache.class);
Cache cache1again = cm.getCache("c1");
assertThat(cache1).isSameAs(cache1again);
Cache cache2 = cm.getCache("c2");
assertThat(cache2).isInstanceOf(CaffeineCache.class);
Cache cache2again = cm.getCache("c2");
assertThat(cache2).isSameAs(cache2again);
Cache cache3 = cm.getCache("c3");
assertThat(cache3).isInstanceOf(CaffeineCache.class);
Cache cache3again = cm.getCache("c3");
assertThat(cache3).isSameAs(cache3again);
cache1.put("key1", "value1");
assertThat(cache1.get("key1").get()).isEqualTo("value1");
cache1.put("key2", 2);
assertThat(cache1.get("key2").get()).isEqualTo(2);
cache1.put("key3", null);
assertThat(cache1.get("key3").get()).isNull();
cache1.evict("key3");
assertThat(cache1.get("key3")).isNull();
assertThat(cache1.get("key3", () -> "value3")).isEqualTo("value3");
assertThat(cache1.get("key3", () -> "value3")).isEqualTo("value3");
cache1.evict("key3");
assertThat(cache1.get("key3", () -> (String) null)).isNull();
assertThat(cache1.get("key3", () -> (String) null)).isNull();
assertThat(cache1.retrieve("key1").join()).isEqualTo("value1");
assertThat(cache1.retrieve("key2").join()).isEqualTo(2);
assertThat(cache1.retrieve("key3").join()).isNull();
cache1.evict("key3");
assertThat(cache1.retrieve("key3")).isNull();
assertThat(cache1.retrieve("key3", () -> CompletableFuture.completedFuture("value3")).join())
.isEqualTo("value3");
assertThat(cache1.retrieve("key3", () -> CompletableFuture.completedFuture("value3")).join())
.isEqualTo("value3");
cache1.evict("key3");
assertThat(cache1.retrieve("key3", () -> CompletableFuture.completedFuture(null)).join()).isNull();
assertThat(cache1.retrieve("key3", () -> CompletableFuture.completedFuture(null)).join()).isNull();
}
@Test
public void changeCaffeineRecreateCache() {
CaffeineCacheManager cm = new CaffeineCacheManager("c1");
@@ -190,7 +256,7 @@ public class CaffeineCacheManagerTests {
assertThat(value.get()).isEqualTo("pong");
assertThatIllegalArgumentException().isThrownBy(() -> assertThat(cache1.get("foo")).isNull())
.withMessageContaining("I only know ping");
.withMessageContaining("I only know ping");
}
@Test