refcard cover
Refcard #216

Java Caching

Strategies and the JCache API

Explores the building blocks of JCache and other caching APIs, as well as multiple strategies for implementing temporary data storage in your application.

Free PDF for Easy Reference
refcard cover

Written By

author avatar Abhishek Gupta
Cloud Developer Advocate, Microsoft
Section 1


What Is Caching?

Generally speaking, caching is a technique wherein objects in your application are stored in a temporary storage area known as a cache. The cache itself can be thought of as an in-memory data structure. Cached objects could be anything from the results of expensive and time-consuming operations, to static webpages or the contents of your backend database. Caching insulates your application from the requirement of fetching the same information (from any data source) or executing the same expensive calculation repeatedly, by storing to and fetching from an intermediate cache when required.

Caching provides several benefits, which is why it is heavily leveraged in use cases where fast access to data is required. Proper caching can improve performance, decrease resource usage, and increase responsiveness.

Typically, in an enterprise application, the cache acts as an intermediate, low-latency data source and sits between the application and the backend systems.

Note:This is a rather simplistic representation to get you started. We will cover more involved architectural topologies in detail later.

Caching Architecture Example

Section 2

Java Caching Landscape

The Java ecosystem has had solid support for caching solutions with several products and frameworks available to choose from. Some widely used solutions are:

  • Hazelcast
  • Oracle Coherence
  • Infinispan
  • Ehcache
  • Apache Ignite
  • GridGain
  • GemFire

In order to create a standard set of APIs to abstract over these heterogeneous caching solutions, JSR 107: Java Temporary Caching API was initiated.

Section 3

JCache API (JSR 107)

What Is JCache?

JCache is a Java API for caching. It provides a set of common interfaces and classes that can be used to temporarily store Java objects in memory. It is a JCP standard represented by JSR 107. It is one of the longest-running JSRs in the history of the JCP—starting with its inception in 2001 and ending with its final release in March 2014.

The JCache API is implemented by different vendors (a.k.a. caching providers), but the manner in which client code accesses it is via a standard set of interfaces and classes that it exposes.

Why JCache?

Caching is not a new concept in the Java world—or even in general. As already mentioned, there are several enterprise- grade caching solutions already available—so why would you choose JCache over a specific vendor/product that you are already using in your applications?

There are two primary benefits:

Portability: JCache allows you to use a standard API in your client applications, decoupling them from the actual vendor implementation. This in turn makes your application portable between various JCache implementations.

Developer Productivity: Developers can leverage the common set of JCache APIs and interfaces without concerning themselves with vendor-specific details. This ensures that the learning curve is smaller since it is restricted to the knowledge of JCache as a standard and not the specifics of a vendor implementation.

What About Vendor-Specific Features?

JCache allows the use of equivalent vendor APIs corresponding to a specific JCache interface/class. This will be discussed in detail in the upcoming sections.

Section 4

JCache Deep Dive

Basic Building Blocks

Here is a simple code snippet to get you started. The details will be explored in upcoming sections.

CachingProvider cachingProvider = Caching. getCachingProvider();
CacheManager cacheManager = cachingProvider. getCacheManager();
MutableConfiguration<String, String> config = new MutableConfiguration();
Cache<String, String> cache = cacheManager. createCache("JDKCodeNames",config);
String jdk7CodeName = cache.get("JDK1.7");


A javax.cache.Cache is a type-safe data structure that allows applications to store data temporarily (as key-value pairs). Its semantics are similar to a java.util.Map object, but it is not exactly the same as a Map.

The Cache interface exposes several features via its API, but some of the basic ones are listed in the following table:



put , putAll

Adds entries (key-value pairs) to a cache


Checks if an entry with a key exists in the cache

get , getAll

Gets value(s) corresponding to key(s)


Substitutes an existing value for a key with another value

remove , removeAll

Removes one or all entries from a cache


As its name indicates, the javax.cache.Entry represents a key-value pair in a cache. As conveyed earlier, there can be multiple such entries in a cache. An entry is a simple entity that exposes bare minimum operations, such as fetching the key and value via the getKey and getValue methods respectively.


The javax.cache.CacheManager interface helps deal with cache objects and executes operations like cache creation, destruction, and introspection (fetching relevant details about itself). Let’s look at some of the common operations:




