Where is the configuration information?

Configuration of local caches involves editing the cache configuration file, named cache.ccf. The classpath should include the directory where this file is located or the file should be placed at the root of the classpath, since it is discovered automatically.

What is in the cache.ccf file?

The cache.ccf file contains default configuration information for cache regions and specific configuration information for regions that you predefine. Regions not using default behaviors should generally be configured via the cache.ccf file. If you can put configuration information in a class, you can edit a props file just as easily. This makes modification of the regional setting more efficient and allows for startup error checking.

There are three main sections of the cache.ccf file:

• the default and system settings
• the region specific settings
• the auxiliary cache definitions

How do I set up default values for regions?

You can establish default values that any non-preconfigured region will inherit. The non-predefined region will be created when you call CacheAccess.getAccess("cacheName"). The default setting look like this:

# DEFAULT CACHE REGION

# sets the default aux value for any non configured caches
jcs.default=DC,RFailover
jcs.default.cacheattributes=
    org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=1000
        

The most important line is jcs.default=DC,Rfailover. This tells the cache what auxiliary caches should be used. Auxiliary caches are configured in the third section of the cache.ccf and are referenced in a comma separated list. You can add as many auxiliary caches as you want, but the behavior of remote and lateral auxiliaries may conflict. This allows you to define different configurations for auxiliary caches and to use these different configurations for different regions.

How do I define a region?

Defining a region involves specifying which auxiliary caches it will use and how many objects it will store in memory. A typical region definition looks like:

jcs.region.testCache=DC,RFailover
jcs.region.testCache.cacheattributes=
    org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.region.testCache.cacheattributes.MaxObjects=1000
        

The region name is testCache. It will have a 1000 item memory limit and will use the DC and RFailover auxiliary caches. If a typical element for this region was very large, you might want to lower the number of items stored in memory. The size of the memory storage is dependent on the priority of the cache, the size of its elements, and the amount of RAM on the machine.

How do I configure an auxiliary cache?

Each auxiliary cache is created through a factory that passes an attribute object to the constructor. The attributes are set via reflection and should be fairly simple to understand. Each auxiliary cache will be fully documented. Plugging in your own auxiliary cache become a simple matter given the reflexive manner of initialization.

The most important settings for common usage are the disk path and the remote cache location. It is recommended that only disk and remote auxiliaries be used. The lateral caches are functional but not as efficient.

The default configuration code above specifies that non-preconfigured caches use the auxiliary cache by the name DC. This cache is defined in the third section of the file:

jcs.auxiliary.DC=
    org.apache.commons.jcs3.auxiliary.disk.DiskCacheFactory
jcs.auxiliary.DC.attributes=
    org.apache.commons.jcs3.auxiliary.disk.DiskCacheAttributes
jcs.auxiliary.DC.attributes.DiskPath=c:/dev/cache/raf
        

The only thing that needs to be set here is the DiskPath value. Change it to wherever you want the cache to persist unused items.

The default region is also set to use an auxiliary called RFailover. This is a remote cache that is designed to failover to other remote servers in a cluster:

jcs.auxiliary.RFailover=
    org.apache.commons.jcs3.auxiliary.remote.RemoteCacheFactory
jcs.auxiliary.RFailover.attributes=
    org.apache.commons.jcs3.auxiliary.remote.RemoteCacheAttributes
jcs.auxiliary.RFailover.attributes.RemoteTypeName=LOCAL
jcs.auxiliary.RFailover.attributes.FailoverServers=
    localhost:1102,localhost:1101
        

If you don't have more than one remote server running, just specify it by itself in the FailoverServers attribute.