[ Java 套件 ] Common JCS - Getting Started (v1.3)

Preface 
JCS is a distributed caching system written in java. It is intended to speed up applications by providing a means to manage cached data of various dynamic natures.Like any caching system, JCS is most useful for high read, low put applications. Latency times drop sharply and bottlenecks move away from the database in an effectively cached system. The foundation of JCS is the Composite Cache, which is the pluggable controller for a cache region. Four types of caches can be plugged into the Composite Cache for any given region: 

(1) Memory,
(2) Disk,
(3) Lateral, and
(4) Remote.

The Composite Cache orchestrates access to the various caches configured for use in a region. The JCS jar provides production ready implementations of each of the four types of caches. In addition to the core four, JCS also provides additional plugins of each type. 

- LRU Memory Cache 

The LRU Memory Cache (Cache algorithm) is an extremely fast, highly configurable memory cache . It uses a Least Recently Used algorithm to manage the number of items that can be stored in memory. The LRU Memory Cache uses its own LRU Map implementation that is significantly faster than both the commonsLRUMap implementation and the LinkedHashMap that is provided with JDK1.4 up. This makes JCS faster than its competitors .

- Indexed Disk Cache 

The Indexed Disk Cache is a fast, reliable, and highly configurable swap for cached data. The indexed disk cache follows the fastest pattern for disk swapping. Cache elements are written to disk via a continuous queue-based process. The length of the item is stored in the first few bytes of the entry. The offset is stored in memory and can be reference via the key. When items are removed from the disk cache, the location and size are recorded and reused when possible. Every aspect of the disk cache is configurable, and a thread pool can be used to reduce the number of queue worker threads across the system.

- JDBC Disk Cache 

The JDBC Disk Cache is a fast, reliable, and highly configurable disk cache. It stores both the keys and elements in a JDBC compatible database. The JDBC disk cache stores elements in a database as BLOBs. Periodically, the table is swept to remove expired elements. Multiple instances can be configured to use a common connection pool. A thread pool can be used to reduce the number of queue worker threads across the system. The MySQL version of the JDBC Disk Cache can optimize and repair tables.

- RMI Remote Cache 

JCS also provides an RMI based Remote Cache Server . Rather than having each node connect to every other node, you can use the remote cache server as the connection point. Each node connects to the remove server, which then broadcasts events to the other nodes. To maintain consistency across a cluster without incurring the overhead of serialization, you can decide to send invalidation messages to the other locals rather than send the object over the wire. The remote cache server holds a serialized version of your objects, so it does not need to be deployed with your class libraries. The remote servers can be chained and a list of failover servers can be configured on the client.

Getting Started 
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. 

STEP 1: Understand the Core Concepts 
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". JCS is an object cache. You can put objects, or "elements," into JCS and reference them via a key, much like a hashtable. 

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. 

"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 HERE. 

STEP 2: Download JCS 
Download the latest version of JCS. The latest JCS builds are located HERE. 

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. 

STEP 3: Get the Required Dependencies 
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; 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. 

* concurrent: This package provides standardized, efficient versions of utility classes commonly encountered in concurrent Java programming.
* commons-logging: The Logging package is an ultra-thin bridge between different logging implementations.
* commons-collections
* commons-lang

STEP 4: Configure JCS 
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. 

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. 

The following cache.ccf file (for v1.3) 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. 

view plaincopy to clipboardprint?

