0
# Configuration System
1

2
The Configuration System provides comprehensive configuration capabilities extending JSR-107 with Caffeine-specific features for performance tuning and behavior customization. The `CaffeineConfiguration` class allows fine-grained control over cache behavior, performance characteristics, and integration features.
3

4
## Capabilities
5

6
### CaffeineConfiguration
7

8
Comprehensive configuration class that extends JSR-107 configuration with Caffeine-specific features for advanced cache tuning.
9

10
```java { .api }
11
/**
12
 * A JCache configuration with Caffeine specific settings.
13
 * Disables store-by-value by default for better performance.
14
 */
15
public final class CaffeineConfiguration<K, V> implements CompleteConfiguration<K, V> {
16
    
17
    /**
18
     * Default constructor with store-by-reference enabled
19
     */
20
    public CaffeineConfiguration();
21
    
22
    /**
23
     * Copy constructor for creating modifiable copy
24
     * @param configuration the configuration to copy
25
     */
26
    public CaffeineConfiguration(CompleteConfiguration<K, V> configuration);
27
    
28
    /**
29
     * Create immutable copy of this configuration
30
     * @return unmodifiable configuration copy
31
     */
32
    public CaffeineConfiguration<K, V> immutableCopy();
33
}
34
```
35

36
### Type Configuration
37

38
Configure key and value types for type safety and optimization.
39

40
```java { .api }
41
/**
42
 * Set the key and value types for this cache
43
 * @param keyType the class of the key type
44
 * @param valueType the class of the value type
45
 * @return this configuration for method chaining
46
 */
47
public CaffeineConfiguration<K, V> setTypes(Class<K> keyType, Class<V> valueType);
48

49
/**
50
 * Get the configured key type
51
 * @return the key type class
52
 */
53
public Class<K> getKeyType();
54

55
/**
56
 * Get the configured value type
57
 * @return the value type class
58
 */
59
public Class<V> getValueType();
60
```
61

62
**Usage Examples:**
63

64
```java
65
CaffeineConfiguration<String, User> config = new CaffeineConfiguration<>()
66
    .setTypes(String.class, User.class);
67

68
Cache<String, User> userCache = cacheManager.createCache("users", config);
69
```
70

71
### Integration Configuration
72

73
Configure cache loader, writer, and expiry policy for external system integration.
74

75
```java { .api }
76
/**
77
 * Set the cache loader factory for read-through operations
78
 * @param factory the CacheLoader factory
79
 * @return this configuration for method chaining
80
 */
81
public CaffeineConfiguration<K, V> setCacheLoaderFactory(Factory<? extends CacheLoader<K, V>> factory);
82

83
/**
84
 * Get the configured cache loader factory
85
 * @return the CacheLoader factory or null
86
 */
87
public @Nullable Factory<CacheLoader<K, V>> getCacheLoaderFactory();
88

89
/**
90
 * Set the cache writer factory for write-through operations
91
 * @param factory the CacheWriter factory
92
 * @return this configuration for method chaining
93
 */
94
public CaffeineConfiguration<K, V> setCacheWriterFactory(Factory<? extends CacheWriter<? super K, ? super V>> factory);
95

96
/**
97
 * Get the configured cache writer factory
98
 * @return the CacheWriter factory or null
99
 */
100
public @Nullable Factory<CacheWriter<? super K, ? super V>> getCacheWriterFactory();
101

102
/**
103
 * Check if cache writer is configured
104
 * @return true if cache writer factory is set
105
 */
106
public boolean hasCacheWriter();
107

108
/**
109
 * Get cache writer instance from factory
110
 * @return CacheWriter instance or null if not configured
111
 */
112
public @Nullable CacheWriter<K, V> getCacheWriter();
113

114
/**
115
 * Set the expiry policy factory
116
 * @param factory the ExpiryPolicy factory
117
 * @return this configuration for method chaining
118
 */
119
public CaffeineConfiguration<K, V> setExpiryPolicyFactory(Factory<? extends ExpiryPolicy> factory);
120

121
/**
122
 * Get the configured expiry policy factory
123
 * @return the ExpiryPolicy factory
124
 */
125
public Factory<ExpiryPolicy> getExpiryPolicyFactory();
126
```
127

128
**Usage Examples:**
129

