| <?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 -- Introduction</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 documentation 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 maps that |
| you reference by name. Each of these maps 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="../JCSPlugins.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://www.apache.org/dist/commons/jcs/"> |
| 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. 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> |
| Beginning with version 2.0 the core of JCS (the LRU memory |
| cache, the indexed disk cache, the TCP lateral, and the |
| RMI remote server) requires only commons-logging. |
| </p> |
| <p> |
| Beginning with version 1.2.7.0 and up to version 1.3, 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.commons.jcs3.engine.CompositeCacheAttributes |
| jcs.default.cacheattributes.MaxObjects=1000 |
| jcs.default.cacheattributes.MemoryCacheName=org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache |
| jcs.default.cacheattributes.UseMemoryShrinker=false |
| jcs.default.cacheattributes.MaxMemoryIdleTimeSeconds=3600 |
| jcs.default.cacheattributes.ShrinkerIntervalSeconds=60 |
| jcs.default.elementattributes=org.apache.commons.jcs3.engine.ElementAttributes |
| jcs.default.elementattributes.IsEternal=false |
| jcs.default.elementattributes.MaxLife=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.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=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.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=${user.dir}/jcs_swap |
| jcs.auxiliary.DC.attributes.MaxPurgatorySize=10000000 |
| jcs.auxiliary.DC.attributes.MaxKeySize=1000000 |
| 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 few convenient classes that should meet all |
| your needs. |
| </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 java.io.Serializable; |
| import org.apache.commons.jcs3.JCS; |
| import org.apache.commons.jcs3.access.CacheAccess; |
| import org.apache.commons.jcs3.access.exception.CacheException; |
| |
| public class JcsExample |
| { |
| public static void main( String[] args ) |
| { |
| JcsExample example = new JcsExample(); |
| example.testCache(); |
| } |
| |
| private CacheAccess<String, City> cache = null; |
| |
| public JcsExample() |
| { |
| try |
| { |
| cache = JCS.getInstance( "default" ); |
| } |
| catch ( CacheException e ) |
| { |
| System.out.println( String.format( "Problem initializing cache: %s", e.getMessage() ) ); |
| } |
| } |
| |
| public void putInCache( City city ) |
| { |
| String key = city.name; |
| try |
| { |
| cache.put( key, city ); |
| } |
| catch ( CacheException e ) |
| { |
| System.out.println( String.format( "Problem putting city %s in the cache, for key %s%n%s", |
| city.name, key, e.getMessage() ) ); |
| } |
| } |
| |
| public City retrieveFromCache( String cityKey ) |
| { |
| return cache.get( cityKey ); |
| } |
| |
| public void testCache() |
| { |
| City zurich = new City( "Zürich", "Switzerland", 366765 ); |
| putInCache( zurich ); |
| |
| City berlin = new City( "Berlin", "Germany", 3502000 ); |
| putInCache( berlin ); |
| |
| City johannesburg = new City( "Johannesburg", "South Africa", 12200000 ); |
| putInCache( johannesburg ); |
| |
| City retrievedCity1 = retrieveFromCache( "Berlin" ); |
| if ( retrievedCity1 != null ) |
| { |
| System.out.println( retrievedCity1.toString() ); |
| } |
| else |
| { |
| System.out.println( "No object was found in the cache for the key \"Berlin\"" ); |
| } |
| |
| City retrievedCity2 = retrieveFromCache( "New York" ); |
| if ( retrievedCity2 != null ) |
| { |
| System.out.println( retrievedCity2.toString() ); |
| } |
| else |
| { |
| System.out.println( "No object was found in the cache for the key \"New York\"" ); |
| } |
| } |
| |
| // defined as a nested inner class to reduce number of .java files in the example |
| public class City implements Serializable |
| { |
| private static final long serialVersionUID = 6392376146163510146L; |
| public String name; |
| public String country; |
| public int population; |
| |
| public City( String name, String country, int population ) |
| { |
| this.name = name; |
| this.country = country; |
| this.population = population; |
| } |
| |
| @Override |
| public String toString() |
| { |
| return String.format( "%s is a city in the country %s with a population of %d", name, country, population ); |
| } |
| } |
| } |
| ]]> |
| </source> |
| </section> |
| |
| </body> |
| </document> |
