0
# Caffeine JCache
1

2
Caffeine JCache is a JSR-107 JCache compatibility adapter that enables the high-performance Caffeine caching library to be used through the standard Java caching API. It implements the javax.cache interfaces including Cache, CacheManager, and related components, allowing applications to leverage Caffeine's advanced features like size-based eviction, time-based expiration, asynchronous loading, and statistical monitoring through the standardized JCache API.
3

4
## Package Information
5

6
- **Package Name**: com.github.ben-manes.caffeine:jcache
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>com.github.ben-manes.caffeine</groupId>
13
    <artifactId>jcache</artifactId>
14
    <version>3.2.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import javax.cache.Caching;
22
import javax.cache.CacheManager;
23
import javax.cache.Cache;
24
import com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider;
25
import com.github.benmanes.caffeine.jcache.configuration.CaffeineConfiguration;
26
```
27

28
## Basic Usage
29

30
```java
31
import javax.cache.Caching;
32
import javax.cache.CacheManager;
33
import javax.cache.Cache;
34
import javax.cache.configuration.MutableConfiguration;
35

36
// Get the default cache manager
37
CacheManager cacheManager = Caching.getCachingProvider().getCacheManager();
38

39
// Create a cache with default configuration
40
Cache<String, String> cache = cacheManager.createCache("myCache", 
41
    new MutableConfiguration<String, String>()
42
        .setTypes(String.class, String.class)
43
        .setStoreByValue(false));
44

