Greg Luck's Blog

This post explores the new Java caching standard: javax.cache.

How it Fits into the Java Ecosystem

This standard is being developed by JSR107, of which the author is co-spec lead. JSR107 is included in Java EE 7, being developed by JSR342. Java EE 7 is due to be finalised at the end of 2012. But in the meantime javax.cache will work in Java SE 6 and higher and Java EE 6 environments as well aswith Spring and other popular environments.

JSR107 has draft status. We are currently at release 0.3 of the API, the reference implementation and the TCK. The code samples in this article work against this version.

Adoption

Vendors who are either active members of the expert group or have expressed interest in implementing the specification are:

• Terracotta – Ehcache
• Oracle – Coherence
• JBoss – Infinispan
• IBM – ExtemeScale
• SpringSource – Gemfire
• GridGain
• TMax
• Google App Engine Java

Terracotta will be releasing a module for Ehcache to coincide with the final draft and then updating that if required for the final version.

Features

From a design point of view, the basic concepts are a CacheManager that holds and controls a collection of Caches. Caches have entries. The basic API can be thought of map-­like with the following additional features:

• atomic operations, similar to java.util.ConcurrentMap
• read-through caching
• write-through caching
• cache event listeners
• statistics
• transactions including all isolation levels
• caching annotations
• generic caches which hold a defined key and value type
• definition of storage by reference (applicable to on heap caches only) and storage by value

Optional Features

Rather than split the specification into a number of editions targeted at different user constituencies such as Java SE and Spring/EE, we have taken a different approach.

Firstly, for Java SE style caching there are no dependencies. And for Spring/EE where you might want to use annotations and/or transactions, the dependencies will be satisfied by those frameworks.

Secondly we have a capabilities API via ServiceProvider.isSupported(OptionalFeature feature)so that you can determine at runtime what the capabilities of the implementation are.  Optional features are:

• storeByReference – storeByValue is the default
• transactional
• annotations

This makes it possible for an implementation to support the specification without necessarily supporting all the features, and allows end users and frameworks to discover what the features are so they can dynamically configure appropriate usage.

Good for Standalone and Distributed Caching

While the specification does not mandate a particular distributed cache topology it is cognizant that caches may well be distributed. We have one API that covers both usages but it is sensitive to distributed concerns. For example CacheEntryListener has a NotificationScope of events it listens for so that events can be restricted to local delivery. We do not have high network cost map-like methods such as keySet() and values(). And we generally prefer zero or low cost return types. So while Map has V put(K key, V value) javax.cache.Cache has void put(K key, V value).

Classloading

Caches contain data shared by multiple threads which may themselves be running in different container applications or OSGi bundles within one JVM and might be distributed across multiple JVMs in a cluster. This makes classloading tricky.

We have addressed this problem. When a CacheManager is created a classloader may be specified. If none is specified the implementation provides a default. Either way object de-serialization will use the CacheManager’s classloader.

This is a big improvement over the approach taken by caches like Ehcache that use a fall-back approach. First the thread’s context classloader is used and it that fails, another classloader is tried. This can be made to work in most scenarios but is a bit hit and miss and varies considerably by implementation.

Getting the Code

The spec is in Maven central. The Maven snippet is:

<dependency>

     <groupId>javax.cache</groupId>

     <artifactId>cache-api</artifactId>

     <version>0.3</version>

</dependency>

A Cook’s Tour of the API

Creating a CacheManager

We support the Java 6 java.util.ServiceLoader creational approach. It will automaticaly detect a cache implementation in your classpath. You then create a CacheManager with:

CacheManager cacheManager = Caching.getCacheManager();

which returns a singleton CacheManager called “__default__”. Subsequent calls return the same CacheManager.

CacheManagers can have names and classloaders configured in. e.g.

CacheManager cacheManager = Caching.getCacheManager(“app1”, Thread.currentThread().getContextClassLoader());

Implementations may also support direct creation with new for maximum flexibility:

CacheManager cacheManager = new RICacheManager(“app1”, Thread.currentThread().getContextClassLoader());

Or to do the same thing without adding a compile time dependency on any particular implementation:

String className = "javax.cache.implementation.RIServiceProvider";

Class<ServiceProvider> clazz =(Class<ServiceProvider>)Class.forName(className);

ServiceProvider provider = clazz.newInstance();

return provider.createCacheManager(Thread.currentThread().getContextClassLoader(), "app1");

