0
# Cache Management
1

2
The Cache Management system provides lifecycle management for caches within a CacheManager, including creation, retrieval, destruction, and configuration. The `CacheManagerImpl` is the central component that manages multiple cache instances and their configurations.
3

4
## Capabilities
5

6
### CacheManagerImpl
7

8
JSR-107 CacheManager implementation that manages Caffeine-based caches with full lifecycle support and configuration management.
9

10
```java { .api }
11
/**
12
 * An implementation of JSR-107 CacheManager that manages Caffeine-based caches.
13
 * Handles cache creation, retrieval, lifecycle, and management operations.
14
 */
15
public final class CacheManagerImpl implements CacheManager {
16
    
17
    /**
18
     * Create a new cache with the specified configuration
19
     * @param cacheName the name of the cache
20
     * @param configuration the cache configuration
21
     * @return newly created Cache instance
22
     * @throws CacheException if cache already exists or is externally configured
23
     * @throws IllegalArgumentException if arguments are null
24
     * @throws IllegalStateException if CacheManager is closed
25
     */
26
    public <K, V, C extends Configuration<K, V>> Cache<K, V> createCache(String cacheName, C configuration) throws IllegalArgumentException, CacheException, IllegalStateException;
27
    
28
    /**
29
     * Get an existing cache with type safety
30
     * @param cacheName the name of the cache
31
     * @param keyType the expected key type
32
     * @param valueType the expected value type
33
     * @return Cache instance or null if not found
34
     * @throws ClassCastException if types don't match
35
     * @throws IllegalArgumentException if arguments are null
36
     * @throws IllegalStateException if CacheManager is closed
37
     */
38
    public <K, V> @Nullable Cache<K, V> getCache(String cacheName, Class<K> keyType, Class<V> valueType) throws IllegalArgumentException, ClassCastException, IllegalStateException;
39
    
40
    /**
41
     * Get an existing cache without type checking
42
     * @param cacheName the name of the cache
43
     * @return CacheProxy instance or null if not found
44
     * @throws IllegalArgumentException if cacheName is null
45
     * @throws IllegalStateException if CacheManager is closed
46
     */
47
    public <K, V> CacheProxy<K, V> getCache(String cacheName) throws IllegalArgumentException, IllegalStateException;
48
    
49
    /**
50
     * Get all cache names managed by this CacheManager
51
     * @return unmodifiable collection of cache names
52
     * @throws IllegalStateException if CacheManager is closed
53
     */
54
    public Collection<String> getCacheNames() throws IllegalStateException;
55
    
56
    /**
57
     * Destroy and remove a cache by name
58
     * @param cacheName the name of the cache to destroy
59
     * @throws IllegalStateException if CacheManager is closed
60
     */
61
    public void destroyCache(String cacheName) throws IllegalStateException;
62
    
63
    /**
64
     * Enable or disable JMX management for a cache
65
     * @param cacheName the name of the cache
66
     * @param enabled true to enable management
67
     * @throws IllegalStateException if CacheManager is closed
68
     */
69
    public void enableManagement(String cacheName, boolean enabled) throws IllegalStateException;
70
    
71
    /**
72
     * Enable or disable statistics collection for a cache
73
     * @param cacheName the name of the cache
74
     * @param enabled true to enable statistics
75
     * @throws IllegalStateException if CacheManager is closed
76
     */
77
    public void enableStatistics(String cacheName, boolean enabled) throws IllegalStateException;
78
    
79
    /**
80
     * Get the CachingProvider that created this CacheManager
81
     * @return the associated CachingProvider
82
     */
83
    public CachingProvider getCachingProvider();
84
    
85
    /**
86
     * Get the URI that identifies this CacheManager
87
     * @return the CacheManager URI
88
     */
89
    public URI getURI();
90
    
91
    /**
92
     * Get the ClassLoader associated with this CacheManager
93
     * @return the ClassLoader (may be null if garbage collected)
94
     */
95
    public @Nullable ClassLoader getClassLoader();
96
    
97
    /**
98
     * Get the properties used to configure this CacheManager
99
     * @return the configuration properties
100
     */
101
    public Properties getProperties();
102
    
103
    /**
104
     * Close this CacheManager and all associated caches
105
     */
106
    public void close();
107
    
108
    /**
109
     * Check if this CacheManager is closed
110
     * @return true if closed
111
     */
112
    public boolean isClosed();
113
    
114
    /**
115
     * Unwrap this CacheManager to the specified type
116
     * @param clazz the class to unwrap to
117
     * @return unwrapped instance
118
     * @throws IllegalArgumentException if unwrapping is not supported
119
     */
120
    public <T> T unwrap(Class<T> clazz) throws IllegalArgumentException;
121
}
122
```
123

