Configuration System

/**
 * A JCache configuration with Caffeine specific settings.
 * Disables store-by-value by default for better performance.
 */
public final class CaffeineConfiguration<K, V> implements CompleteConfiguration<K, V> {
    
    /**
     * Default constructor with store-by-reference enabled
     */
    public CaffeineConfiguration();
    
    /**
     * Copy constructor for creating modifiable copy
     * @param configuration the configuration to copy
     */
    public CaffeineConfiguration(CompleteConfiguration<K, V> configuration);
    
    /**
     * Create immutable copy of this configuration
     * @return unmodifiable configuration copy
     */
    public CaffeineConfiguration<K, V> immutableCopy();
}

/**
 * Set the key and value types for this cache
 * @param keyType the class of the key type
 * @param valueType the class of the value type
 * @return this configuration for method chaining
 */
public CaffeineConfiguration<K, V> setTypes(Class<K> keyType, Class<V> valueType);

/**
 * Get the configured key type
 * @return the key type class
 */
public Class<K> getKeyType();

/**
 * Get the configured value type
 * @return the value type class
 */
public Class<V> getValueType();

CaffeineConfiguration<String, User> config = new CaffeineConfiguration<>()
    .setTypes(String.class, User.class);

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

/**
 * Set the cache loader factory for read-through operations
 * @param factory the CacheLoader factory
 * @return this configuration for method chaining
 */
public CaffeineConfiguration<K, V> setCacheLoaderFactory(Factory<? extends CacheLoader<K, V>> factory);

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

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

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

/**
 * Check if cache writer is configured
 * @return true if cache writer factory is set
 */
public boolean hasCacheWriter();

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

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

/**
 * Get the configured expiry policy factory
 * @return the ExpiryPolicy factory
 */
public Factory<ExpiryPolicy> getExpiryPolicyFactory();

CaffeineConfiguration<String, User> config = new CaffeineConfiguration<String, User>()
    .setTypes(String.class, User.class)
    .setCacheLoaderFactory(() -> new DatabaseUserLoader())
    .setCacheWriterFactory(() -> new DatabaseUserWriter())
    .setExpiryPolicyFactory(() -> new TouchedExpiryPolicy(Duration.ofHours(2)))
    .setReadThrough(true)
    .setWriteThrough(true);

/**
 * Enable or disable read-through behavior
 * @param isReadThrough true to enable read-through
 * @return this configuration for method chaining
 */
public CaffeineConfiguration<K, V> setReadThrough(boolean isReadThrough);

/**
 * Check if read-through is enabled
 * @return true if read-through is enabled
 */
public boolean isReadThrough();

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

/**
 * Check if write-through is enabled
 * @return true if write-through is enabled
 */
public boolean isWriteThrough();

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

/**
 * Check if store-by-value is enabled
 * @return true if store-by-value is enabled
 */
public boolean isStoreByValue();

/**
 * Set maximum number of entries in the cache
 * @param maximumSize the maximum size (empty to disable)
 * @return this configuration for method chaining
 */
public CaffeineConfiguration<K, V> setMaximumSize(OptionalLong maximumSize);

/**
 * Get the configured maximum size
 * @return the maximum size setting
 */
public OptionalLong getMaximumSize();

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

/**
 * Get the configured maximum weight
 * @return the maximum weight setting
 */
public OptionalLong getMaximumWeight();

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

/**
 * Get the configured weigher factory
 * @return the Weigher factory setting
 */
public Optional<Factory<Weigher<K, V>>> getWeigherFactory();

// Size-based eviction
CaffeineConfiguration<String, String> sizeConfig = new CaffeineConfiguration<String, String>()
    .setMaximumSize(OptionalLong.of(10000));

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

/**
 * Set expire-after-write duration in nanoseconds
 * @param expireAfterWriteNanos the duration (empty to disable)
 * @return this configuration for method chaining
 */
public CaffeineConfiguration<K, V> setExpireAfterWrite(OptionalLong expireAfterWriteNanos);

/**
 * Get the expire-after-write setting
 * @return the expire-after-write duration in nanoseconds
 */
public OptionalLong getExpireAfterWrite();

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

/**
 * Get the expire-after-access setting
 * @return the expire-after-access duration in nanoseconds
 */
