Caching Support

/**
 * Cache manager implementation for Caffeine caches
 */
public class CaffeineCacheManager implements CacheManager {
    /**
     * Construct a dynamic CaffeineCacheManager
     */
    public CaffeineCacheManager();
    
    /**
     * Construct a static CaffeineCacheManager with specified cache names
     * @param cacheNames the cache names to manage
     */
    public CaffeineCacheManager(String... cacheNames);
    
    /**
     * Set the Caffeine instance to use for building caches
     * @param caffeine the Caffeine builder instance
     */
    public void setCaffeine(Caffeine<Object, Object> caffeine);
    
    /**
     * Set the CaffeineSpec to use for building caches
     * @param caffeineSpec the Caffeine specification
     */
    public void setCaffeineSpec(CaffeineSpec caffeineSpec);
    
    /**
     * Set the Caffeine cache specification String
     * @param cacheSpecification the cache specification string
     */
    public void setCacheSpecification(String cacheSpecification);
    
    /**
     * Set the Caffeine CacheLoader for building LoadingCache instances
     * @param cacheLoader the cache loader
     */
    public void setCacheLoader(CacheLoader<Object, Object> cacheLoader);
    
    /**
     * Set the Caffeine AsyncCacheLoader for building async LoadingCache instances
     * @param cacheLoader the async cache loader
     */
    public void setAsyncCacheLoader(AsyncCacheLoader<Object, Object> cacheLoader);
    
    /**
     * Enable async cache mode for non-blocking operations
     * @param asyncCacheMode whether to enable async mode
     */
    public void setAsyncCacheMode(boolean asyncCacheMode);
    
    /**
     * Configure whether to allow null values in caches
     * @param allowNullValues whether to allow null values
     */
    public void setAllowNullValues(boolean allowNullValues);
    
    /**
     * Return whether this cache manager accepts null values
     * @return whether null values are allowed
     */
    public boolean isAllowNullValues();
    
    /**
     * Set cache names for static mode
     * @param cacheNames collection of cache names
     */
    public void setCacheNames(Collection<String> cacheNames);
    
    /**
     * Register a custom native Caffeine Cache instance
     * @param name the cache name
     * @param cache the native Caffeine Cache instance
     */
    public void registerCustomCache(String name, com.github.benmanes.caffeine.cache.Cache<Object, Object> cache);
    
    /**
     * Register a custom Caffeine AsyncCache instance
     * @param name the cache name
     * @param cache the Caffeine AsyncCache instance
     */
    public void registerCustomCache(String name, AsyncCache<Object, Object> cache);
    
    /**
     * Remove the specified cache from this cache manager
     * @param name the name of the cache to remove
     */
    public void removeCache(String name);
}

@Configuration
@EnableCaching
public class CacheConfig {
    
    @Bean
    public CacheManager cacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
        cacheManager.setCaffeine(Caffeine.newBuilder()
            .maximumSize(1000)
            .expireAfterWrite(Duration.ofMinutes(10))
            .recordStats());
        cacheManager.setCacheNames("users", "products", "orders");
        return cacheManager;
    }
    
    // Async cache configuration
    @Bean("asyncCacheManager")
    public CacheManager asyncCacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
        cacheManager.setCaffeine(Caffeine.newBuilder()
            .maximumSize(500)
            .expireAfterAccess(Duration.ofMinutes(5)));
        cacheManager.setAsyncCacheMode(true);
        return cacheManager;
    }
}

/**
 * Cache implementation backed by a Caffeine cache
 */
public class CaffeineCache extends AbstractValueAdaptingCache {
    /**
     * Create a CaffeineCache instance
     * @param name the cache name
     * @param cache the underlying Caffeine cache
     */
    public CaffeineCache(String name, com.github.benmanes.caffeine.cache.Cache<Object, Object> cache);
    
    /**
     * Create a CaffeineCache instance with null value handling
     * @param name the cache name
     * @param cache the underlying Caffeine cache
     * @param allowNullValues whether to allow null values
     */
    public CaffeineCache(String name, com.github.benmanes.caffeine.cache.Cache<Object, Object> cache, boolean allowNullValues);
    
    /**
     * Create a CaffeineCache instance with AsyncCache support
     * @param name the cache name
     * @param cache the underlying Caffeine AsyncCache
     * @param allowNullValues whether to allow null values
     */
    public CaffeineCache(String name, AsyncCache<Object, Object> cache, boolean allowNullValues);
    
    /**
     * Get the internal Caffeine Cache instance
     * @return the native Caffeine Cache
     */
    public final com.github.benmanes.caffeine.cache.Cache<Object, Object> getNativeCache();
    
    /**
     * Get the internal Caffeine AsyncCache instance
     * @return the Caffeine AsyncCache
     * @throws IllegalStateException if no AsyncCache is available
     */
    public final AsyncCache<Object, Object> getAsyncCache();
    
    /**
     * Retrieve a value asynchronously (async cache mode only)
     * @param key the cache key
     * @return CompletableFuture containing the value or null
     */
    public CompletableFuture<?> retrieve(Object key);
    
    /**
     * Retrieve a value asynchronously with value loader (async cache mode only)
     * @param key the cache key
     * @param valueLoader the value loader supplier
     * @return CompletableFuture containing the loaded value
     */
    public <T> CompletableFuture<T> retrieve(Object key, Supplier<CompletableFuture<T>> valueLoader);
}

/**
 * Cache manager implementation for JCache/JSR-107 providers
 */
public class JCacheCacheManager extends AbstractTransactionSupportingCacheManager {
    /**
     * Set the JCache CacheManager to use
     * @param cacheManager the JCache CacheManager instance
     */
    public void setCacheManager(javax.cache.CacheManager cacheManager);
    
