0
# Caching Support
1

2
Spring Context Support provides comprehensive caching integration with multiple providers including Caffeine, JCache/JSR-107, and transaction-aware caching. It enables high-performance caching strategies with Spring's declarative caching annotations and programmatic cache access.
3

4
## Capabilities
5

6
### Caffeine Cache Manager
7

8
Primary entry point for Caffeine-based caching integration, offering high-performance in-memory caching with async support.
9

10
```java { .api }
11
/**
12
 * Cache manager implementation for Caffeine caches
13
 */
14
public class CaffeineCacheManager implements CacheManager {
15
    /**
16
     * Construct a dynamic CaffeineCacheManager
17
     */
18
    public CaffeineCacheManager();
19
    
20
    /**
21
     * Construct a static CaffeineCacheManager with specified cache names
22
     * @param cacheNames the cache names to manage
23
     */
24
    public CaffeineCacheManager(String... cacheNames);
25
    
26
    /**
27
     * Set the Caffeine instance to use for building caches
28
     * @param caffeine the Caffeine builder instance
29
     */
30
    public void setCaffeine(Caffeine<Object, Object> caffeine);
31
    
32
    /**
33
     * Set the CaffeineSpec to use for building caches
34
     * @param caffeineSpec the Caffeine specification
35
     */
36
    public void setCaffeineSpec(CaffeineSpec caffeineSpec);
37
    
38
    /**
39
     * Set the Caffeine cache specification String
40
     * @param cacheSpecification the cache specification string
41
     */
42
    public void setCacheSpecification(String cacheSpecification);
43
    
44
    /**
45
     * Set the Caffeine CacheLoader for building LoadingCache instances
46
     * @param cacheLoader the cache loader
47
     */
48
    public void setCacheLoader(CacheLoader<Object, Object> cacheLoader);
49
    
50
    /**
51
     * Set the Caffeine AsyncCacheLoader for building async LoadingCache instances
52
     * @param cacheLoader the async cache loader
53
     */
54
    public void setAsyncCacheLoader(AsyncCacheLoader<Object, Object> cacheLoader);
55
    
56
    /**
57
     * Enable async cache mode for non-blocking operations
58
     * @param asyncCacheMode whether to enable async mode
59
     */
60
    public void setAsyncCacheMode(boolean asyncCacheMode);
61
    
62
    /**
63
     * Configure whether to allow null values in caches
64
     * @param allowNullValues whether to allow null values
65
     */
66
    public void setAllowNullValues(boolean allowNullValues);
67
    
68
    /**
69
     * Return whether this cache manager accepts null values
70
     * @return whether null values are allowed
71
     */
72
    public boolean isAllowNullValues();
73
    
74
    /**
75
     * Set cache names for static mode
76
     * @param cacheNames collection of cache names
77
     */
78
    public void setCacheNames(Collection<String> cacheNames);
79
    
80
    /**
81
     * Register a custom native Caffeine Cache instance
82
     * @param name the cache name
83
     * @param cache the native Caffeine Cache instance
84
     */
85
    public void registerCustomCache(String name, com.github.benmanes.caffeine.cache.Cache<Object, Object> cache);
86
    
87
    /**
88
     * Register a custom Caffeine AsyncCache instance
89
     * @param name the cache name
90
     * @param cache the Caffeine AsyncCache instance
91
     */
92
    public void registerCustomCache(String name, AsyncCache<Object, Object> cache);
93
    
94
    /**
95
     * Remove the specified cache from this cache manager
96
     * @param name the name of the cache to remove
97
     */
98
    public void removeCache(String name);
99
}
100
```
101

102
**Usage Examples:**
103

104
```java
105
@Configuration
106
@EnableCaching
107
public class CacheConfig {
108
    
109
    @Bean
110
    public CacheManager cacheManager() {
111
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
112
        cacheManager.setCaffeine(Caffeine.newBuilder()
113
            .maximumSize(1000)
114
            .expireAfterWrite(Duration.ofMinutes(10))
115
            .recordStats());
116
        cacheManager.setCacheNames("users", "products", "orders");
117
        return cacheManager;
118
    }
119
    
120
    // Async cache configuration
121
    @Bean("asyncCacheManager")
122
    public CacheManager asyncCacheManager() {
123
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
124
        cacheManager.setCaffeine(Caffeine.newBuilder()
125
            .maximumSize(500)
126
            .expireAfterAccess(Duration.ofMinutes(5)));
127
        cacheManager.setAsyncCacheMode(true);
128
        return cacheManager;
129
    }
130
}
131
```
132

133
### Caffeine Cache
134

135
Individual cache implementation wrapping Caffeine cache instances with Spring Cache abstraction.
136

