Fork me on GitHub

cache2k 1.2.0.Final - Loch Lomond

cache2k is a high performance and light weight in-process caching library. Compared to other libraries (EHCache, Guava and Caffeine) it achieves the highest throughput for cache hits while still providing one of the best eviction efficiency. Advanced features of cache2k, like refresh ahead and resilience can solve typical application problems with ease.

Highlights of the new version: Spring Framework integration, optimized footprint on Android with provided ProGuard rules, performance and initialization improvements in JCache to optimize the use as L2 cache in Hibernate or Datanucleus.

This change log lists the complete changes since the last stable version 1.0.2.Final.

New and Noteworthy

  • Support for Spring caching abstraction. See the user guide on Spring Framework Integration
  • cache2k is now delivered in two jar files, cache2k-api contains the API and cache2k-core the implementation. Both jar files need to be present at runtime. GH#80
  • Optimized cache version for integer keys with better memory footprint and access performance since no autoboxing is needed.
  • XML configuration becomes XSD schema, also some structural changes and improvements
  • JCache speedup: Don’t copy values or allow listener attachment if this is not needed. This improves speed when used as L2 cache in Hibernate or Datenucleus.

API Changes

  • IntCache and LongCache for int and long keys, plus IntKeyValueSource and LongKeyValueSource
  • Cache2kBuilder.getManager() returns the cache manager
  • Add CacheManager.getConfiguredCacheNames to get a list of caches that are specified in the XML configuration

API Changes and Potential breakages

Below changes affect potentially existing applications. The version 1.2 is not strictly binary compatible.

  • Cache.computeIfAbsent propagates RuntimeException without wrapping
  • Renaming of method on MutableCacheEntry: setExpiry to setExpiryTime
  • JMX support is not enabled by default any more. It can be enabled per cache or globally, see the Statistics - cache2k Use Guide
  • improve generic type parameters in configuration classes, affected: Cache2kConfiguration.setKeyType, Cache2kConfiguration.setValueType, CacheType
  • CacheEntry.getLastModifiedTime is not supported any more. Permanently throws exception, see: CacheEntry.getLastModifications - cache2k API documentation Alternative method is via: MutableCacheEntry.getRefreshedTime()
  • Cache2kBuilder.disableLastModificationTime: deprecated, has no effect
  • ConfigurationSectionContainer: Implements collection interface, method add returns a boolean.
  • XML configuration: scopes are lower case, structual changes, see below and the examples


  • Cache.replaceIfEquals: Fix potential NPE, if listener or writer is used
  • Cache.removeIfEquals statistics: count miss and hit consistently
  • NPE in Cache.putAll when used with ConcurrentHashMap, GH#90


  • Rename jar cache2k-all to cache2k-osgi-all. This contains a bundle of the cache2k-api and cache2k-core jar file and is kept for OSGi environments only. This special variant is likely to be dropped in the future, see: GH#83. This combined jar should not be used any more to avoid potential duplication in the class path.
  • cache2k-core: Code for XML configuration or JMX support is included but can be removed (e.g. via ProGuard rules) if not needed
  • consolidate the output of the cache coordinates in the toString outputs
  • CacheManager: add toString() output
  • change timer implementation, faster operation when expiry is used
  • Introduce simulated clock and improve test coverage for timing related features
  • Improve timer robustness by changing thread priorities
  • Code quality: Unused code removed
  • Rename thread prefix for async listener execution from cache2k-async to cache2k-listener
  • throws IllegalStateException if cache with identical name already is created
  • Cache2kConfiguration.isExternalConfigurationPresent is now true if there is an XML default configuration
  • Default configuration and class loaders: hold separate default configuration per class loader
  • Cache2kConfiguration: add setters for collections (listeners and sections) to better integrate with other generic configuration code like Springs’ bean XML configuration.
  • Change ConfigurationException source location message to standard, like (cache2k.xml:123) direct highlighting and click in IntelliJ works
  • XML configuration: Default value in variables: E.g. ${env.CACHE_SIZE:-2000}, uses the environment variable or 2000 if not present
  • XML configuration: No element <users> in the <properties>
  • XML configuration: <parameters> element for bean values to the customizer suppliers
  • XML configuration: The scope for the system properties is renamed from prop to sys.
  • XML configuration: A variable without scope (e.g. ${xy}) refers to the properties section in the configuration file
  • XML configuration: Variable (e.g. env and sys) scopes in the configuration are changed to lower case
  • JCache speedup: Do not support online listener attachment by default if in cache2k configuration mode. See JCache Optimizations and Semantics - cache2k Use Guide
  • JCache: If a cache is present in the XML configuration CacheManager.getCache creates the cache based on the present configuration. Some clients (e.g. Spring) use CacheManager.getCache to request an exiting/known cache.
  • JCache: ignore isWriteThrough flag and just use the writer when present. This avoids an NPE if a cache client enables write through but does not provide a writer, which is an illegal configuration (found in Datanucleus).
  • JCache and XML configuration: allow expireAfterWrite to be configured via XML
  • JCache configuration: switch to cache2k semantics whenever a cache2k configuration file is present (before either a default or cache section needed to be present)
  • JCache: print useful toString() output for a JCache cache, delegates to the underlying cache2k cache
  • JCache: clarify manager URIs and improve exception text GH#91

Using this cache2k version

The binaries are available on maven central.

For Java SE/EE and Android environments

For Maven users:


Recommended for Gradle users:

def cache2kVersion = '1.2.0.Final'

dependencies {
    implementation "org.cache2k:cache2k-api:${cache2kVersion}"
    runtimeOnly "org.cache2k:cache2k-core:${cache2kVersion}"

Note to Android users: The included jar files contain code that might only be needed in server environments (e.g. JMX support). It is possible to strip unnecessary code. Example ProGuard rules can be found at Andriod - cache2k User Guide

Using the JCache / JSR107 provider

Maven users include the cache2k JCache provider this way:


For Gradle users:

dependencies {
    runtimeOnly "org.cache2k:cache2k-jcache:1.2.0.Final"

Implementation details, tuning tips and hints on configuration can be found at: JCache - cache2k User Guide