1. # DEFAULT CACHE REGION  
2. jcs.default=DC  
3. jcs.default.cacheattributes=org.apache.jcs.engine.CompositeCacheAttributes  
4. jcs.default.cacheattributes.MaxObjects=1000  
5. jcs.default.cacheattributes.MemoryCacheName=org.apache.jcs.engine.memory.lru.LRUMemoryCache  
6. jcs.default.cacheattributes.UseMemoryShrinker=false  
7. jcs.default.cacheattributes.MaxMemoryIdleTimeSeconds=3600  
8. jcs.default.cacheattributes.ShrinkerIntervalSeconds=60  
9. jcs.default.elementattributes=org.apache.jcs.engine.ElementAttributes  
10. jcs.default.elementattributes.IsEternal=false  
11. jcs.default.elementattributes.MaxLifeSeconds=21600  
12. jcs.default.elementattributes.IdleTime=1800  
13. jcs.default.elementattributes.IsSpool=true  
14. jcs.default.elementattributes.IsRemote=true  
15. jcs.default.elementattributes.IsLateral=true  
16.   
17. # PRE-DEFINED CACHE REGIONS  
18. jcs.region.testCache1=DC  
19. jcs.region.testCache1.cacheattributes=org.apache.jcs.engine.CompositeCacheAttributes  
20. jcs.region.testCache1.cacheattributes.MaxObjects=1000  
21. jcs.region.testCache1.cacheattributes.MemoryCacheName=org.apache.jcs.engine.memory.lru.LRUMemoryCache  
22. jcs.region.testCache1.cacheattributes.UseMemoryShrinker=false  
23. jcs.region.testCache1.cacheattributes.MaxMemoryIdleTimeSeconds=3600  
24. jcs.region.testCache1.cacheattributes.ShrinkerIntervalSeconds=60  
25. jcs.region.testCache1.cacheattributes.MaxSpoolPerRun=500  
26. jcs.region.testCache1.elementattributes=org.apache.jcs.engine.ElementAttributes  
27.   
28. # AVAILABLE AUXILIARY CACHES  
29. jcs.auxiliary.DC=org.apache.jcs.auxiliary.disk.indexed.IndexedDiskCacheFactory  
30. jcs.auxiliary.DC.attributes=org.apache.jcs.auxiliary.disk.indexed.IndexedDiskCacheAttributes  
31. jcs.auxiliary.DC.attributes.DiskPath=jcs_swap  
32. jcs.auxiliary.DC.attributes.MaxPurgatorySize=10000000  
33. jcs.auxiliary.DC.attributes.MaxKeySize=1000000  
34. jcs.auxiliary.DC.attributes.MaxRecycleBinSize=5000  
35. jcs.auxiliary.DC.attributes.OptimizeAtRemoveCount=300000  
36. jcs.auxiliary.DC.attributes.ShutdownSpoolTimeLimit=60  

Basic JCS configuration is described in more detail HERE; Element level configuration is described in more detail HERE. For more information on advanced configuration options and the available plugins, see the User's Guide. 

STEP 5: Programming to JCS 
JCS provides a few convenient classes that should meet all your needs. To get a cache region you simply ask JCS for the region by name. If you wanted to use JCS for Cityobjects, you would do something like this: 
- HelloWorld.java 

view plaincopy to clipboardprint?

1. package demo;  
2.   
3. import java.io.File;  
4. import java.io.FileInputStream;  
5. import java.io.Serializable;  
6. import java.util.Properties;  
7. import java.util.Random;  
8. import java.util.logging.Logger;  
9.   
10. import org.apache.jcs.JCS;  
11. import org.apache.jcs.access.behavior.ICacheAccess;  
12. import org.apache.jcs.access.exception.CacheException;  
13. import org.apache.jcs.engine.control.CompositeCacheManager;  
14.   
15. public class HelloWorld {  
16.     public static class City implements Serializable{         
17.         public String name;  
18.         public City(String n){this.name=n;}  
19.     }  
20.       
21.     public static Logger log = Logger.getLogger("HelloWorld");  
22.     public static final String CacheRegionName = "city";  
23.     public static ICacheAccess cache = null;  
24.   
25.     /** 
26.      * http://stackoverflow.com/questions/10733681/how-to-change-jcs-cache-ccf-files-path 
27.      * @param args 
28.      */  
29.     public static void main(String[] args) throws Exception{  
30.         try  
31.         {  
32.             CompositeCacheManager ccm = CompositeCacheManager.getUnconfiguredInstance();  
33.             Properties props = new Properties();  
34.             props.load(new FileInputStream(new File("cache.ccf")));           
35.   
36.             ccm.configure(props);  
37.             Random rdm = new Random();  
38.               
39.             cache = JCS.getInstance( CacheRegionName );  
40.             for(int i=0; i<100000; i++)  
41.             {  
42.                 cache.put(i, new City("Taiwan-"+i)); // Store in Cache  
43.                 if(i!=0 && i%1000==0)   
44.                 {  
45.                     // Check City object in cache every 1000 rounds  
46.                     int id = rdm.nextInt(i);  
47.                     City city = (City)cache.get(id);  
48.                     System.out.printf("\t[Test] City with ID=%d=%s\n", id, city.name);  
49.                 }  
50.             }             
51.             System.out.printf("\t[Info] Done!\n");  
52.             cache.remove();  
53.         }  
54.         catch ( CacheException e )  
55.         {  
56.             log.severe(String.format("Problem initializing cache for region name ["+ CacheRegionName + "]=%s", e));          
57.         }  
58.     }  
59. }  

Supplement: 
* Basic JCS Config 
* Plugin overview 
* Basic Web example