124
**Usage Examples:**
125

126
```java
127
import javax.cache.Caching;
128
import javax.cache.CacheManager;
129
import javax.cache.Cache;
130
import javax.cache.configuration.MutableConfiguration;
131
import com.github.benmanes.caffeine.jcache.configuration.CaffeineConfiguration;
132

133
// Get CacheManager
134
CacheManager cacheManager = Caching.getCachingProvider().getCacheManager();
135

136
// Create cache with standard configuration
137
Cache<String, String> basicCache = cacheManager.createCache("basic", 
138
    new MutableConfiguration<String, String>()
139
        .setTypes(String.class, String.class));
140

141
// Create cache with Caffeine-specific configuration
142
Cache<String, Integer> advancedCache = cacheManager.createCache("advanced",
143
    new CaffeineConfiguration<String, Integer>()
144
        .setTypes(String.class, Integer.class)
145
        .setMaximumSize(OptionalLong.of(1000))
146
        .setExpireAfterWrite(OptionalLong.of(Duration.ofMinutes(30).toNanos()))
147
        .setStatisticsEnabled(true));
148

149
// Retrieve existing caches
150
Cache<String, String> retrieved = cacheManager.getCache("basic", String.class, String.class);
151
Cache<Object, Object> untyped = cacheManager.getCache("basic");
152

153
// Manage cache lifecycle
154
Collection<String> cacheNames = cacheManager.getCacheNames();
155
cacheManager.enableStatistics("advanced", true);
156
cacheManager.enableManagement("advanced", true);
157

158
// Cleanup
159
cacheManager.destroyCache("basic");
160
cacheManager.close();
161
```
162

163
### Cache Factory Integration
164

165
The CacheManager works with the internal `CacheFactory` to create cache instances from configurations:
166

167
```java { .api }
168
// Internal factory methods (package-private)
169
static CacheProxy<?, ?> createCache(CacheManager cacheManager, String cacheName, Configuration<?, ?> configuration);
170
static CacheProxy<?, ?> tryToCreateFromExternalSettings(CacheManager cacheManager, String cacheName);
171
static boolean isDefinedExternally(CacheManager cacheManager, String cacheName);
172
```
173

174
### External Configuration Support
175

176
The CacheManager supports external configuration through:
177

178
- **Typesafe Config**: Configuration files can define cache settings
179
- **Properties**: Runtime properties for cache behavior
180
- **Environment Variables**: System-level configuration
181

182
```java
183
// Example with external configuration
184
Properties props = new Properties();
185
props.setProperty("cache.myCache.maximumSize", "1000");
186
props.setProperty("cache.myCache.expireAfterWrite", "PT30M");
187

188
CacheManager manager = Caching.getCachingProvider()
189
    .getCacheManager(URI.create("custom://config"), 
190
                    getClass().getClassLoader(), 
191
                    props);
192
```
193

194
### OSGi Support
195

196
The CacheManager includes special handling for OSGi environments:
197

198
- **ClassLoader Management**: Proper context ClassLoader handling
199
- **Component Lifecycle**: Integration with OSGi component lifecycle
200
- **Dynamic Configuration**: Support for runtime configuration changes
201

202
```java
203
// OSGi-aware cache creation (internal handling)
204
// Automatically detects OSGi environment and adjusts ClassLoader behavior
205
Cache<String, String> osgiCache = cacheManager.createCache("osgi-cache", configuration);
206
```
207

208
### Error Handling
209

210
Common exceptions thrown by CacheManager operations:
211

212
- **`CacheException`**: When cache already exists or configuration conflicts
213
- **`ClassCastException`**: When retrieved cache types don't match expected types
214
- **`IllegalStateException`**: When operations are performed on closed CacheManager
215
- **`IllegalArgumentException`**: When unwrapping to unsupported types