or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cache-management.mdcache-operations.mdconfiguration.mdevents.mdindex.mdintegration.mdmanagement.mdspi.md
tile.json

tessl/maven-com-github-ben-manes-caffeine--jcache

JSR-107 JCache compatibility adapter for Caffeine caching library

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.github.ben-manes.caffeine/jcache@3.2.x

To install, run

npx @tessl/cli install tessl/maven-com-github-ben-manes-caffeine--jcache@3.2.0

index.mddocs/

Caffeine JCache

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.

Package Information

  • Package Name: com.github.ben-manes.caffeine:jcache
  • Package Type: maven
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>com.github.ben-manes.caffeine</groupId>
  <artifactId>jcache</artifactId>
  <version>3.2.0</version>
</dependency>

Core Imports

import javax.cache.Caching;
import javax.cache.CacheManager;
import javax.cache.Cache;
import com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider;
import com.github.benmanes.caffeine.jcache.configuration.CaffeineConfiguration;

Basic Usage

import javax.cache.Caching;
import javax.cache.CacheManager;
import javax.cache.Cache;
import javax.cache.configuration.MutableConfiguration;

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

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

// Basic cache operations
cache.put("key1", "value1");
String value = cache.get("key1");
boolean hasKey = cache.containsKey("key1");
cache.remove("key1");

Architecture

Caffeine JCache is built around several key components:

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

Capabilities

Service Provider Interface

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

public final class CaffeineCachingProvider implements CachingProvider {
    public CacheManager getCacheManager();
    public CacheManager getCacheManager(URI uri, ClassLoader classLoader);
    public CacheManager getCacheManager(URI uri, ClassLoader classLoader, Properties properties);
    public void close();
    public void close(ClassLoader classLoader);
    public void close(URI uri, ClassLoader classLoader);
    public boolean isSupported(OptionalFeature optionalFeature);
    public URI getDefaultURI();
    public ClassLoader getDefaultClassLoader();
    public Properties getDefaultProperties();
}

Service Provider Interface

Cache Management

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

public final class CacheManagerImpl implements CacheManager {
    public <K, V, C extends Configuration<K, V>> Cache<K, V> createCache(String cacheName, C configuration) throws IllegalArgumentException, CacheException, IllegalStateException;
    public <K, V> @Nullable Cache<K, V> getCache(String cacheName, Class<K> keyType, Class<V> valueType) throws IllegalArgumentException, ClassCastException, IllegalStateException;
    public <K, V> CacheProxy<K, V> getCache(String cacheName) throws IllegalArgumentException, IllegalStateException;
    public Collection<String> getCacheNames() throws IllegalStateException;
    public void destroyCache(String cacheName) throws IllegalStateException;
    public void enableManagement(String cacheName, boolean enabled) throws IllegalStateException;
    public void enableStatistics(String cacheName, boolean enabled) throws IllegalStateException;
    
    public CachingProvider getCachingProvider();
    public URI getURI();
    public @Nullable ClassLoader getClassLoader();
    public Properties getProperties();
    public void close();
    public boolean isClosed();
    public <T> T unwrap(Class<T> clazz) throws IllegalArgumentException;
}

Cache Management

Cache Operations

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

public class CacheProxy<K, V> implements Cache<K, V> {
    // Basic operations
    public @Nullable V get(K key);
    public Map<K, V> getAll(Set<? extends K> keys);
    public boolean containsKey(K key);
    public void put(K key, V value);
    public void putAll(Map<? extends K, ? extends V> map);
    public boolean putIfAbsent(K key, V value);
    
    // Atomic operations
    public @Nullable V getAndPut(K key, V value);
    public V getAndRemove(K key);
    public V getAndReplace(K key, V value);
    public boolean replace(K key, V oldValue, V newValue);
    public boolean replace(K key, V value);
    
    // Removal operations
    public boolean remove(K key);
    public boolean remove(K key, V oldValue);
    public void removeAll(Set<? extends K> keys);
    public void removeAll();
    public void clear();
    
    // Bulk and async operations
    public void loadAll(Set<? extends K> keys, boolean replaceExistingValues, 
                       CompletionListener completionListener);
    
    // Entry processing
    public <T> @Nullable T invoke(K key, EntryProcessor<K, V, T> entryProcessor, Object... arguments);
    public <T> Map<K, EntryProcessorResult<T>> invokeAll(Set<? extends K> keys, 
                                                         EntryProcessor<K, V, T> entryProcessor, 
                                                         Object... arguments);
    
    // Cache management
    public String getName();
    public CacheManager getCacheManager();
    public <C extends Configuration<K, V>> C getConfiguration(Class<C> clazz);
    public boolean isClosed();
    public void close();
    public <T> T unwrap(Class<T> clazz);
    public Iterator<Cache.Entry<K, V>> iterator();
}

Cache Operations

Configuration System

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

public final class CaffeineConfiguration<K, V> implements CompleteConfiguration<K, V> {
    // Constructors
    public CaffeineConfiguration();
    public CaffeineConfiguration(CompleteConfiguration<K, V> configuration);
    public CaffeineConfiguration<K, V> immutableCopy();
    
