ObjectCache Documentation

The ObjectCache is a generic cache for Objects, which implements several ways to manage the contents of the cache and their life-cycle. There are several components at work in the ObjectCache, and this page serves as a brief introduction to the ObjectCache and its components. For detailed information, see the API details.

ObjectCache Overview

The above diagram illustrates how the components of the ObjectCache work together to provide a standard, generic cache for objects. The ObjectCache implements the Map interface and allows objects to be stored and retrieved from the cache. However, instead of values being stored directly within the Map, they are stored within a CachedObject instance. The CachedObject instance takes care of maintaining the creation time, last usage time, the expiration limits, etc. When a value is asked for from the ObjectCache via get(Object), the key is looked up, the CachedObject instance is retrieved, and then the value is retrieved from the CachedObject and then returned. If the CachedObject shows its value to be expried, null is returned instead.

ObjectCache Is "Store-Only"

The ObjectCache is only a storage implementation. As such, it does not know how values are obtained in the first place. That is, if a value expires, the ObjectCache does not know how to reload it.

The key side-effect of this design is that ObjectCache is made to be encapsulated. You use ObjectCache within frameworks that know how to instantiate the value objects, defering lifecycle maintenance and tracking to the ObjectCache.

ObjectCache Defers to CachedObject Implementations

The ObjectCache defers most of the actual life-cycle tracking to the CachedObject implementations. This allows the basics of the keyed cache to be implemented and to defer special cache operations (like using SoftReferences) to the CachedObject implementation object. The ObjectCache can then be extended by providing new CachedObject implementations and providing properties that enable these implementations over the default (see how the softReferences property affects cache behavior).

Soft References Allows For "Memory-Sensitive" Caches

By setting the ObjectCache to use soft references, it tells the ObjectCache instance to use the SoftCachedObject instead. The SoftCachedObject uses a java.lang.ref.SoftReference to hold the value object. If the reference is reaped by the VM garbage collector, the object will respond like an expired CachedObject instance, returning null and returning true for isExpired().

Using soft-references is highly recommended unless you have a pressing reason not to cycle out cached objects when memory is tight. Using soft-references also makes sure that references held in class-level singletons are not held on to across web application deployments (that is, in app servers like tomcat or jboss, the soft reference is usually reaped upon redeployment).

Classes and Components in ObjectCache

The following is a brief overview of the components and classes used in ObjectCache:

ObjectCache

This is the actual cache--in terms of holding multiple objects that can be looked up via a known key.

Cached

This is an interface for objects that are cached (or contain cached data). This interface describes the information and operations needed to track the "cache state" of an implementor (when it was created, has it expired, etc). CachedObject implements this interface.

CachedObject

Implements Cached and supports managing the life-cycle of a single object. If you only have to cache one object (and not many), using a single instance of CachedObject is the way to go.

SoftCachedObject

This is a subclass of CachedObject which uses java.lang.ref.SoftReference to store the value object. This makes the SoftCachedObject a "memory-sensitive" cache.