Create a cache


Destroy a cache

getCache (and its overloaded forms)

Search for a (possibly) existing cache

getProperties, getURI, isClosed, getClassLoader, etc.

Provide information about the cache


Part of the JCache SPI, the javax.cache.spi.CachingProvider provides methods that allow applications to manage CacheManager instances.



getCacheManager (and its overloaded versions)

Create CacheManager instance

close (and its overloaded versions)

Destroy/close CacheManager instance

getDefaultClassLoader, getDefaultProperties, getDefaultURI, isSupported

Obtain information about the CachingProvider


This class is used to obtain a handle to a javax.cache.CacheProvider object via getCachingProvider and its overloaded versions.

Note:There are other ways in which the CachingProvider might be obtained.

Apart from this, the Caching class also provides other capabilities as noted in the following table:




Provides a list of all CachingProvider instances


Allows the client code to search for a javax.cache.Cache object using its name

JCache Architecture

Section 5

API Overview

It’s good to think of JCache as a set of modules, with each module delivering a specific feature. The JCache API is so split up that it’s easy and intuitive to explore it in this manner.







Expiration Policies


Listeners and Filters




External Resource Integration









The APIs introduced in the Basic Building Blocks section form the bulk of what we can call the core of JCache, since these classes/interfaces (and their respective provider implementations) are fundamental to the API.


The JCache API offers a standard set of interfaces and implementations with which one can configure a cache programmatically. The javax.cache.configuration.MutableConfiguration and its builder-like API aids in the configuration.

The following cache characteristics can be configured:




Data types to be stored in the Cache


Store by reference or value


Expiration Policy

setReadThrough, setWriteThrough

Read through and Write through policies

setCacheLoaderFactory, setCacheWriterFactory

Loader and Writer implementation


Entry Listener implementation

setManagementEnabled, setStatisticsEnabled

Management and statistics activation

MutableConfiguration<String,String> config = new MutableConfiguration();

Expiration Policies

As the name suggests, an expiry policy can be enforced on a cache, which would determine auto-eviction or removal of entries from your cache as per the policy semantics.

Note:By default, the entries in a javax.cache.Cache do not expire.

The expiry policies provided by the JCache API revolve around the javax.cache.expiry.ExpiryPolicy interface and its ready-to-use implementations.




Based on time of last access


Based on creation time


Ensures the cache entries never expire (default expiry policy)


Based on time of last update


Based on time of last access OR update

MutableConfiguration<String,String> config = new MutableConfiguration();

Listeners and Filters

Cache event listeners allow client code to register callbacks against the cache events they might be interested in. javax.cache.event.CacheEntryListener acts as a (parent) marker interface for other interfaces that provide a contract (method) which can be implemented in order to react to a specific event in the cache. These are typically single abstract methods, which makes them perfectly suitable for Java 8 lambda-style implementation.

JCache also has filters, which help determine whether or not to call the cache listeners. This comes in handy when you want to selectively dispatch calls to cache listeners based on certain conditions.
