130
```java
131
CaffeineConfiguration<String, User> config = new CaffeineConfiguration<String, User>()
132
    .setTypes(String.class, User.class)
133
    .setCacheLoaderFactory(() -> new DatabaseUserLoader())
134
    .setCacheWriterFactory(() -> new DatabaseUserWriter())
135
    .setExpiryPolicyFactory(() -> new TouchedExpiryPolicy(Duration.ofHours(2)))
136
    .setReadThrough(true)
137
    .setWriteThrough(true);
138
```
139

140
### Behavior Configuration
141

142
Configure cache behavior including read/write-through and store semantics.
143

144
```java { .api }
145
/**
146
 * Enable or disable read-through behavior
147
 * @param isReadThrough true to enable read-through
148
 * @return this configuration for method chaining
149
 */
150
public CaffeineConfiguration<K, V> setReadThrough(boolean isReadThrough);
151

152
/**
153
 * Check if read-through is enabled
154
 * @return true if read-through is enabled
155
 */
156
public boolean isReadThrough();
157

158
/**
159
 * Enable or disable write-through behavior
160
 * @param isWriteThrough true to enable write-through
161
 * @return this configuration for method chaining
162
 */
163
public CaffeineConfiguration<K, V> setWriteThrough(boolean isWriteThrough);
164

165
/**
166
 * Check if write-through is enabled
167
 * @return true if write-through is enabled
168
 */
169
public boolean isWriteThrough();
170

171
/**
172
 * Enable or disable store-by-value semantics
173
 * @param isStoreByValue true to enable store-by-value
174
 * @return this configuration for method chaining
175
 */
176
public CaffeineConfiguration<K, V> setStoreByValue(boolean isStoreByValue);
177

178
/**
179
 * Check if store-by-value is enabled
180
 * @return true if store-by-value is enabled
181
 */
182
public boolean isStoreByValue();
183
```
184

185
### Size and Weight Configuration
186

187
Configure cache size limits and custom weighing strategies.
188

189
```java { .api }
190
/**
191
 * Set maximum number of entries in the cache
192
 * @param maximumSize the maximum size (empty to disable)
193
 * @return this configuration for method chaining
194
 */
195
public CaffeineConfiguration<K, V> setMaximumSize(OptionalLong maximumSize);
196

197
/**
198
 * Get the configured maximum size
199
 * @return the maximum size setting
200
 */
201
public OptionalLong getMaximumSize();
202

203
/**
204
 * Set maximum weight of entries in the cache
205
 * @param maximumWeight the maximum weight (empty to disable)
206
 * @return this configuration for method chaining
207
 */
208
public CaffeineConfiguration<K, V> setMaximumWeight(OptionalLong maximumWeight);
209

210
/**
211
 * Get the configured maximum weight
212
 * @return the maximum weight setting
213
 */
214
public OptionalLong getMaximumWeight();
215

216
/**
217
 * Set the weigher factory for custom entry weighing
218
 * @param factory the Weigher factory (empty to disable)
219
 * @return this configuration for method chaining
220
 */
221
public CaffeineConfiguration<K, V> setWeigherFactory(Optional<Factory<? extends Weigher<K, V>>> factory);
222

223
/**
224
 * Get the configured weigher factory
225
 * @return the Weigher factory setting
226
 */
227
public Optional<Factory<Weigher<K, V>>> getWeigherFactory();
228
```
229

230
**Usage Examples:**
231

232
```java
233
// Size-based eviction
234
CaffeineConfiguration<String, String> sizeConfig = new CaffeineConfiguration<String, String>()
235
    .setMaximumSize(OptionalLong.of(10000));
236

237
// Weight-based eviction with custom weigher
238
CaffeineConfiguration<String, byte[]> weightConfig = new CaffeineConfiguration<String, byte[]>()
239
    .setMaximumWeight(OptionalLong.of(1024 * 1024)) // 1MB total
240
    .setWeigherFactory(Optional.of(() -> (key, value) -> 
241
        key.length() + value.length));
242
```
243

244
### Expiration Configuration
245

246
Configure time-based expiration policies with nanosecond precision.
247