45
// Basic cache operations
46
cache.put("key1", "value1");
47
String value = cache.get("key1");
48
boolean hasKey = cache.containsKey("key1");
49
cache.remove("key1");
50
```
51

52
## Architecture
53

54
Caffeine JCache is built around several key components:
55

56
- **Service Provider Interface**: `CaffeineCachingProvider` implements the JSR-107 SPI for automatic discovery
57
- **Cache Management**: `CacheManagerImpl` manages cache lifecycles and configuration
58
- **Cache Implementation**: `CacheProxy` and `LoadingCacheProxy` provide JSR-107 Cache interface backed by Caffeine
59
- **Configuration System**: `CaffeineConfiguration` extends JSR-107 configuration with Caffeine-specific features
60
- **Event System**: Comprehensive event handling for cache operations with sync/async listeners
61
- **Management & Monitoring**: JMX integration for statistics and management operations
62
- **Integration Features**: Support for cache loading, writing, and entry processing
63

64
## Capabilities
65

66
### Service Provider Interface
67

68
Entry point for JSR-107 cache discovery and CacheManager creation. Automatically discovered through ServiceLoader mechanism.
69

70
```java { .api }
71
public final class CaffeineCachingProvider implements CachingProvider {
72
    public CacheManager getCacheManager();
73
    public CacheManager getCacheManager(URI uri, ClassLoader classLoader);
74
    public CacheManager getCacheManager(URI uri, ClassLoader classLoader, Properties properties);
75
    public void close();
76
    public void close(ClassLoader classLoader);
77
    public void close(URI uri, ClassLoader classLoader);
78
    public boolean isSupported(OptionalFeature optionalFeature);
79
    public URI getDefaultURI();
80
    public ClassLoader getDefaultClassLoader();
81
    public Properties getDefaultProperties();
82
}
83
```
84

85
[Service Provider Interface](./spi.md)
86

87
### Cache Management
88

89
Cache lifecycle management including creation, retrieval, destruction, and configuration of caches within a CacheManager.
90

91
```java { .api }
92
public final class CacheManagerImpl implements CacheManager {
93
    public <K, V, C extends Configuration<K, V>> Cache<K, V> createCache(String cacheName, C configuration) throws IllegalArgumentException, CacheException, IllegalStateException;
94
    public <K, V> @Nullable Cache<K, V> getCache(String cacheName, Class<K> keyType, Class<V> valueType) throws IllegalArgumentException, ClassCastException, IllegalStateException;
95
    public <K, V> CacheProxy<K, V> getCache(String cacheName) throws IllegalArgumentException, IllegalStateException;
96
    public Collection<String> getCacheNames() throws IllegalStateException;
97
    public void destroyCache(String cacheName) throws IllegalStateException;
98
    public void enableManagement(String cacheName, boolean enabled) throws IllegalStateException;
99
    public void enableStatistics(String cacheName, boolean enabled) throws IllegalStateException;
100
    
101
    public CachingProvider getCachingProvider();
102
    public URI getURI();
103
    public @Nullable ClassLoader getClassLoader();
104
    public Properties getProperties();
105
    public void close();
106
    public boolean isClosed();
107
    public <T> T unwrap(Class<T> clazz) throws IllegalArgumentException;
108
}
109
```
110

111
[Cache Management](./cache-management.md)
112

113
### Cache Operations
114

115
Core caching functionality implementing the complete JSR-107 Cache interface with both synchronous and asynchronous operations.
116

117
```java { .api }
118
public class CacheProxy<K, V> implements Cache<K, V> {
119
    // Basic operations
120
    public @Nullable V get(K key);
121
    public Map<K, V> getAll(Set<? extends K> keys);
122
    public boolean containsKey(K key);
123
    public void put(K key, V value);
124
    public void putAll(Map<? extends K, ? extends V> map);
125
    public boolean putIfAbsent(K key, V value);
126
    
127
    // Atomic operations
128
    public @Nullable V getAndPut(K key, V value);
129
    public V getAndRemove(K key);
130
    public V getAndReplace(K key, V value);
131
    public boolean replace(K key, V oldValue, V newValue);
132
    public boolean replace(K key, V value);
133
    
134
    // Removal operations
135
    public boolean remove(K key);
136
    public boolean remove(K key, V oldValue);
137
    public void removeAll(Set<? extends K> keys);
138
    public void removeAll();
139
    public void clear();
140
    
141
    // Bulk and async operations
142
    public void loadAll(Set<? extends K> keys, boolean replaceExistingValues, 
143
                       CompletionListener completionListener);
144
    
145
    // Entry processing
146
    public <T> @Nullable T invoke(K key, EntryProcessor<K, V, T> entryProcessor, Object... arguments);
147
    public <T> Map<K, EntryProcessorResult<T>> invokeAll(Set<? extends K> keys, 
148
                                                         EntryProcessor<K, V, T> entryProcessor, 
149
                                                         Object... arguments);
150
    
151
    // Cache management
152
    public String getName();
153
    public CacheManager getCacheManager();
154
    public <C extends Configuration<K, V>> C getConfiguration(Class<C> clazz);
155
    public boolean isClosed();
156
    public void close();
157
    public <T> T unwrap(Class<T> clazz);
158
    public Iterator<Cache.Entry<K, V>> iterator();
159
}
160
```
161

162
[Cache Operations](./cache-operations.md)
163

164
### Configuration System
165

166
Comprehensive configuration system extending JSR-107 with Caffeine-specific features for performance tuning and behavior customization.
167

168
```java { .api }
169
public final class CaffeineConfiguration<K, V> implements CompleteConfiguration<K, V> {
170
    // Constructors
171
    public CaffeineConfiguration();
172
    public CaffeineConfiguration(CompleteConfiguration<K, V> configuration);
173
    public CaffeineConfiguration<K, V> immutableCopy();
174
    
175
    // Type configuration
176
    public CaffeineConfiguration<K, V> setTypes(Class<K> keyType, Class<V> valueType);
177
    
178
    // Integration configuration
179
    public CaffeineConfiguration<K, V> setCacheLoaderFactory(Factory<? extends CacheLoader<K, V>> factory);
180
    public CaffeineConfiguration<K, V> setCacheWriterFactory(Factory<? extends CacheWriter<? super K, ? super V>> factory);
181
    public CaffeineConfiguration<K, V> setExpiryPolicyFactory(Factory<? extends ExpiryPolicy> factory);
182
    public CaffeineConfiguration<K, V> addCacheEntryListenerConfiguration(CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);
183
    public CaffeineConfiguration<K, V> removeCacheEntryListenerConfiguration(CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);
184
    
185
    // Behavior configuration
186
    public CaffeineConfiguration<K, V> setReadThrough(boolean isReadThrough);
187
    public CaffeineConfiguration<K, V> setWriteThrough(boolean isWriteThrough);
188
    public CaffeineConfiguration<K, V> setStoreByValue(boolean isStoreByValue);
189
    public CaffeineConfiguration<K, V> setStatisticsEnabled(boolean enabled);
190
    public CaffeineConfiguration<K, V> setManagementEnabled(boolean enabled);
191
    public CaffeineConfiguration<K, V> setNativeStatisticsEnabled(boolean enabled);
192
    
193
    // Caffeine-specific configuration
194
    public CaffeineConfiguration<K, V> setMaximumSize(OptionalLong maximumSize);
195
    public CaffeineConfiguration<K, V> setMaximumWeight(OptionalLong maximumWeight);
196
    public CaffeineConfiguration<K, V> setExpireAfterWrite(OptionalLong expireAfterWriteNanos);
197
    public CaffeineConfiguration<K, V> setExpireAfterAccess(OptionalLong expireAfterAccessNanos);
198
    public CaffeineConfiguration<K, V> setRefreshAfterWrite(OptionalLong refreshAfterWriteNanos);
199
    
200
    // Factory configuration
201
    public CaffeineConfiguration<K, V> setWeigherFactory(Optional<Factory<? extends Weigher<K, V>>> factory);
202
    public CaffeineConfiguration<K, V> setExpiryFactory(Optional<Factory<? extends Expiry<K, V>>> factory);
203
    public CaffeineConfiguration<K, V> setCopierFactory(Factory<Copier> factory);
204
    public CaffeineConfiguration<K, V> setSchedulerFactory(Factory<Scheduler> factory);
205
    public CaffeineConfiguration<K, V> setTickerFactory(Factory<Ticker> factory);
206
    public CaffeineConfiguration<K, V> setExecutorFactory(Factory<Executor> factory);
207
}
208
```
209

210
[Configuration System](./configuration.md)
211

212
### Event Handling
213

214
Comprehensive event system for cache operations with support for synchronous and asynchronous listeners, event filtering, and custom event dispatching.
215

216
```java { .api }
217
public final class EventDispatcher<K, V> {
218
    public void register(CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);
219
    public void deregister(CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);
220
    public void publishCreated(Cache<K, V> cache, K key, V value);
221
    public void publishUpdated(Cache<K, V> cache, K key, V oldValue, V newValue);
222
    public void publishRemoved(Cache<K, V> cache, K key, V value);
223
    public void publishExpired(Cache<K, V> cache, K key, V value);
224
    public void awaitSynchronous();
225
    public void ignoreSynchronous();
226
    public List<Registration<K, V>> registrations();
227
}
228

