Apache Commons logo

Commons JCS™

Element Attribute Configuration

The following document describes the various configuration options available for cache elements. Each element put into the cache can be configured independently. You can define element behavior in three ways: as a default setting, as a region setting, or at the element level.

Setting the defaults

The configuration below can be put in the cache.ccf configuration file. It establishes the default behavior for all regions. A region can override these defaults and an individual element can override these defaults and the region settings.

					
# DEFAULT CACHE REGION

jcs.default=DC
jcs.default.cacheattributes=
    org.apache.commons.jcs.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=1000
jcs.default.cacheattributes.MemoryCacheName=
    org.apache.commons.jcs.engine.memory.lru.LRUMemoryCache
jcs.default.cacheattributes.UseMemoryShrinker=true
jcs.default.cacheattributes.MaxMemoryIdleTimeSeconds=3600
jcs.default.cacheattributes.ShrinkerIntervalSeconds=60
jcs.default.elementattributes=org.apache.commons.jcs.engine.ElementAttributes
jcs.default.elementattributes.IsEternal=false
jcs.default.elementattributes.MaxLifeSeconds=700
jcs.default.elementattributes.IdleTime=1800
jcs.default.elementattributes.IsSpool=true
jcs.default.elementattributes.IsRemote=true
jcs.default.elementattributes.IsLateral=true
        
				

The default and region configuration settings have three components. They define what auxiliaries are available, how the cache should control the memory, and how the elements should behave. This configuration tells all regions to use an auxiliary called DC by default. It also establishes several settings for memory management (see Basic JCS Configuration for more information on the cacheattribute settings). In addition, by default all regions will take these element configuration settings.

These settings specify that elements are not eternal, i.e. they can expire. By default elements are considered eternal.

You can define the maximum life of an item by setting the MaxLifeSeconds parameter. If an item has been in the cache for longer than the set number of seconds it will not be retrieved on a get request. If you use the memory shrinker the item will be actively removed from memory. Currently there is no background disk shrinker, but the disk cache does allow for a maximum number of keys (see Indexed Disk Cache for more information on the disk cache settings).

You can define the maximum time an item can live without being accessed by setting the IdleTime parameter. This is different than the MaxMemoryIdleTimeSeconds parameter, which just specifies how long an object can be in memory before it is subjected to removal or being spooled to a disk cache if it is available. Note: the IdleTime parameter may not function properly for items retrieved from disk, if you have a memory size of 0.

IsSpool determines whether or not the element can go to disk, if a disk cache is configured for the region.

IsRemote determines whether or not the element can be sent to a remote server, if one is configured for the region.

IsLateral determines whether or not the element can be laterally distributed, if a lateral auxiliary is configured for the region.

Programmatic Configuration

Every element put into the cache has its own set of attributes. By default elements are given a copy of the default element attributes associated with a region. You can also specify the attributes to use for an element when you put it in the cache.

				
    CacheAccess<String, String> jcs = JCS.getInstance( "myregion" );

    . . .

    // jcs.getDefaultElementAttributes returns a copy not a reference
    IElementAttributes attributes = jcs.getDefaultElementAttributes();

    // set some special value
    attributes.setIsEternal( true );
    jcs.put( "key", "data", attributes );
        		
				

You can also programmatically modify the default element attributes.

					
    CacheAccess<String, String> jcs = JCS.getInstance( "myregion" );

    . . .

    // jcs.getDefaultElementAttributes returns a copy not a reference
    IElementAttributes attributes = jcs.getDefaultElementAttributes();

    // set some special value
    attributes.setIsEternal( true );
    jcs.setDefaultElementAttributes( attributes );