    // Type configuration
    public CaffeineConfiguration<K, V> setTypes(Class<K> keyType, Class<V> valueType);
    
    // Integration configuration
    public CaffeineConfiguration<K, V> setCacheLoaderFactory(Factory<? extends CacheLoader<K, V>> factory);
    public CaffeineConfiguration<K, V> setCacheWriterFactory(Factory<? extends CacheWriter<? super K, ? super V>> factory);
    public CaffeineConfiguration<K, V> setExpiryPolicyFactory(Factory<? extends ExpiryPolicy> factory);
    public CaffeineConfiguration<K, V> addCacheEntryListenerConfiguration(CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);
    public CaffeineConfiguration<K, V> removeCacheEntryListenerConfiguration(CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);
    
    // Behavior configuration
    public CaffeineConfiguration<K, V> setReadThrough(boolean isReadThrough);
    public CaffeineConfiguration<K, V> setWriteThrough(boolean isWriteThrough);
    public CaffeineConfiguration<K, V> setStoreByValue(boolean isStoreByValue);
    public CaffeineConfiguration<K, V> setStatisticsEnabled(boolean enabled);
    public CaffeineConfiguration<K, V> setManagementEnabled(boolean enabled);
    public CaffeineConfiguration<K, V> setNativeStatisticsEnabled(boolean enabled);
    
    // Caffeine-specific configuration
    public CaffeineConfiguration<K, V> setMaximumSize(OptionalLong maximumSize);
    public CaffeineConfiguration<K, V> setMaximumWeight(OptionalLong maximumWeight);
    public CaffeineConfiguration<K, V> setExpireAfterWrite(OptionalLong expireAfterWriteNanos);
    public CaffeineConfiguration<K, V> setExpireAfterAccess(OptionalLong expireAfterAccessNanos);
    public CaffeineConfiguration<K, V> setRefreshAfterWrite(OptionalLong refreshAfterWriteNanos);
    
    // Factory configuration
    public CaffeineConfiguration<K, V> setWeigherFactory(Optional<Factory<? extends Weigher<K, V>>> factory);
    public CaffeineConfiguration<K, V> setExpiryFactory(Optional<Factory<? extends Expiry<K, V>>> factory);
    public CaffeineConfiguration<K, V> setCopierFactory(Factory<Copier> factory);
    public CaffeineConfiguration<K, V> setSchedulerFactory(Factory<Scheduler> factory);
    public CaffeineConfiguration<K, V> setTickerFactory(Factory<Ticker> factory);
    public CaffeineConfiguration<K, V> setExecutorFactory(Factory<Executor> factory);
}

Configuration System

Event Handling

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

public final class EventDispatcher<K, V> {
    public void register(CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);
    public void deregister(CacheEntryListenerConfiguration<K, V> cacheEntryListenerConfiguration);
    public void publishCreated(Cache<K, V> cache, K key, V value);
    public void publishUpdated(Cache<K, V> cache, K key, V oldValue, V newValue);
    public void publishRemoved(Cache<K, V> cache, K key, V value);
    public void publishExpired(Cache<K, V> cache, K key, V value);
    public void awaitSynchronous();
    public void ignoreSynchronous();
    public List<Registration<K, V>> registrations();
}

public final class Registration<K, V> {
    public CacheEntryListener<? super K, ? super V> getCacheEntryListener();
    public CacheEntryFilter<? super K, ? super V> getCacheEntryFilter();
    public CacheEntryListenerConfiguration<K, V> getConfiguration();
    public boolean matches(EventType eventType);
}

Event Handling

Management and Monitoring

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

public final class JCacheStatisticsMXBean implements CacheStatisticsMXBean {
    public long getCacheHits();
    public long getCacheMisses();
    public long getCacheGets();
    public long getCachePuts();
    public long getCacheRemovals();
    public long getCacheEvictions();
    public float getAverageGetTime();
    public float getAveragePutTime();
    public float getAverageRemoveTime();
    public float getCacheHitPercentage();
    public float getCacheMissPercentage();
}

public final class JCacheMXBean implements CacheMXBean {
    // Management operations
}

public final class JmxRegistration {
    public static void registerMxBean(Cache<?, ?> cache, Object mxBean, MBeanType mBeanType);
    public static void unregisterMxBean(Cache<?, ?> cache, MBeanType mBeanType);
}

Management and Monitoring

Integration Features

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

public final class JCacheLoaderAdapter<K, V> implements CacheLoader<K, Expirable<V>> {
    public Expirable<V> load(K key) throws Exception;
    public Map<K, Expirable<V>> loadAll(Iterable<? extends K> keys) throws Exception;
}

public interface Copier {
    public <T> T copy(T object, ClassLoader classLoader);
    public static Copier identity();
}

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

public final class EntryProcessorEntry<K, V> implements MutableEntry<K, V> {
    public K getKey();
    public V getValue();
    public boolean exists();
    public void remove();
    public void setValue(V value);
    public <T> T unwrap(Class<T> clazz);
}

Integration Features