We expect implementations to have their own well-known configuration files which will be used to configure the CacheManager. The name of the CacheManager can be used to distinguish the configuration file. For ehcache, this will be the familiar ehcache.xml placed at the root of the classpath with a hyphenated prefix for the name of the CacheManager. So, the default CacheManager will simply be ehcache.xml and “myCacheManager” will be app1-ehcache.xml.

Creating a Cache

The API supports programmatic creation of caches. This complements the usual convention of configuring caches declaratively which is left to each vendor.

To programmatically configure a cache named “testCache” which is set for read-through

cacheManager = getCacheManager();

CacheConfiguration cacheConfiguration = cacheManager.createCacheConfiguration()

cacheConfiguration.setReadThrough(true);

Cache testCache = cacheManager.createCacheBuilder(“testCache”)

.setCacheConfiguration(cacheConfiguration).build();

Getting a reference to a Cache

You get caches from the CacheManager. To get a cache called “testCache”:

Cache<Integer, Date> cache = cacheManager.getCache(“testCache”);

Basic Cache Operations

To put to a cache:

Cache<Integer, Date> cache = cacheManager.getCache(cacheName);

Date value1 = new Date();

Integer key = 1;

cache.put(key, value1);

To get from a cache:

Cache<Integer, Date> cache = cacheManager.getCache(cacheName);

Date value2 = cache.get(key);

To remove from a cache:

Cache<Integer, Date> cache = cacheManager.getCache(cacheName);

Integer key = 1;

cache.remove(key);

Annotations

JSR107 introduces a standardised set of caching annotations, which do method level caching interception on annotated classes running in dependency injection containers. Caching annotations are becoming increasingly popular, starting with Ehcache Annotations for Spring, which then influenced Spring 3’s caching annotations.

The JSR107 annotations cover the most common cache operations including:

• @CacheResult – use the cache
• @CachePut – put into the cache
• @CacheRemoveEntry – remove a single entry from the cache
• @CacheRemoveAll – remove all entries from the cache

When the required cache name, key and value can be inputed they are not required. See the JavaDoc for the details. To allow greater control, you can specify all these and more. In the following example, the cacheName attribute is specified to be “domainCache”, index is specified as the key and domain as the value.

public class DomainDao {

     @CachePut(cacheName="domainCache")

     public void updateDomain(String domainId, @CacheKeyParam int index,

          @CacheValue Domain domain) {

     ...

     }

}

The reference implementation includes an implementation for both Spring and CDI. CDI is the standardised container driven injection introduced in Java EE 6. The implementation is nicely modularised for reuse, uses an Apache license, and we therefore expect several open source caches to reuse them. While we have not done an implementation for Guice, this could be easily done.

Annotation Example

This example shows how to use annotations to keep a cache in sync with an underlying data structure, in this case a Blog manager, and also how to use the cache to speed up responses, done with @CacheResult

public class BlogManager {

@CacheResult(cacheName="blogManager")

public Blog getBlogEntry(String title) {...}

@CacheRemoveEntry(cacheName="blogManager")

public void removeBlogEntry(String title) {...}

@CacheRemoveAll(cacheName="blogManager")

public void removeAllBlogs() {...}

@CachePut(cacheName=”blogManager”)

public void createEntry(@CacheKeyParam String title,

@CacheValue Blog blog) {...}

@CacheResult(cacheName="blogManager")

public Blog getEntryCached(String randomArg,

@CacheKeyParam String title){...}

}

Wiring Up Spring

For Spring the key is the following config line, which adds the caching annotation interceptors into the Spring context:

<jcache-spring:annotation-driven proxy-target-class="true"/>

A full example  is:

<beans ...>

<context:annotation-config/>

<jcache-spring:annotation-driven proxy-target-class="true"/>

<bean id="cacheManager" factory-method="getCacheManager" />

</beans>

Spring has it’s own caching annotations based on earlier work from JSR107 contributor Eric Dalquist. Those annotations and JSR107 will happily co-exist.

Wiring Up CDI

First create an implementation of javax.cache.annotation.BeanProvider and then tell CDI where to find it  declaring a resource named javax.cache.annotation.BeanProvider in the classpath at /META-INF/services/.

For an example using the Weld implementation of CDI, see the CdiBeanProvider in our CDI test harness.

Further Reading

For further reading visit the JSRs home page at https://github.com/jsr107/jsr107spec.