Skip navigation links
 

Package javax.cache

This package contains the API for JCache. JCache describes the technique whereby Java developers use a CachingProvider to temporarily cache Java objects. It provides a common way for Java programs to create, access, update and remove entries from caches.

Core Concepts

The Java Caching API defines five core interfaces: CachingProvider, CacheManager, Cache, Cache.Entry and ExpiryPolicy.

A CachingProvider defines the mechanism to establish, configure, acquire, manage and control zero or more CacheManagers. An application may access and use zero or more CachingProviders at runtime.

A CacheManager defines the mechanism to establish, configure, acquire, manage and control zero or more uniquely named Caches all within the context of the CacheManager. A CacheManager is owned by a single CachingProvider.

A Cache is a Map-like data-structure that permits the temporary storage of Key-based Values, some what like Map data-structure. A Cache is owned by a single CacheManager.

An Cache.Entry is a single key-value pair stored by a Cache.

Each entry stored by a Cache has a defined duration, called the Expiry Duration, during which they may be accessed, updated and removed. Once this duration has passed, the entry is said to be expired. Once expired, entries are no longer available to be accessed, updated or removed, just as if they never existed in a Cache. Expiry is set using an ExpiryPolicy.

Store-By-Value and Store-By-Reference

Entries are stored by individual Caches using one of two mechanisms: store-by-value and store-by-reference.

Store-By-Value

The default mechanism, called store-by-value, instructs an implementation to make a copy of application provided keys and values prior to storing them in a Cache and later to return a new copy of the entries when accessed from a Cache.

The purpose of copying entries as they are stored in a Cache and again when they are returned from a Cache is to allow applications to continue mutating the state of the keys and values without causing side-effects to entries held by a Cache.

Store-By-Reference

The alternative and optional mechanism, called store-by-reference, instructs a Cache implementation to simply store and return references to the application provided keys and values, instead of making a copies as required by the store-by-value approach. Should an application later mutate the keys or values provided to a Cache using store-by-reference semantics, the side-effects of the mutations will be visible to those accessing the entries from the Cache, without an application having to update the Cache.

Caches and Maps

While Caches and Maps share somewhat similar APIs, Caches are not Maps and Maps are not Caches. The following section outlines the main similarities and differences.

Like Map-based data-structures:

Unlike Map-based data-structures:

Consistency

Consistency refers to the behavior of caches and the guarantees that exist when concurrent cache mutation occur together with the visibility of the mutations when multiple threads are accessing a cache.

All implementations must support the Default Consistency model as outlined below.

Default Consistency

When using the default consistency mode, most Cache operations are performed as if a locking mechanism exists for each key in a Cache. When a cache operation acquires an exclusive read and write lock on a key all subsequent operations on that key will block until that lock is released. The consequences are that operations performed by a thread happen-before read or mutation operations performed by another thread, including threads in different Java Virtual Machines.

For some Cache operations the value returned by a Cache is considered the last value. The last value might be an old value or a new value, especially in the case where an entry is concurrently being updated. It is implementation dependent which is returned.

Other operations follow a different convention in that mutations may only occur when the current state of an entry matches a desired state. In such operations multiple threads are free to compete to apply these changes i.e. as if they share a lock.

As these methods must interact with other Cache operations acting as if they had an exclusive lock, the CAS methods cannot write new values without acting as if they also had an exclusive lock.

See the JCache Specification for further details.

Further Consistency Models

An implementation may provide support for different consistency models in addition to the required Default Consistency mode

A Simple Example

This simple example creates a default CacheManager, configures a Cache on it called “simpleCache” with a key type of String and a value type of Integer and an expiry of one hour and then performs a some cache operations. 


 //resolve a cache manager
 CachingProvider cachingProvider = Caching.getCachingProvider();
 CacheManager cacheManager = cachingProvider.getCacheManager();

 //configure the cache
 MutableConfiguration<String, Integer> config =
    new MutableConfiguration<>()
    .setTypes(String.class, Integer.class)
    .setExpiryPolicyFactory(AccessedExpiryPolicy.factoryOf(ONE_HOUR))
    .setStatisticsEnabled(true);

 //create the cache
 Cache<String, Integer> cache = cacheManager.createCache("simpleCache", config);

 //cache operations
 String key = "key";
 Integer value1 = 1;
 cache.put("key", value1);
 Integer value2 = cache.get(key);
 cache.remove(key);
Since:
1.0
Author:
Greg Luck
Skip navigation links

Copyright © 2017. All rights reserved.