Atlassian Cache 2 Overview
Atlassian is rolling out a new version of the Atlassian Cache API (atlassian-cache-api-2.x) that will be used within Atlassian products (initially JIRA 6.2 and Confluence 5.5). The API has been designed to be backwardly compatible with atlassian-cache-api-0.1.
The main interfaces in the API from an end-user perspective are:
- Cache - represents a cache
- CacheLoader - used with a Cache to provide read-through semantics (see Cache Population).
- CachedReference - represents a resettable reference that is backed by a cache.
- Supplier - used with a CachedReference to generate the referenced object.
- CacheFactory - responsible for creating Cache and CachedReference instances which may be configured using CacheSettings.
The Cache API supports three distinct types of caches:
- Local - the data in a local cache is held on the JVM. The keys and values are stored by reference.
- Cluster - the data in a cluster cache is replicated across the cluster. The keys and values are stored by value, and hence must be Serializable (this is only enforced at run-time).
- Hybrid - the data in a hybrid cache is stored locally on each node in a cluster, and is kept synchronized via invalidation messages. The keys and values are stored by reference, however the keys must be Serializable (this is only enforced at run-time).
See Cache Creation for how to specify the type of cache.
On this page:
For populating the data in a cache, the Cache API supports two styles:
- Read Through Cache semantics where values for cache misses are retrieved using a supplied CacheLoader when the cache is created. This is the preferred style for new development.
- Traditional put-style semantics where values are put into the cache using the put(K, V) and putIfAbsent(K, V) methods. This is supported for backwards compatibility.
The Cache API supports two rules for eviction of values from a cache, which are specified in the CacheSettings:
- expireAfterAccess(long, java.util.concurrent.TimeUnit) - evicts entries that have not been accessed for a specified duration.
- expireAfterWrite(long, java.util.concurrent.TimeUnit) - evicts entries that have not been updated since a specified duration.
To be precise, the rules are actually hints to the underlying cache provider that may or may not be observed. The user of the cache should be prepared to handle their values being evicted at anytime.
When creating a cache, it is possible to provide a CacheSettings to control the configuration of a cache, which are created using the CacheSettingsBuilder. See CacheSettingsBuilder for all the settings that may be specified.
When settings are not explicitly specified, the product specific default will be used. See each product's documentation for detailed information on how defaults are determined.
|remote()||replicateViaCopy()||Cache Type Created|
Cache data sharing guidelines
This section provides guidelines for developers wanting to share data stored in a cache. Sharing can be between:
Different versions of a plugin (after an upgrade/downgrade).
Local cache data
Local cache keys and values are stored by reference. Therefore, to ensure that the data can be accessed between plugins and plugin restarts, only use classes provided by:
Java JDK (e.g.
The product core (such as Confluence core classes).
Note that a plugin can serialize custom classes to a portable format that is stored as a
Cluster cache data
Cluster cache keys and values are stored by value, which means they are serialized on insertion to the cache, and deserialized on extraction.
Therefore, to ensure that the data can be shared, both product and plugin developers must ensure that the objects placed into a cluster cache implement serialization with support for versioning. See Versioning of Serializable Objects.
It's recommended that plugin developers use classes from the Java JDK and product core. If custom classes are required to be shared between plugins, then a common shared library should be used for defining them.
Hybrid cache data
Hybrid cache keys are stored by value, and values are stored by reference.
- Keys should adhere to the guidelines in Cluster Cache Data, AND
- Values should adhere to the guidelines in Local Cache Data.
Cache code examples
The following example shows how to obtain a cache called "old-style" using defaults.
The following example shows how to obtain a cache called "with-loader" that uses a CacheLoader.
The following example shows how to obtain a hybrid cache called "adam" that expires values after 60 seconds of no access.
CachedReference code examples
The following example shows how to use a CachedReference.