<?xml version="1.0"?> | |
<document> | |
<properties> | |
<title>Getting Started -- Intoduction</title> | |
<author email="asmuts@apache.org">Aaron Smuts</author> | |
</properties> | |
<body> | |
<section name="Getting Started"> | |
<p> | |
To start using JCS you need to (1) understand the core | |
concepts, (2) download JCS, (3) get the required | |
dependencies, (4) configure JCS, and (5) then start | |
programming to it. The purpose of the getting started | |
guide is to help you get up and running with JCS as | |
quickly as possible. In depth doumentation on the | |
various features of JCS is provided in the User's Guide. | |
</p> | |
</section> | |
<section name="STEP 1: Understand the Core Concepts"> | |
<p> | |
In order to use JCS, you must understand a few core | |
concepts, most importantly you need to know the | |
difference between "elements," "regions," and | |
"auxiliaries". | |
</p> | |
<p> | |
JCS is an object cache. You can put objects, or | |
"elements," into JCS and reference them via a key, much | |
like a hashtable. | |
</p> | |
<p> | |
You can think of JCS as a collection of hashtables that | |
you reference by name. Each of these hashtables is | |
called a "region," and each region can be configured | |
independently of the others. For instance, I may have a | |
region called Cities where I cache City objects that | |
change infrequently. I may also define a region called | |
Products where I cache product data that changes more | |
frequently. I would configure the volatile Product | |
region to expire elements more quickly than the City | |
region. | |
</p> | |
<p> | |
"Auxiliaries" are optional plugins that a region can | |
use. The core auxiliaries are the Indexed Disk Cache, | |
the TCP Lateral Cache, and the Remote Cache Server. The | |
Disk Cache, for example, allows you to swap items onto | |
disk when a memory threshold is reached. You can read | |
more about the available auxiliaries | |
<a href="../Plugins.html">HERE</a> | |
. | |
</p> | |
</section> | |
<section name="STEP 2: Download JCS"> | |
<p> | |
Download the latest version of JCS. The latests JCS | |
builds are located | |
<a | |
href="http://svn.apache.org/viewcvs.cgi/jakarta/jcs/trunk/tempbuild/"> | |
HERE | |
</a> | |
</p> | |
<p> | |
If you would like to build JCS yourself, check it out | |
from Subversion and build it as you would any other | |
project built by Maven 1.x. The location of the | |
repository is documented in the project info pages that | |
are linked via the left nav. | |
</p> | |
</section> | |
<section name="STEP 3: Get the Required Dependencies"> | |
<p> | |
As of version 1.2.7.0, the core of JCS (the LRU memory | |
cache, the indexed disk cache, the TCP lateral, and the | |
RMI remote server) requires only two other jars. | |
</p> | |
<p> | |
<a | |
href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html"> | |
concurrent | |
</a> | |
</p> | |
<p>commons-logging</p> | |
<p> | |
Versions 1.2.6.9 and below also require the following | |
two additional jars: | |
</p> | |
<p>commons-collections</p> | |
<p>commons-lang</p> | |
<p> | |
All of the other dependencies listed on the project info | |
page are for optional plugins. | |
</p> | |
</section> | |
<section name="STEP 4: Configure JCS"> | |
<p> | |
JCS is configured from a properties file called | |
"cache.ccf". There are alternatives to using this file, | |
but they are beyond the scope of the getting started | |
guide. | |
</p> | |
<p> | |
The cache configuration has three parts: default, | |
regions, and auxiliaries. You can think of the | |
auxiliaries as log4j appenders and the regions as log4j | |
categories. For each region (or category) you can | |
specify and auxiliary (or appender to use). If you don't | |
define a region in the cache.ccf, then the default | |
settings are used. The difference between JCS and log4j | |
is that in JCS, pre-defined regions do not inherent | |
auxiliaries from the default region. | |
</p> | |
<p> | |
The following cache.ccf file defines one region called | |
"testCache1" and uses the Indexed Disk Cache, here | |
called "DC" by default. The LRU Memory Cache is selected | |
as the memory manager. | |
</p> | |
<source> | |
<![CDATA[ | |
# DEFAULT CACHE REGION | |
jcs.default=DC | |
jcs.default.cacheattributes= | |
org.apache.jcs.engine.CompositeCacheAttributes | |
jcs.default.cacheattributes.MaxObjects=1000 | |
jcs.default.cacheattributes.MemoryCacheName= | |
org.apache.jcs.engine.memory.lru.LRUMemoryCache | |
jcs.default.cacheattributes.UseMemoryShrinker=false | |
jcs.default.cacheattributes.MaxMemoryIdleTimeSeconds=3600 | |
jcs.default.cacheattributes.ShrinkerIntervalSeconds=60 | |
jcs.default.elementattributes=org.apache.jcs.engine.ElementAttributes | |
jcs.default.elementattributes.IsEternal=false | |
jcs.default.elementattributes.MaxLifeSeconds=21600 | |
jcs.default.elementattributes.IdleTime=1800 | |
jcs.default.elementattributes.IsSpool=true | |
jcs.default.elementattributes.IsRemote=true | |
jcs.default.elementattributes.IsLateral=true | |
# PRE-DEFINED CACHE REGIONS | |
jcs.region.testCache1=DC | |
jcs.region.testCache1.cacheattributes= | |
org.apache.jcs.engine.CompositeCacheAttributes | |
jcs.region.testCache1.cacheattributes.MaxObjects=1000 | |
jcs.region.testCache1.cacheattributes.MemoryCacheName= | |
org.apache.jcs.engine.memory.lru.LRUMemoryCache | |
jcs.region.testCache1.cacheattributes.UseMemoryShrinker=false | |
jcs.region.testCache1.cacheattributes.MaxMemoryIdleTimeSeconds=3600 | |
jcs.region.testCache1.cacheattributes.ShrinkerIntervalSeconds=60 | |
jcs.region.testCache1.cacheattributes.MaxSpoolPerRun=500 | |
jcs.region.testCache1.elementattributes=org.apache.jcs.engine.ElementAttributes | |
jcs.region.testCache1.elementattributes.IsEternal=false | |
# AVAILABLE AUXILIARY CACHES | |
jcs.auxiliary.DC= | |
org.apache.jcs.auxiliary.disk.indexed.IndexedDiskCacheFactory | |
jcs.auxiliary.DC.attributes= | |
org.apache.jcs.auxiliary.disk.indexed.IndexedDiskCacheAttributes | |
jcs.auxiliary.DC.attributes.DiskPath=${user.dir}/jcs_swap | |
jcs.auxiliary.DC.attributes.MaxPurgatorySize=10000000 | |
jcs.auxiliary.DC.attributes.MaxKeySize=1000000 | |
jcs.auxiliary.DC.attributes.MaxRecycleBinSize=5000 | |
jcs.auxiliary.DC.attributes.OptimizeAtRemoveCount=300000 | |
jcs.auxiliary.DC.attributes.ShutdownSpoolTimeLimit=60 | |
]]> | |
</source> | |
<p> | |
Basic JCS configuration is described in more detail | |
<a href="../BasicJCSConfiguration.html">HERE</a> | |
</p> | |
<p> | |
Element level configuration is described in more detail | |
<a href="../ElementAttributes.html">HERE</a> | |
</p> | |
<p> | |
For more information on advanced configuration options | |
and the available plugins, see the User's Guide. | |
</p> | |
</section> | |
<section name="STEP 5: Programming to JCS"> | |
<p> | |
JCS provides a convenient class that should meet all | |
your needs. It is called, appropriately engough, | |
<code>org.apache.jcs.JCS</code> | |
</p> | |
<p> | |
To get a cache region you simply ask JCS for the region | |
by name. If you wanted to use JCS for City objects, you | |
would do something like this: | |
</p> | |
<source> | |
<![CDATA[ | |
import org.apache.jcs.JCS; | |
import org.apache.jcs.access.exception.CacheException; | |
. . . | |
private static final String cacheRegionName = "city"; | |
private JCS cache = null; | |
. . . | |
// in your constructor you might do this | |
try | |
{ | |
setCache( JCS.getInstance( this.getCacheRegionName() ) ); | |
} | |
catch ( CacheException e ) | |
{ | |
log.error( "Problem initializing cache for region name [" | |
+ this.getCacheRegionName() + "].", e ); | |
} | |
. . . | |
// to get a city out of the cache by id you might do this: | |
String key = "cityId:" + String.valueOf( id ); | |
City city = (City) cache.get( key ); | |
. . . | |
// to put a city object in the cache, you could do this: | |
try | |
{ | |
// if it isn't null, insert it | |
if ( city != null ) | |
{ | |
cache.put( key, city ); | |
} | |
} | |
catch ( CacheException e ) | |
{ | |
log.error( "Problem putting " | |
+ city + " in the cache, for key " + key, e ); | |
} | |
]]> | |
</source> | |
</section> | |
</body> | |
</document> |