137
```java { .api }
138
/**
139
 * Cache implementation backed by a Caffeine cache
140
 */
141
public class CaffeineCache extends AbstractValueAdaptingCache {
142
    /**
143
     * Create a CaffeineCache instance
144
     * @param name the cache name
145
     * @param cache the underlying Caffeine cache
146
     */
147
    public CaffeineCache(String name, com.github.benmanes.caffeine.cache.Cache<Object, Object> cache);
148
    
149
    /**
150
     * Create a CaffeineCache instance with null value handling
151
     * @param name the cache name
152
     * @param cache the underlying Caffeine cache
153
     * @param allowNullValues whether to allow null values
154
     */
155
    public CaffeineCache(String name, com.github.benmanes.caffeine.cache.Cache<Object, Object> cache, boolean allowNullValues);
156
    
157
    /**
158
     * Create a CaffeineCache instance with AsyncCache support
159
     * @param name the cache name
160
     * @param cache the underlying Caffeine AsyncCache
161
     * @param allowNullValues whether to allow null values
162
     */
163
    public CaffeineCache(String name, AsyncCache<Object, Object> cache, boolean allowNullValues);
164
    
165
    /**
166
     * Get the internal Caffeine Cache instance
167
     * @return the native Caffeine Cache
168
     */
169
    public final com.github.benmanes.caffeine.cache.Cache<Object, Object> getNativeCache();
170
    
171
    /**
172
     * Get the internal Caffeine AsyncCache instance
173
     * @return the Caffeine AsyncCache
174
     * @throws IllegalStateException if no AsyncCache is available
175
     */
176
    public final AsyncCache<Object, Object> getAsyncCache();
177
    
178
    /**
179
     * Retrieve a value asynchronously (async cache mode only)
180
     * @param key the cache key
181
     * @return CompletableFuture containing the value or null
182
     */
183
    public CompletableFuture<?> retrieve(Object key);
184
    
185
    /**
186
     * Retrieve a value asynchronously with value loader (async cache mode only)
187
     * @param key the cache key
188
     * @param valueLoader the value loader supplier
189
     * @return CompletableFuture containing the loaded value
190
     */
191
    public <T> CompletableFuture<T> retrieve(Object key, Supplier<CompletableFuture<T>> valueLoader);
192
}
193
```
194

195
### JCache Manager
196

197
Entry point for JSR-107 JCache integration, supporting standard JCache implementations like Hazelcast, Infinispan, and EhCache.
198

199
```java { .api }
200
/**
201
 * Cache manager implementation for JCache/JSR-107 providers
202
 */
203
public class JCacheCacheManager extends AbstractTransactionSupportingCacheManager {
204
    /**
205
     * Set the JCache CacheManager to use
206
     * @param cacheManager the JCache CacheManager instance
207
     */
208
    public void setCacheManager(javax.cache.CacheManager cacheManager);
209
    
210
    /**
211
     * Get the underlying JCache CacheManager
212
     * @return the JCache CacheManager instance
213
     */
214
    public javax.cache.CacheManager getCacheManager();
215
    
216
    /**
217
     * Configure whether to allow null values in caches
218
     * @param allowNullValues whether to allow null values
219
     */
220
    public void setAllowNullValues(boolean allowNullValues);
221
}
222
```
223

224
**Usage Examples:**
225

226
```java
227
@Configuration
228
@EnableCaching
229
public class JCacheConfig {
230
    
231
    @Bean
232
    public CacheManager jCacheManager() {
233
        JCacheCacheManager cacheManager = new JCacheCacheManager();
234
        
235
        // Configure with Hazelcast
236
        javax.cache.CacheManager jCacheManager = Caching.getCachingProvider()
237
            .getCacheManager();
238
        cacheManager.setCacheManager(jCacheManager);
239
        
240
        return cacheManager;
241
    }
242
}
243
```
244

245
### JCache Cache
246

247
Individual JCache cache wrapper providing Spring Cache abstraction over JCache instances.
248

249
```java { .api }
250
/**
251
 * Cache implementation backed by a JCache instance
252
 */
253
public class JCacheCache extends AbstractValueAdaptingCache {
254
    /**
255
     * Create a JCacheCache instance
256
     * @param jCache the underlying JCache cache
257
     */
258
    public JCacheCache(javax.cache.Cache<Object, Object> jCache);
259
    
260
    /**
261
     * Create a JCacheCache instance with null value handling
262
     * @param jCache the underlying JCache cache
263
     * @param allowNullValues whether to allow null values
264
     */
265
    public JCacheCache(javax.cache.Cache<Object, Object> jCache, boolean allowNullValues);
266
}
267
```
268

269
### JCache Configuration Support
270

271
Configuration interfaces and classes for customizing JCache behavior.
272