229
public final class Registration<K, V> {
230
    public CacheEntryListener<? super K, ? super V> getCacheEntryListener();
231
    public CacheEntryFilter<? super K, ? super V> getCacheEntryFilter();
232
    public CacheEntryListenerConfiguration<K, V> getConfiguration();
233
    public boolean matches(EventType eventType);
234
}
235
```
236

237
[Event Handling](./events.md)
238

239
### Management and Monitoring
240

241
JMX integration for cache statistics, management operations, and runtime monitoring of cache performance and behavior.
242

243
```java { .api }
244
public final class JCacheStatisticsMXBean implements CacheStatisticsMXBean {
245
    public long getCacheHits();
246
    public long getCacheMisses();
247
    public long getCacheGets();
248
    public long getCachePuts();
249
    public long getCacheRemovals();
250
    public long getCacheEvictions();
251
    public float getAverageGetTime();
252
    public float getAveragePutTime();
253
    public float getAverageRemoveTime();
254
    public float getCacheHitPercentage();
255
    public float getCacheMissPercentage();
256
}
257

258
public final class JCacheMXBean implements CacheMXBean {
259
    // Management operations
260
}
261

262
public final class JmxRegistration {
263
    public static void registerMxBean(Cache<?, ?> cache, Object mxBean, MBeanType mBeanType);
264
    public static void unregisterMxBean(Cache<?, ?> cache, MBeanType mBeanType);
265
}
266
```
267

268
[Management and Monitoring](./management.md)
269

270
### Integration Features
271

272
Support for cache loading, writing, copying, and entry processing to integrate with external data sources and custom business logic.
273

274
```java { .api }
275
public final class JCacheLoaderAdapter<K, V> implements CacheLoader<K, Expirable<V>> {
276
    public Expirable<V> load(K key) throws Exception;
277
    public Map<K, Expirable<V>> loadAll(Iterable<? extends K> keys) throws Exception;
278
}
279

280
public interface Copier {
281
    public <T> T copy(T object, ClassLoader classLoader);
282
    public static Copier identity();
283
}
284

285
public class JavaSerializationCopier extends AbstractCopier<byte[]> {
286
    protected byte[] serialize(Object object, ClassLoader classLoader);
287
    protected Object deserialize(byte[] data, ClassLoader classLoader);
288
}
289

290
public final class EntryProcessorEntry<K, V> implements MutableEntry<K, V> {
291
    public K getKey();
292
    public V getValue();
293
    public boolean exists();
294
    public void remove();
295
    public void setValue(V value);
296
    public <T> T unwrap(Class<T> clazz);
297
}
298
```
299

300
[Integration Features](./integration.md)