248
```java { .api }
249
/**
250
 * Set expire-after-write duration in nanoseconds
251
 * @param expireAfterWriteNanos the duration (empty to disable)
252
 * @return this configuration for method chaining
253
 */
254
public CaffeineConfiguration<K, V> setExpireAfterWrite(OptionalLong expireAfterWriteNanos);
255

256
/**
257
 * Get the expire-after-write setting
258
 * @return the expire-after-write duration in nanoseconds
259
 */
260
public OptionalLong getExpireAfterWrite();
261

262
/**
263
 * Set expire-after-access duration in nanoseconds
264
 * @param expireAfterAccessNanos the duration (empty to disable)
265
 * @return this configuration for method chaining
266
 */
267
public CaffeineConfiguration<K, V> setExpireAfterAccess(OptionalLong expireAfterAccessNanos);
268

269
/**
270
 * Get the expire-after-access setting
271
 * @return the expire-after-access duration in nanoseconds
272
 */
273
public OptionalLong getExpireAfterAccess();
274

275
/**
276
 * Set refresh-after-write duration in nanoseconds
277
 * @param refreshAfterWriteNanos the duration (empty to disable)
278
 * @return this configuration for method chaining
279
 */
280
public CaffeineConfiguration<K, V> setRefreshAfterWrite(OptionalLong refreshAfterWriteNanos);
281

282
/**
283
 * Get the refresh-after-write setting
284
 * @return the refresh-after-write duration in nanoseconds
285
 */
286
public OptionalLong getRefreshAfterWrite();
287

288
/**
289
 * Set custom expiry factory for variable expiration
290
 * @param factory the Expiry factory (empty to disable)
291
 * @return this configuration for method chaining
292
 */
293
public CaffeineConfiguration<K, V> setExpiryFactory(Optional<Factory<? extends Expiry<K, V>>> factory);
294

295
/**
296
 * Get the configured expiry factory
297
 * @return the Expiry factory setting
298
 */
299
public Optional<Factory<Expiry<K, V>>> getExpiryFactory();
300
```
301

302
**Usage Examples:**
303

304
```java
305
import java.time.Duration;
306

307
// Time-based expiration
308
CaffeineConfiguration<String, String> timeConfig = new CaffeineConfiguration<String, String>()
309
    .setExpireAfterWrite(OptionalLong.of(Duration.ofMinutes(30).toNanos()))
310
    .setExpireAfterAccess(OptionalLong.of(Duration.ofMinutes(10).toNanos()))
311
    .setRefreshAfterWrite(OptionalLong.of(Duration.ofMinutes(5).toNanos()));
312

313
// Custom variable expiry
314
CaffeineConfiguration<String, CacheEntry> customExpiryConfig = 
315
    new CaffeineConfiguration<String, CacheEntry>()
316
        .setExpiryFactory(Optional.of(() -> new Expiry<String, CacheEntry>() {
317
            @Override
318
            public long expireAfterCreate(String key, CacheEntry value, long currentTime) {
319
                return value.getTtlNanos();
320
            }
321
            
322
            @Override
323
            public long expireAfterUpdate(String key, CacheEntry value, long currentTime, long currentDuration) {
324
                return value.getTtlNanos();
325
            }
326
            
327
            @Override
328
            public long expireAfterRead(String key, CacheEntry value, long currentTime, long currentDuration) {
329
                return currentDuration; // No change on read
330
            }
331
        }));
332
```
333

334
### Factory Configuration
335

336
Configure factories for various cache components and services.
337

338
```java { .api }
339
/**
340
 * Set the copier factory for store-by-value operations
341
 * @param factory the Copier factory
342
 * @return this configuration for method chaining
343
 */
344
public CaffeineConfiguration<K, V> setCopierFactory(Factory<Copier> factory);
345

346
/**
347
 * Get the configured copier factory
348
 * @return the Copier factory
349
 */
350
public Factory<Copier> getCopierFactory();
351

352
/**
353
 * Set the scheduler factory for timed operations
354
 * @param factory the Scheduler factory
355
 * @return this configuration for method chaining
356
 */
357
public CaffeineConfiguration<K, V> setSchedulerFactory(Factory<Scheduler> factory);
358

359
/**
360
 * Get the configured scheduler factory
361
 * @return the Scheduler factory
362
 */
363
public Factory<Scheduler> getSchedulerFactory();
364

365
/**
366
 * Set the ticker factory for time measurement
367
 * @param factory the Ticker factory
368
 * @return this configuration for method chaining
369
 */
370
public CaffeineConfiguration<K, V> setTickerFactory(Factory<Ticker> factory);
371

372
/**
373
 * Get the configured ticker factory
374
 * @return the Ticker factory
375
 */
376
public Factory<Ticker> getTickerFactory();
377

378
/**
379
 * Set the executor factory for asynchronous operations
380
 * @param factory the Executor factory
381
 * @return this configuration for method chaining
382
 */
383
public CaffeineConfiguration<K, V> setExecutorFactory(Factory<Executor> factory);
384

385
/**
386
 * Get the configured executor factory
387
 * @return the Executor factory
388
 */
389
public Factory<Executor> getExecutorFactory();
390
```
391

