| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <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 latest 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 enough, |
| <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> |