Apache Commons logo

Commons JCS™

Basic JCS Configuration

The following document illustrates several basic JCS configurations. As you'll see, using JCS can be as simple as creating a single memory cache for you application. However, with a few configuration changes, you can quickly enable some distributed caching features that can scale your application even further.

Building a cache.ccf file

Configuring the JCS can be as simple as your needs. The most basic configuration would be a pure memory cache where every region takes the default values. The complete configuration file (cache.ccf) could look like this:

# DEFAULT CACHE REGION

jcs.default=
jcs.default.cacheattributes=
    org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=1000
jcs.default.cacheattributes.MemoryCacheName=
    org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache
        

If you want to add memory shrinking then you can add these lines:

jcs.default.cacheattributes.UseMemoryShrinker=true
jcs.default.cacheattributes.MaxMemoryIdleTimeSeconds=3600
jcs.default.cacheattributes.ShrinkerIntervalSeconds=60
jcs.default.cacheattributes.MaxSpoolPerRun=500
jcs.default.elementattributes=org.apache.commons.jcs3.engine.ElementAttributes
jcs.default.elementattributes.IsEternal=false
        

Adding a disk cache is as simple as telling it what folder to use. It is recommended that you add a disk cache. If you want to add a disk cache to your default parameters, then (1) add this to the bottom of the file to create the auxiliary:

jcs.auxiliary.DC=
    org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCacheFactory
jcs.auxiliary.DC.attributes=
    org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCacheAttributes
jcs.auxiliary.DC.attributes.DiskPath=g:/dev/jcs/raf
        

and (2) change the first line to:

jcs.default=DC
        

If you want to predefine a specific region, say called testCache1, then add these lines:

jcs.region.testCache1=DC
jcs.region.testCache1.cacheattributes=
    org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.region.testCache1.cacheattributes.MaxObjects=1000
jcs.region.testCache1.cacheattributes.MemoryCacheName=
    org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache
jcs.region.testCache1.cacheattributes.UseMemoryShrinker=true
jcs.region.testCache1.cacheattributes.MaxMemoryIdleTimeSeconds=3600
jcs.region.testCache1.cacheattributes.ShrinkerIntervalSeconds=60
jcs.region.testCache1.cacheattributes.MaxSpoolPerRun=500
jcs.region.testCache1.elementattributes=org.apache.commons.jcs3.engine.ElementAttributes
jcs.region.testCache1.elementattributes.IsEternal=false

        

If you want to add a lateral cache for distribution (the TCP Lateral Auxiliary is recommended), then add these lines to the bottom of the file to define the auxiliary:

jcs.auxiliary.LTCP=
    org.apache.commons.jcs3.auxiliary.lateral.LateralCacheFactory
jcs.auxiliary.LTCP.attributes=
    org.apache.commons.jcs3.auxiliary.lateral.LateralCacheAttributes
jcs.auxiliary.LTCP.attributes.TransmissionTypeName=TCP
jcs.auxiliary.LTCP.attributes.TcpServers=localhost:1111
jcs.auxiliary.LTCP.attributes.TcpListenerPort=1110
jcs.auxiliary.LTCP.attributes.PutOnlyMode=false
        

See the TCP Lateral documentation for more information. If you want to set up testCache1 to use this, then change the definition to:

jcs.region.testCache1=DC,LTCP
        

A few comments on configuration

Auxiliary definitions are like log4j appenders, they are defined and then associated with a region like a log4j category.

The order of configuration file is unimportant, though you should try to keep it organized for your own sake.

Configuration is being refactored and is subject to change. It should only become easier.

The complete file

The complete file from above would look like this:

# DEFAULT CACHE REGION

jcs.default=DC,LTCP
jcs.default.cacheattributes=
    org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=1000
jcs.default.cacheattributes.MemoryCacheName=
    org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache

# PRE-DEFINED CACHE REGIONS

jcs.region.testCache1=DC,LTCP
jcs.region.testCache1.cacheattributes=
    org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.region.testCache1.cacheattributes.MaxObjects=1000
jcs.region.testCache1.cacheattributes.MemoryCacheName=
    org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache
jcs.region.testCache1.cacheattributes.UseMemoryShrinker=true
jcs.region.testCache1.cacheattributes.MaxMemoryIdleTimeSeconds=3600
jcs.region.testCache1.cacheattributes.ShrinkerIntervalSeconds=60
jcs.region.testCache1.cacheattributes.MaxSpoolPerRun=500
jcs.region.testCache1.elementattributes=org.apache.commons.jcs3.engine.ElementAttributes
jcs.region.testCache1.elementattributes.IsEternal=false


# AVAILABLE AUXILIARY CACHES
jcs.auxiliary.DC=
    org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCacheFactory
jcs.auxiliary.DC.attributes=
    org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCacheAttributes
jcs.auxiliary.DC.attributes.DiskPath=g:/dev/jcs/raf
jcs.auxiliary.DC.attributes.maxKeySize=100000

jcs.auxiliary.LTCP=
    org.apache.commons.jcs3.auxiliary.lateral.LateralCacheFactory
jcs.auxiliary.LTCP.attributes=
    org.apache.commons.jcs3.auxiliary.lateral.LateralCacheAttributes
jcs.auxiliary.LTCP.attributes.TransmissionTypeName=TCP
jcs.auxiliary.LTCP.attributes.TcpServers=localhost:1111
jcs.auxiliary.LTCP.attributes.TcpListenerPort=1110
jcs.auxiliary.LTCP.attributes.PutOnlyMode=false