    /**
     * Get the underlying JCache CacheManager
     * @return the JCache CacheManager instance
     */
    public javax.cache.CacheManager getCacheManager();
    
    /**
     * Configure whether to allow null values in caches
     * @param allowNullValues whether to allow null values
     */
    public void setAllowNullValues(boolean allowNullValues);
}

@Configuration
@EnableCaching
public class JCacheConfig {
    
    @Bean
    public CacheManager jCacheManager() {
        JCacheCacheManager cacheManager = new JCacheCacheManager();
        
        // Configure with Hazelcast
        javax.cache.CacheManager jCacheManager = Caching.getCachingProvider()
            .getCacheManager();
        cacheManager.setCacheManager(jCacheManager);
        
        return cacheManager;
    }
}

/**
 * Cache implementation backed by a JCache instance
 */
public class JCacheCache extends AbstractValueAdaptingCache {
    /**
     * Create a JCacheCache instance
     * @param jCache the underlying JCache cache
     */
    public JCacheCache(javax.cache.Cache<Object, Object> jCache);
    
    /**
     * Create a JCacheCache instance with null value handling
     * @param jCache the underlying JCache cache
     * @param allowNullValues whether to allow null values
     */
    public JCacheCache(javax.cache.Cache<Object, Object> jCache, boolean allowNullValues);
}

/**
 * Configuration interface for JCache setup
 */
public interface JCacheConfigurer extends CachingConfigurer {
    /**
     * Return the cache resolver for exception caching
     * @return the exception cache resolver, or null for default
     */
    @Nullable
    CacheResolver exceptionCacheResolver();
}

/**
 * Base implementation of JCacheConfigurer
 */
public class JCacheConfigurerSupport implements JCacheConfigurer {
    @Override
    @Nullable
    public CacheManager cacheManager() { return null; }
    
    @Override
    @Nullable
    public CacheResolver cacheResolver() { return null; }
    
    @Override
    @Nullable
    public CacheResolver exceptionCacheResolver() { return null; }
    
    @Override
    @Nullable
    public KeyGenerator keyGenerator() { return null; }
    
    @Override
    @Nullable
    public CacheErrorHandler errorHandler() { return null; }
}

/**
 * Proxy for a target CacheManager that synchronizes cache operations with Spring transactions
 */
public class TransactionAwareCacheManagerProxy implements CacheManager, InitializingBean {
    /**
     * Set the target CacheManager to proxy
     * @param targetCacheManager the target cache manager
     */
    public void setTargetCacheManager(CacheManager targetCacheManager);
    
    /**
     * Get the target CacheManager being proxied
     * @return the target cache manager
     */
    public CacheManager getTargetCacheManager();
}

/**
 * Cache decorator that synchronizes cache operations with Spring transactions
 */
public class TransactionAwareCacheDecorator implements Cache {
    /**
     * Create a transaction-aware cache decorator
     * @param targetCache the target cache to decorate
     */
    public TransactionAwareCacheDecorator(Cache targetCache);
    
    /**
     * Get the target cache being decorated
     * @return the target cache
     */
    public Cache getTargetCache();
}

/**
 * Base class for cache managers that support transactions
 */
public abstract class AbstractTransactionSupportingCacheManager extends AbstractCacheManager 
        implements BeanClassLoaderAware, InitializingBean {
    /**
     * Set whether to decorate caches with transaction awareness
     * @param transactionAware whether to enable transaction awareness
     */
    public void setTransactionAware(boolean transactionAware);
    
    /**
     * Check whether caches are decorated with transaction awareness
     * @return whether transaction awareness is enabled
     */
    public boolean isTransactionAware();
}

@Configuration
@EnableCaching
@EnableTransactionManagement
public class TransactionalCacheConfig {
    
    @Bean
    public CacheManager transactionalCacheManager() {
        // Create base cache manager
        CaffeineCacheManager baseCacheManager = new CaffeineCacheManager();
        baseCacheManager.setCaffeine(Caffeine.newBuilder()
            .maximumSize(1000)
            .expireAfterWrite(Duration.ofMinutes(10)));
        
        // Wrap with transaction-aware proxy
        TransactionAwareCacheManagerProxy proxy = new TransactionAwareCacheManagerProxy();
        proxy.setTargetCacheManager(baseCacheManager);
        
        return proxy;
    }
}

@Service
@Transactional
public class UserService {
    
    @Cacheable("users")
    public User findUser(Long id) {
        // Cache will be populated after transaction commits
        return userRepository.findById(id);
    }
    
    @CacheEvict("users")
    public void updateUser(User user) {
        // Cache will be evicted after transaction commits
        userRepository.save(user);
    }
}

/**
 * AOP interceptor for JCache annotations
 */
public class JCacheInterceptor extends JCacheAspectSupport implements MethodInterceptor, Serializable {
}

/**
 * Base class providing JCache operation aspects
 */
public abstract class JCacheAspectSupport implements BeanFactoryAware, InitializingBean, SmartInitializingSingleton {
    /**
     * Set the JCache operation source for metadata lookup
     * @param jCacheOperationSource the operation source
     */
    public void setJCacheOperationSource(JCacheOperationSource jCacheOperationSource);
}

/**
 * Interface for JCache operation metadata source
 */
public interface JCacheOperationSource {
    /**
     * Get JCache operations for the given method
     * @param method the method to analyze
     * @param targetClass the target class
     * @return collection of JCache operations, or null if none
     */
    @Nullable
    Collection<JCacheOperation<?>> getCacheOperations(Method method, @Nullable Class<?> targetClass);
}