CacheEntryCreatedListener<Long,TicketDetails> newTicketCreationListener = (cacheEntries) -> {
for(CacheEntryEvent ticketCreatedEvent : cacheEntries){
System.out.println(“Ticket ID: “ + ticketCreatedEvent.getKey());
System.out.println(“Ticket Details: “ + ticketCreatedEvent.getValue().toString());
CacheEntryEventFilter<Long,TicketDetails> entryEventFilter = (event) -> event.getSource().getName().equals(“TicketsCache”);

External Resource Integration

The JCache API supports cache loaders and cache writers, which help integrate the cache with external resources. A read-through operation is accomplished with the help of a javax.cache. CacheLoader implementation (which is automatically invoked if a key is not found in the cache) that retrieves the value for the corresponding key from an external source. Similarly, a javax. cache.CacheWriter implementation synchronizes an external source in response to updates and removal of entries in the cache.





CacheLoader [load, loadAll]



CacheWriter [delete, deleteAll, write, writeAll]


public class TicketCacheLoaderWriter implements CacheLoader<Long, TicketDetails>, CacheWriter<Long, TicketDetails>{

public TicketDetails load(Long ticketID) throws CacheLoaderException {
return getTicketDetails(ticketID); }

public Map<Long, TicketDetails> loadAll(Iterable<? extends Long> ticketIDs) throws CacheLoaderException {
Map<Long, TicketDetails> tickets = new HashMap<>();
for(Long ticketID : ticketIDs){
tickets.put(ticketID, getTicketDetails(ticketID));
return Collections.unmodifiableMap(tickets); }

  private TicketDetails getTicketDetails(Long ticketID){
TicketDetails details = null;
//business logic to fetch ticket information
return details; }

public void write(Cache.Entry<? extends Long, ? extends TicketDetails> ticketEntry) throws CacheWriterException{
writeTicketDetails(ticketEntry.getKey(), ticketEntry.getValue());}

public void writeAll(Collection<Cache.Entry<? extends Long, ? extends TicketDetails>> ticketEntries) throws CacheWriterException {
for(Cache.Entry ticketEntry : ticketEntries){
          writeTicketDetails((Long) ticketEntry.getKey(), (TicketDetails) ticketEntry.getValue());}

public void delete(Object ticketID) throws CacheWriterException {
deleteTicket((Long) ticketID); }

public void deleteAll(Collection<?> ticketIds) throws CacheWriterException {
for(Object ticketID : ticketIds){
deleteTicket((Long) ticketID); }

private void writeTicketDetails(Long ticketID, TicketDetails ticketDetails){
//business logic to delete ticket information

  private void deleteTicket(Long ticketID){

Cache Entry Processing

An entry processor is particularly useful when your cache is distributed (which is quite often the case) over multiple nodes (JVMs). In order to update an existing entry in the cache, one might follow the default set of steps:

  • Get the value from the cache
  • Mutate/update it
  • Put the updated value back into the cache

While this is perfectly normal, it is not efficient in terms of performance (especially when the cache values are large). The caching provider has to de-serialize the cache value from one of the many nodes to the client and then send the updated (and serialized) version back to the cache. The problem is magnified if multiple such calls are made in succession. Entry processors allow the client to apply a transformation on the cache entry by sending it over to the cache node rather than fetching the entry from the cache and then mutating it locally. This significantly reduces the network traffic as well as serialization/de-serialization expenses. All you need to do is define/implement the entry processor represented by the javax.cache.EntryProcessor interface and specify the same during the Cache.invoke or Cache.invokeAll methods.





javax.cache. EntryProcessor

Invoked as a result of calling Cache.invoke or Cache.invokeAll


javax.cache. EntryProcessorResult

Part of the Map returned by the Cache.invokeAll method (one for each key). It wraps the result returned by the entry processor


JCache annotations (in the javax.cache.annotation package) help you treat caching operations as aspects (from an aspect-oriented paradigm perspective). These annotations allow the client code to specify caching requirements in a declarative fashion. Note that the efficacy of these annotations is dependent on an external framework (like CDI, Guice, etc.), which can process these and execute the required operations.

By default, JCache exposes a limited number of caching operations via annotations, but they are useful nonetheless.




Searches the cache for a key (the method parameter), invokes the method if the value cannot be found, and caches the same for future invocations


Executes a cache put with key and value in the method parameters


Removes a cache entry by using the key specified in the method parameter


Removes ALL cache entries

Note:The above-mentioned annotations are applicable on a class (which essentially enforces them for all the methods in that class) or for one or more method(s).

There are also three auxiliary annotations worth mentioning:




Helps specify default configurations for aforementioned annotations. Applicable for a class


Used to explicitly specify a method parameter as a cache key


Used to explicitly specify a method parameter as a cache value when using the @CachePut annotation

public class TicketingService{

public void persistTicket(long ticketID, @CacheValue TicketDetails details){
//domain logic to persist ticket information

public TicketDetails findTicket(@CacheKey long ticketID){
TicketDetails details = null;
//execute domain logic to find ticket information
return details;

public void deleteTicket(@CacheKey long ticketID){
//domain logic to delete ticket information

public void deleteAllTickets(){
    //domain logic to delete ticket information


JCache provides MBean interfaces whose implementations expose cache configuration and runtime performance monitoring related statistics. These statistics can be tracked through any JMX client or through the javax.management.MBeanServer API (programmatic).





getKeyType, getValueType, isManagementEnabled, isReadThrough, isStatisticsEnabled, isStoreByValue, isWriteThrough


CacheStatistics MXBean

Clear, getAverageGetTime, getAveragePutTime, getAverageRemoveTime, getCacheEvictions, getCacheGets, getCacheHitPercentage, getCacheHits, getCacheMisses, getCacheMissPercentage, getCachePuts, getCacheRemovals


MutableConfiguration<String,String> config = new MutableConfiguration();


The javax.cache.spi package consists of a single interface: CachingProvider. We have already looked at the specific details of this class, but let’s understand it from a JCache vendor perspective.

A JCache provider implements this interface, and for it to be auto- discoverable, the full qualified class name of the concrete class is declared in META-INF/services/javax.cache.spi.CachingProvider—it must be available in the class path. Generally, this is packaged in the vendor implementation JAR itself. So you can think of this interface as the gateway to your JCache provider.

CacheManager cacheManager = Caching. getCachingProvider(“com.hazelcast.cache.impl.HazelcastCachingProvider”).getCacheManager();
CacheManager cacheManager = Caching. getCachingProvider(“com.tangosol.coherence.jcache.CoherenceBasedCachingProvider”).getCacheManager(); 

Best of Both Worlds: Using Vendor-Specific Features Along With JCache

By now I am sure you understand that JCache (JSR 107) is just a standard set of APIs that are implemented by different vendors. The standard JCache APIs provide you with a hook to tap into the concrete vendor-specific implementation itself—you can do so using the unwrap method. Let’s look at the details in the table below.

Note: This is obviously not recommended if true CachingProvider portability is what you are looking for since your application would be directly coupled to vendor-specific APIs.





javax.cache. CacheManager

Get a handle to
the CacheManager implementation of a provider


Get a handle to the Cache implementation of a provider


Get a handle to the Cache.Entry implementation of a provider

javax.cache.annotation. CacheInvocationContext

Get a handle to the CacheInvocationContext implementation of a provider

//Hazelcast specific example
ICache<String,String> hazelcastICache = cache. unwrap(ICache.class); 

The Hazelcast ICache extension for JCache provides lots of value added features. It’s not possible to discuss all of them in detail, but here are some of the important ones:

Asynchronous Operations: The ICache extension exposes asynchronous equivalents for most of the JCache operations like get, put, putIfAbsent, etc.

Near Cache: This feature allows Hazelcast clients (via explicit configuration) to store data locally rather than reaching out to remote Hazelcast cluster, thus reducing latency and network traffic.

Section 6

Caching Strategies

Caching strategies are methodologies one might adopt while implementing a caching solution as part of an application. The drivers/use cases behind the requirement of a caching layer vary based on the application’s requirements.

Let’s look at some of the commonly adopted caching strategies and how JCache fits into the picture. The following table provides a quick snapshot followed by some details:

Cache Topology

Which caching topology/setup is best suited for your application? Does your application need a single-node cache or a collaborative cache with multiple nodes?


From a specification perspective, JCache does not include any details or presumptions with regards to the cache topology.

Standalone: As the name suggests, this setup consists of a single node containing all the cached data. It’s equivalent to a single- node cluster and does not collaborate with other running instances.

Distributed: Data is spread across multiple nodes in a cache such that only a single node is responsible for fetching a particular entry. This is possible by distributing/partitioning the cluster
in a balanced manner (i.e., all the nodes have the same number of entries and are hence load balanced). Failover is handled via configurable backups on each node.

Replicated: Data is spread across multiple nodes in a cache such that each node consists of the complete cache data, since each cluster node contains all the data; failover is not a concern.

Cache Modes

Do you want the cache to run in the same process as your application, or would you want it to exist independently (as-a- service style) and execute in a client-server mode?


JCache does not mandate anything specific as far as cache modes are concerned. It embraces these principles by providing flexible APIs that are designed in a cache-mode agnostic manner.

The following modes are common across caches in general:

Embedded mode: When the cache and the application co-exist within the same JVM, the cache can be said to be operating in embedded mode. The cache lives and dies with the application JVM. This strategy should be used when:

  • Tight coupling between your application and the cache is not a concern
  • The application host has enough capacity (memory) to accommodate the demands of the cache

Client-Server mode: In this setup, the application acts as the client to a standalone (remote) caching layer. This should be leveraged when:

  • The caching infrastructure and application need to evolve independently
  • Multiple applications use a unified caching layer which can be scaled up without affecting client applications

Multiple Combinations to Choose From

Different cache modes and topologies make it possible to have multiple options to choose from, depending upon specific requirements.

Standalone Embedded Cache: A single cache node within the same JVM as the application itself Standalone Embedded CacheDistributed Embedded Cache: Multiple cache (clustered) nodes, each of which is co-located within the application JVM and is responsible for a specific cache entry only

Replicated Embedded Cache: Multiple cache (clustered) nodes, each of which is co-located within the application JVM; here the cached data is replicated to all the nodesDistributed or Replicated Embedded CacheStandalone Client-Server Cache: A single cache node running as a separate process than that of the applicationStandalone Client-Server CacheDistributed Client-Server Cache: Multiple cache (clustered) nodes, collaborating in a distributed fashion and executing in isolation from the client application

Replicated Client-Server Cache: Multiple cache (clustered) nodes, where the entire cache data copy is present on each node, and the cache itself is run as a separate process than that of the application Distributed or Replicated Client-Server Cache

Transparent Cache Access

You are designing a generic caching layer for heterogeneous applications. Ideally, you would want your application to access the cache transparently without polluting its core logic with the specifics of the caching implementation.


As already stated in the JCache Deep Dive section, integration to external systems—like databases, file stores, LDAP, etc.— is already abstracted via the CacheLoader and CacheWriter mechanisms, which help you implement Read-Through and Write-Through strategies respectively.

Read-Through: A process by which a missing cache entry is fetched from the integrated backend store.

Write-Through: A process by which changes to a cache entry (create, update, delete) are pushed into the backend data store.

It is important to note that the business logic for Read-Through and Write-Through operations for a specific cache are confined within the caching layer itself. Hence, your application remains insulated from the specifics of the cache and its backing system-of-record.

Other Strategies (Non-JCache)

Write-Behind: This strategy leverages a more efficient approach wherein the cache updates are batched (queued) and asynchronously written to the backend store instead of an eager and synchronous policy adopted by the Write-Through strategy. For example, Hazelcast supports the Write-Behind strategy via its com.hazelcast.core. MapStore interface when the write-delay-seconds configuration property is greater than 0. Please note that this is purely a Hazelcast Map feature and is not supported through ICache extension.

Refresh-Ahead: This is another interesting strategy where a caching implementation allows you to refresh the cache data from the backend store depending upon a specific factor, which can be expressed in terms of an entry’s expiration time. The reload process is asynchronous in nature. For example, Oracle Coherence supports this strategy, which is driven by a configuration element known as the refresh-ahead factor, which is a percentage of the expiration time of a cache entry.

Cache Data Quality

Cache expiry/eviction policies are vital from a cache data quality perspective. If a cache is not tuned to expire its contents, then it will not get a chance to refresh/reload/sync up with its master repo/system-of-record and might end up returning stale or outdated data.

You need to ensure that the caching implementation takes into account the data volatility in the backing data store (behind the cache) and effectively tune your cache to maintain quality data.


In the JCache Deep Dive section, you came across the default expiry policies available in JCache—AccessedExpiryPolicy, CreatedExpiryPolicy, EternalExpiryPolicy, ModifiedExpiryPolicy, and TouchedExpiryPolicy. In addition to these policies, JCache allows you to implement custom eviction policies by implementing the javax.cache.expiry.ExpiryPolicy interface.

Flexi-Eviction (Non-JCache)

The JCache API allows you to enforce expiry policies on a specific cache; as a result, it is applicable to all the entries in that cache. With the Hazelcast JCache implementation, you can fine-tune this further by providing the capability to specify the ExpiryPolicy per entry in a cache. This is powered by the com.hazelcast.cache.ICache interface.

ICache<String,String> hazelcastICache = cache. unwrap(ICache.class);
hazelcastICache.put(“key2”, “value2”, new TouchedExpiryPolicy(Duration.FIVE_MINUTES));

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}