273
```java { .api }
274
/**
275
 * Configuration interface for JCache setup
276
 */
277
public interface JCacheConfigurer extends CachingConfigurer {
278
    /**
279
     * Return the cache resolver for exception caching
280
     * @return the exception cache resolver, or null for default
281
     */
282
    @Nullable
283
    CacheResolver exceptionCacheResolver();
284
}
285

286
/**
287
 * Base implementation of JCacheConfigurer
288
 */
289
public class JCacheConfigurerSupport implements JCacheConfigurer {
290
    @Override
291
    @Nullable
292
    public CacheManager cacheManager() { return null; }
293
    
294
    @Override
295
    @Nullable
296
    public CacheResolver cacheResolver() { return null; }
297
    
298
    @Override
299
    @Nullable
300
    public CacheResolver exceptionCacheResolver() { return null; }
301
    
302
    @Override
303
    @Nullable
304
    public KeyGenerator keyGenerator() { return null; }
305
    
306
    @Override
307
    @Nullable
308
    public CacheErrorHandler errorHandler() { return null; }
309
}
310
```
311

312
### Transaction-Aware Caching
313

314
Proxy-based cache manager that synchronizes cache operations with Spring transactions.
315

316
```java { .api }
317
/**
318
 * Proxy for a target CacheManager that synchronizes cache operations with Spring transactions
319
 */
320
public class TransactionAwareCacheManagerProxy implements CacheManager, InitializingBean {
321
    /**
322
     * Set the target CacheManager to proxy
323
     * @param targetCacheManager the target cache manager
324
     */
325
    public void setTargetCacheManager(CacheManager targetCacheManager);
326
    
327
    /**
328
     * Get the target CacheManager being proxied
329
     * @return the target cache manager
330
     */
331
    public CacheManager getTargetCacheManager();
332
}
333

334
/**
335
 * Cache decorator that synchronizes cache operations with Spring transactions
336
 */
337
public class TransactionAwareCacheDecorator implements Cache {
338
    /**
339
     * Create a transaction-aware cache decorator
340
     * @param targetCache the target cache to decorate
341
     */
342
    public TransactionAwareCacheDecorator(Cache targetCache);
343
    
344
    /**
345
     * Get the target cache being decorated
346
     * @return the target cache
347
     */
348
    public Cache getTargetCache();
349
}
350

351
/**
352
 * Base class for cache managers that support transactions
353
 */
354
public abstract class AbstractTransactionSupportingCacheManager extends AbstractCacheManager 
355
        implements BeanClassLoaderAware, InitializingBean {
356
    /**
357
     * Set whether to decorate caches with transaction awareness
358
     * @param transactionAware whether to enable transaction awareness
359
     */
360
    public void setTransactionAware(boolean transactionAware);
361
    
362
    /**
363
     * Check whether caches are decorated with transaction awareness
364
     * @return whether transaction awareness is enabled
365
     */
366
    public boolean isTransactionAware();
367
}
368
```
369

370
**Usage Examples:**
371

372
```java
373
@Configuration
374
@EnableCaching
375
@EnableTransactionManagement
376
public class TransactionalCacheConfig {
377
    
378
    @Bean
379
    public CacheManager transactionalCacheManager() {
380
        // Create base cache manager
381
        CaffeineCacheManager baseCacheManager = new CaffeineCacheManager();
382
        baseCacheManager.setCaffeine(Caffeine.newBuilder()
383
            .maximumSize(1000)
384
            .expireAfterWrite(Duration.ofMinutes(10)));
385
        
386
        // Wrap with transaction-aware proxy
387
        TransactionAwareCacheManagerProxy proxy = new TransactionAwareCacheManagerProxy();
388
        proxy.setTargetCacheManager(baseCacheManager);
389
        
390
        return proxy;
391
    }
392
}
393

394
@Service
395
@Transactional
396
public class UserService {
397
    
398
    @Cacheable("users")
399
    public User findUser(Long id) {
400
        // Cache will be populated after transaction commits
401
        return userRepository.findById(id);
402
    }
403
    
404
    @CacheEvict("users")
405
    public void updateUser(User user) {
406
        // Cache will be evicted after transaction commits
407
        userRepository.save(user);
408
    }
409
}
410
```
411

412
## JCache Interceptor Support
413

414
Advanced AOP support for JCache annotations processing.
415

416
```java { .api }
417
/**
418
 * AOP interceptor for JCache annotations
419
 */
420
public class JCacheInterceptor extends JCacheAspectSupport implements MethodInterceptor, Serializable {
421
}
422

423
/**
424
 * Base class providing JCache operation aspects
425
 */
426
public abstract class JCacheAspectSupport implements BeanFactoryAware, InitializingBean, SmartInitializingSingleton {
427
    /**
428
     * Set the JCache operation source for metadata lookup
429
     * @param jCacheOperationSource the operation source
430
     */
431
    public void setJCacheOperationSource(JCacheOperationSource jCacheOperationSource);
432
}
433

434
/**
435
 * Interface for JCache operation metadata source
436
 */
437
public interface JCacheOperationSource {
438
    /**
439
     * Get JCache operations for the given method
440
     * @param method the method to analyze
441
     * @param targetClass the target class
442
     * @return collection of JCache operations, or null if none
443
     */
444
    @Nullable
445
    Collection<JCacheOperation<?>> getCacheOperations(Method method, @Nullable Class<?> targetClass);
446
}
447
```