From 46ba13b6451d7cb624512bd5c363819e62f1e47a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Nicoll?= Date: Mon, 29 Jul 2024 11:29:09 +0200 Subject: [PATCH] Review Caching infrastructure documentation Closes gh-33288 --- .../pages/integration/cache/annotations.adoc | 2 +- .../cache/annotation/CachingConfigurer.java | 56 ++++++------------- .../cache/annotation/EnableCaching.java | 22 ++++---- 3 files changed, 27 insertions(+), 53 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc b/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc index a455ac6ef278..9acd169a1d13 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc @@ -524,7 +524,7 @@ To enable caching annotations add the annotation `@EnableCaching` to one of your ---- @Configuration @EnableCaching - public class AppConfig { + class AppConfig { @Bean CacheManager cacheManager() { diff --git a/spring-context/src/main/java/org/springframework/cache/annotation/CachingConfigurer.java b/spring-context/src/main/java/org/springframework/cache/annotation/CachingConfigurer.java index fe26f7d56d93..85c372dfeb3c 100644 --- a/spring-context/src/main/java/org/springframework/cache/annotation/CachingConfigurer.java +++ b/spring-context/src/main/java/org/springframework/cache/annotation/CachingConfigurer.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2023 the original author or authors. + * Copyright 2002-2024 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. @@ -29,8 +29,8 @@ * cache management. * *

See @{@link EnableCaching} for general examples and context; see - * {@link #cacheManager()}, {@link #cacheResolver()} and {@link #keyGenerator()} - * for detailed instructions. + * {@link #cacheManager()}, {@link #cacheResolver()}, {@link #keyGenerator()}, and + * {@link #errorHandler()} for detailed instructions. * * @author Chris Beams * @author Stephane Nicoll @@ -46,14 +46,15 @@ public interface CachingConfigurer { * management of the cache resolution, consider setting the * {@link CacheResolver} directly. *

Implementations must explicitly declare - * {@link org.springframework.context.annotation.Bean @Bean}, e.g. + * {@link org.springframework.context.annotation.Bean @Bean} so that + * the cache manager participates in the lifecycle of the context, e.g. * 

 	 * @Configuration
 	 * @EnableCaching
-	 * public class AppConfig implements CachingConfigurer {
+	 * class AppConfig implements CachingConfigurer {
 	 *     @Bean // important!
 	 *     @Override
-	 *     public CacheManager cacheManager() {
+	 *     CacheManager cacheManager() {
 	 *         // configure and return CacheManager instance
 	 *     }
 	 *     // ...
@@ -70,17 +71,18 @@ default CacheManager cacheManager() {
 	 * Return the {@link CacheResolver} bean to use to resolve regular caches for
 	 * annotation-driven cache management. This is an alternative and more powerful
 	 * option of specifying the {@link CacheManager} to use.
-	 * 
If both a {@link #cacheManager()} and {@code #cacheResolver()} are set,
+	 * 
If both a {@link #cacheManager()} and {@code cacheResolver()} are set,
 	 * the cache manager is ignored.
 	 * 
Implementations must explicitly declare
-	 * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
+	 * {@link org.springframework.context.annotation.Bean @Bean} so that
+	 * the cache resolver participates in the lifecycle of the context, e.g.
 	 * 
 	 * @Configuration
 	 * @EnableCaching
-	 * public class AppConfig implements CachingConfigurer {
+	 * class AppConfig implements CachingConfigurer {
 	 *     @Bean // important!
 	 *     @Override
-	 *     public CacheResolver cacheResolver() {
+	 *     CacheResolver cacheResolver() {
 	 *         // configure and return CacheResolver instance
 	 *     }
 	 *     // ...
@@ -95,20 +97,8 @@ default CacheResolver cacheResolver() {
 
 	/**
 	 * Return the key generator bean to use for annotation-driven cache management.
-	 * Implementations must explicitly declare
-	 * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
-	 * 
-	 * @Configuration
-	 * @EnableCaching
-	 * public class AppConfig implements CachingConfigurer {
-	 *     @Bean // important!
-	 *     @Override
-	 *     public KeyGenerator keyGenerator() {
-	 *         // configure and return KeyGenerator instance
-	 *     }
-	 *     // ...
-	 * }
-	 * 

+	 * 
By default, {@link org.springframework.cache.interceptor.SimpleKeyGenerator}
+	 * is used.
 	 * See @{@link EnableCaching} for more complete examples.
 	 */
 	@Nullable
@@ -118,22 +108,8 @@ default KeyGenerator keyGenerator() {
 
 	/**
 	 * Return the {@link CacheErrorHandler} to use to handle cache-related errors.
-	 * 
By default,{@link org.springframework.cache.interceptor.SimpleCacheErrorHandler}
-	 * is used and simply throws the exception back at the client.
-	 * 
Implementations must explicitly declare
-	 * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
-	 * 
-	 * @Configuration
-	 * @EnableCaching
-	 * public class AppConfig implements CachingConfigurer {
-	 *     @Bean // important!
-	 *     @Override
-	 *     public CacheErrorHandler errorHandler() {
-	 *         // configure and return CacheErrorHandler instance
-	 *     }
-	 *     // ...
-	 * }
-	 * 

+	 * 
By default, {@link org.springframework.cache.interceptor.SimpleCacheErrorHandler}
+	 * is used, which throws the exception back at the client.
 	 * See @{@link EnableCaching} for more complete examples.
 	 */
 	@Nullable
diff --git a/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java b/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java
index 06ea231402d4..75ad63f82747 100644
--- a/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java
+++ b/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -35,16 +35,16 @@
  * 
  * @Configuration
  * @EnableCaching
- * public class AppConfig {
+ * class AppConfig {
  *
  *     @Bean
- *     public MyService myService() {
+ *     MyService myService() {
  *         // configure and return a class having @Cacheable methods
  *         return new MyService();
  *     }
  *
  *     @Bean
- *     public CacheManager cacheManager() {
+ *     CacheManager cacheManager() {
  *         // configure and return an implementation of Spring's CacheManager SPI
  *         SimpleCacheManager cacheManager = new SimpleCacheManager();
  *         cacheManager.setCaches(Set.of(new ConcurrentMapCache("default")));
@@ -103,26 +103,25 @@
  * 
  * @Configuration
  * @EnableCaching
- * public class AppConfig implements CachingConfigurer {
+ * class AppConfig implements CachingConfigurer {
  *
  *     @Bean
- *     public MyService myService() {
+ *     MyService myService() {
  *         // configure and return a class having @Cacheable methods
  *         return new MyService();
  *     }
  *
  *     @Bean
  *     @Override
- *     public CacheManager cacheManager() {
+ *     CacheManager cacheManager() {
  *         // configure and return an implementation of Spring's CacheManager SPI
  *         SimpleCacheManager cacheManager = new SimpleCacheManager();
  *         cacheManager.setCaches(Set.of(new ConcurrentMapCache("default")));
  *         return cacheManager;
  *     }
  *
- *     @Bean
  *     @Override
- *     public KeyGenerator keyGenerator() {
+ *     KeyGenerator keyGenerator() {
  *         // configure and return an implementation of Spring's KeyGenerator SPI
  *         return new MyKeyGenerator();
  *     }
@@ -137,9 +136,8 @@
  * org.springframework.cache.interceptor.KeyGenerator KeyGenerator} SPI. Normally,
  * {@code @EnableCaching} will configure Spring's
  * {@link org.springframework.cache.interceptor.SimpleKeyGenerator SimpleKeyGenerator}
- * for this purpose, but when implementing {@code CachingConfigurer}, a key generator
- * must be provided explicitly. Return {@code null} or {@code new SimpleKeyGenerator()}
- * from this method if no customization is necessary.
+ * for this purpose, but when implementing {@code CachingConfigurer}, a custom key
+ * generator can be specified.
  *
  * 
{@link CachingConfigurer} offers additional customization options:
  * see the {@link CachingConfigurer} javadoc for further details.