public OptionalLong getExpireAfterAccess();

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

/**
 * Get the refresh-after-write setting
 * @return the refresh-after-write duration in nanoseconds
 */
public OptionalLong getRefreshAfterWrite();

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

/**
 * Get the configured expiry factory
 * @return the Expiry factory setting
 */
public Optional<Factory<Expiry<K, V>>> getExpiryFactory();

import java.time.Duration;

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

// Custom variable expiry
CaffeineConfiguration<String, CacheEntry> customExpiryConfig = 
    new CaffeineConfiguration<String, CacheEntry>()
        .setExpiryFactory(Optional.of(() -> new Expiry<String, CacheEntry>() {
            @Override
            public long expireAfterCreate(String key, CacheEntry value, long currentTime) {
                return value.getTtlNanos();
            }
            
            @Override
            public long expireAfterUpdate(String key, CacheEntry value, long currentTime, long currentDuration) {
                return value.getTtlNanos();
            }
            
            @Override
            public long expireAfterRead(String key, CacheEntry value, long currentTime, long currentDuration) {
                return currentDuration; // No change on read
            }
        }));

/**
 * Set the copier factory for store-by-value operations
 * @param factory the Copier factory
 * @return this configuration for method chaining
 */
public CaffeineConfiguration<K, V> setCopierFactory(Factory<Copier> factory);

/**
 * Get the configured copier factory
 * @return the Copier factory
 */
public Factory<Copier> getCopierFactory();

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

/**
 * Get the configured scheduler factory
 * @return the Scheduler factory
 */
public Factory<Scheduler> getSchedulerFactory();

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

/**
 * Get the configured ticker factory
 * @return the Ticker factory
 */
public Factory<Ticker> getTickerFactory();

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

/**
 * Get the configured executor factory
 * @return the Executor factory
 */
public Factory<Executor> getExecutorFactory();

/**
 * Enable or disable statistics collection
 * @param enabled true to enable statistics
 * @return this configuration for method chaining
 */
public CaffeineConfiguration<K, V> setStatisticsEnabled(boolean enabled);

/**
 * Check if statistics are enabled
 * @return true if statistics are enabled
 */
public boolean isStatisticsEnabled();

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

/**
 * Check if native statistics are enabled
 * @return true if native statistics are enabled
 */
public boolean isNativeStatisticsEnabled();

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

/**
 * Check if management is enabled
 * @return true if management is enabled
 */
public boolean isManagementEnabled();

/**
 * Add a cache entry listener configuration
 * @param cacheEntryListenerConfiguration the listener configuration
 * @return this configuration for method chaining
 */
public CaffeineConfiguration<K, V> addCacheEntryListenerConfiguration(
    CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);

/**
 * Remove a cache entry listener configuration
 * @param cacheEntryListenerConfiguration the listener configuration to remove
 * @return this configuration for method chaining
 */
public CaffeineConfiguration<K, V> removeCacheEntryListenerConfiguration(
    CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);

/**
 * Get all configured cache entry listener configurations
 * @return iterable of listener configurations
 */
public Iterable<CacheEntryListenerConfiguration<K, V>> getCacheEntryListenerConfigurations();

/**
 * Utility for configuring caches using Typesafe Config
 */
public final class TypesafeConfigurator {
    /**
     * Create cache configurations from Typesafe Config
     * @param cacheManager the cache manager
     * @param config the Typesafe Config instance
     */
    public static void create(CacheManager cacheManager, Config config);
    
    /**
     * Refresh existing cache configurations from Typesafe Config
     * @param cacheManager the cache manager
     * @param config the updated Typesafe Config instance
     */
    public static void refresh(CacheManager cacheManager, Config config);
}

# application.conf
cache {
  users {
    maximumSize = 1000
    expireAfterWrite = "PT30M"
    expireAfterAccess = "PT10M"
    statisticsEnabled = true
  }
  
  sessions {
    maximumWeight = 1048576  # 1MB
    expireAfterAccess = "PT1H"
    refreshAfterWrite = "PT30M"
  }
}

// Load configuration
Config config = ConfigFactory.load();
TypesafeConfigurator.create(cacheManager, config);

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