Skip to content

Commit 46ba13b

Browse files
snicollsnicoll
committed
Review Caching infrastructure documentation
Closes gh-33288
1 parent 9d9e621 commit 46ba13b

File tree

3 files changed

+27
-53
lines changed

3 files changed

+27
-53
lines changed

‎framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -524,7 +524,7 @@ To enable caching annotations add the annotation `@EnableCaching` to one of your
524524
----
525525
@Configuration
526526
@EnableCaching
527-
public class AppConfig {
527+
class AppConfig {
528528
529529
@Bean
530530
CacheManager cacheManager() {

‎spring-context/src/main/java/org/springframework/cache/annotation/CachingConfigurer.java

+16-40
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2002-2023 the original author or authors.
2+
* Copyright 2002-2024 the original author or authors.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -29,8 +29,8 @@
2929
* cache management.
3030
*
3131
* <p>See @{@link EnableCaching} for general examples and context; see
32-
* {@link #cacheManager()}, {@link #cacheResolver()} and {@link #keyGenerator()}
33-
* for detailed instructions.
32+
* {@link #cacheManager()}, {@link #cacheResolver()}, {@link #keyGenerator()}, and
33+
* {@link #errorHandler()} for detailed instructions.
3434
*
3535
* @author Chris Beams
3636
* @author Stephane Nicoll
@@ -46,14 +46,15 @@ public interface CachingConfigurer {
4646
* management of the cache resolution, consider setting the
4747
* {@link CacheResolver} directly.
4848
* <p>Implementations must explicitly declare
49-
* {@link org.springframework.context.annotation.Bean @Bean}, e.g.
49+
* {@link org.springframework.context.annotation.Bean @Bean} so that
50+
* the cache manager participates in the lifecycle of the context, e.g.
5051
* <pre class="code">
5152
* &#064;Configuration
5253
* &#064;EnableCaching
53-
* public class AppConfig implements CachingConfigurer {
54+
* class AppConfig implements CachingConfigurer {
5455
* &#064;Bean // important!
5556
* &#064;Override
56-
* public CacheManager cacheManager() {
57+
* CacheManager cacheManager() {
5758
* // configure and return CacheManager instance
5859
* }
5960
* // ...
@@ -70,17 +71,18 @@ default CacheManager cacheManager() {
7071
* Return the {@link CacheResolver} bean to use to resolve regular caches for
7172
* annotation-driven cache management. This is an alternative and more powerful
7273
* option of specifying the {@link CacheManager} to use.
73-
* <p>If both a {@link #cacheManager()} and {@code #cacheResolver()} are set,
74+
* <p>If both a {@link #cacheManager()} and {@code cacheResolver()} are set,
7475
* the cache manager is ignored.
7576
* <p>Implementations must explicitly declare
76-
* {@link org.springframework.context.annotation.Bean @Bean}, e.g.
77+
* {@link org.springframework.context.annotation.Bean @Bean} so that
78+
* the cache resolver participates in the lifecycle of the context, e.g.
7779
* <pre class="code">
7880
* &#064;Configuration
7981
* &#064;EnableCaching
80-
* public class AppConfig implements CachingConfigurer {
82+
* class AppConfig implements CachingConfigurer {
8183
* &#064;Bean // important!
8284
* &#064;Override
83-
* public CacheResolver cacheResolver() {
85+
* CacheResolver cacheResolver() {
8486
* // configure and return CacheResolver instance
8587
* }
8688
* // ...
@@ -95,20 +97,8 @@ default CacheResolver cacheResolver() {
9597

9698
/**
9799
* Return the key generator bean to use for annotation-driven cache management.
98-
* Implementations must explicitly declare
99-
* {@link org.springframework.context.annotation.Bean @Bean}, e.g.
100-
* <pre class="code">
101-
* &#064;Configuration
102-
* &#064;EnableCaching
103-
* public class AppConfig implements CachingConfigurer {
104-
* &#064;Bean // important!
105-
* &#064;Override
106-
* public KeyGenerator keyGenerator() {
107-
* // configure and return KeyGenerator instance
108-
* }
109-
* // ...
110-
* }
111-
* </pre>
100+
* <p>By default, {@link org.springframework.cache.interceptor.SimpleKeyGenerator}
101+
* is used.
112102
* See @{@link EnableCaching} for more complete examples.
113103
*/
114104
@Nullable
@@ -118,22 +108,8 @@ default KeyGenerator keyGenerator() {
118108

119109
/**
120110
* Return the {@link CacheErrorHandler} to use to handle cache-related errors.
121-
* <p>By default,{@link org.springframework.cache.interceptor.SimpleCacheErrorHandler}
122-
* is used and simply throws the exception back at the client.
123-
* <p>Implementations must explicitly declare
124-
* {@link org.springframework.context.annotation.Bean @Bean}, e.g.
125-
* <pre class="code">
126-
* &#064;Configuration
127-
* &#064;EnableCaching
128-
* public class AppConfig implements CachingConfigurer {
129-
* &#064;Bean // important!
130-
* &#064;Override
131-
* public CacheErrorHandler errorHandler() {
132-
* // configure and return CacheErrorHandler instance
133-
* }
134-
* // ...
135-
* }
136-
* </pre>
111+
* <p>By default, {@link org.springframework.cache.interceptor.SimpleCacheErrorHandler}
112+
* is used, which throws the exception back at the client.
137113
* See @{@link EnableCaching} for more complete examples.
138114
*/
139115
@Nullable

‎spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java

+10-12
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2002-2023 the original author or authors.
2+
* Copyright 2002-2024 the original author or authors.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -35,16 +35,16 @@
3535
* <pre class="code">
3636
* &#064;Configuration
3737
* &#064;EnableCaching
38-
* public class AppConfig {
38+
* class AppConfig {
3939
*
4040
* &#064;Bean
41-
* public MyService myService() {
41+
* MyService myService() {
4242
* // configure and return a class having &#064;Cacheable methods
4343
* return new MyService();
4444
* }
4545
*
4646
* &#064;Bean
47-
* public CacheManager cacheManager() {
47+
* CacheManager cacheManager() {
4848
* // configure and return an implementation of Spring's CacheManager SPI
4949
* SimpleCacheManager cacheManager = new SimpleCacheManager();
5050
* cacheManager.setCaches(Set.of(new ConcurrentMapCache("default")));
@@ -103,26 +103,25 @@
103103
* <pre class="code">
104104
* &#064;Configuration
105105
* &#064;EnableCaching
106-
* public class AppConfig implements CachingConfigurer {
106+
* class AppConfig implements CachingConfigurer {
107107
*
108108
* &#064;Bean
109-
* public MyService myService() {
109+
* MyService myService() {
110110
* // configure and return a class having &#064;Cacheable methods
111111
* return new MyService();
112112
* }
113113
*
114114
* &#064;Bean
115115
* &#064;Override
116-
* public CacheManager cacheManager() {
116+
* CacheManager cacheManager() {
117117
* // configure and return an implementation of Spring's CacheManager SPI
118118
* SimpleCacheManager cacheManager = new SimpleCacheManager();
119119
* cacheManager.setCaches(Set.of(new ConcurrentMapCache("default")));
120120
* return cacheManager;
121121
* }
122122
*
123-
* &#064;Bean
124123
* &#064;Override
125-
* public KeyGenerator keyGenerator() {
124+
* KeyGenerator keyGenerator() {
126125
* // configure and return an implementation of Spring's KeyGenerator SPI
127126
* return new MyKeyGenerator();
128127
* }
@@ -137,9 +136,8 @@
137136
* org.springframework.cache.interceptor.KeyGenerator KeyGenerator} SPI. Normally,
138137
* {@code @EnableCaching} will configure Spring's
139138
* {@link org.springframework.cache.interceptor.SimpleKeyGenerator SimpleKeyGenerator}
140-
* for this purpose, but when implementing {@code CachingConfigurer}, a key generator
141-
* must be provided explicitly. Return {@code null} or {@code new SimpleKeyGenerator()}
142-
* from this method if no customization is necessary.
139+
* for this purpose, but when implementing {@code CachingConfigurer}, a custom key
140+
* generator can be specified.
143141
*
144142
* <p>{@link CachingConfigurer} offers additional customization options:
145143
* see the {@link CachingConfigurer} javadoc for further details.

0 commit comments

Comments
 (0)