392
### Statistics and Management Configuration
393

394
Configure monitoring and management features.
395

396
```java { .api }
397
/**
398
 * Enable or disable statistics collection
399
 * @param enabled true to enable statistics
400
 * @return this configuration for method chaining
401
 */
402
public CaffeineConfiguration<K, V> setStatisticsEnabled(boolean enabled);
403

404
/**
405
 * Check if statistics are enabled
406
 * @return true if statistics are enabled
407
 */
408
public boolean isStatisticsEnabled();
409

410
/**
411
 * Enable or disable native Caffeine statistics
412
 * @param enabled true to enable native statistics
413
 * @return this configuration for method chaining
414
 */
415
public CaffeineConfiguration<K, V> setNativeStatisticsEnabled(boolean enabled);
416

417
/**
418
 * Check if native statistics are enabled
419
 * @return true if native statistics are enabled
420
 */
421
public boolean isNativeStatisticsEnabled();
422

423
/**
424
 * Enable or disable JMX management
425
 * @param enabled true to enable management
426
 * @return this configuration for method chaining
427
 */
428
public CaffeineConfiguration<K, V> setManagementEnabled(boolean enabled);
429

430
/**
431
 * Check if management is enabled
432
 * @return true if management is enabled
433
 */
434
public boolean isManagementEnabled();
435
```
436

437
### Event Listener Configuration
438

439
Configure cache entry event listeners.
440

441
```java { .api }
442
/**
443
 * Add a cache entry listener configuration
444
 * @param cacheEntryListenerConfiguration the listener configuration
445
 * @return this configuration for method chaining
446
 */
447
public CaffeineConfiguration<K, V> addCacheEntryListenerConfiguration(
448
    CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);
449

450
/**
451
 * Remove a cache entry listener configuration
452
 * @param cacheEntryListenerConfiguration the listener configuration to remove
453
 * @return this configuration for method chaining
454
 */
455
public CaffeineConfiguration<K, V> removeCacheEntryListenerConfiguration(
456
    CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);
457

458
/**
459
 * Get all configured cache entry listener configurations
460
 * @return iterable of listener configurations
461
 */
462
public Iterable<CacheEntryListenerConfiguration<K, V>> getCacheEntryListenerConfigurations();
463
```
464

465
### TypesafeConfigurator
466

467
Utility for configuring caches using Typesafe Config files.
468

469
```java { .api }
470
/**
471
 * Utility for configuring caches using Typesafe Config
472
 */
473
public final class TypesafeConfigurator {
474
    /**
475
     * Create cache configurations from Typesafe Config
476
     * @param cacheManager the cache manager
477
     * @param config the Typesafe Config instance
478
     */
479
    public static void create(CacheManager cacheManager, Config config);
480
    
481
    /**
482
     * Refresh existing cache configurations from Typesafe Config
483
     * @param cacheManager the cache manager
484
     * @param config the updated Typesafe Config instance
485
     */
486
    public static void refresh(CacheManager cacheManager, Config config);
487
}
488
```
489

490
**Configuration File Example:**
491

492
```hocon
493
# application.conf
494
cache {
495
  users {
496
    maximumSize = 1000
497
    expireAfterWrite = "PT30M"
498
    expireAfterAccess = "PT10M"
499
    statisticsEnabled = true
500
  }
501
  
502
  sessions {
503
    maximumWeight = 1048576  # 1MB
504
    expireAfterAccess = "PT1H"
505
    refreshAfterWrite = "PT30M"
506
  }
507
}
508
```
509

510
```java
511
// Load configuration
512
Config config = ConfigFactory.load();
513
TypesafeConfigurator.create(cacheManager, config);
514

515
// Caches are automatically created with configured settings
516
Cache<String, User> userCache = cacheManager.getCache("users");
517
```