Author: tv
Date: Tue Apr 14 13:30:04 2015
New Revision: 1673421
URL: http://svn.apache.org/r1673421
Log:
JCS-124 Make the code in Step 5 on the JCS overview page a full working class
that can compile
Modified:
commons/proper/jcs/trunk/xdocs/getting_started/intro.xml
Modified: commons/proper/jcs/trunk/xdocs/getting_started/intro.xml
URL:
http://svn.apache.org/viewvc/commons/proper/jcs/trunk/xdocs/getting_started/intro.xml?rev=1673421&r1=1673420&r2=1673421&view=diff
==============================================================================
--- commons/proper/jcs/trunk/xdocs/getting_started/intro.xml (original)
+++ commons/proper/jcs/trunk/xdocs/getting_started/intro.xml Tue Apr 14
13:30:04 2015
@@ -19,143 +19,141 @@
-->
<document>
- <properties>
- <title>Getting Started -- Introduction</title>
- <author email="asm...@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
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="../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>
+ <properties>
+ <title>Getting Started -- Introduction</title>
+ <author email="asm...@apache.org">Aaron Smuts</author>
+ </properties>
- <section name="STEP 3: Get the Required Dependencies">
+ <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
+ <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[
+ 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.jcs.engine.CompositeCacheAttributes
+jcs.default.cacheattributes=org.apache.commons.jcs.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=1000
-jcs.default.cacheattributes.MemoryCacheName=
- org.apache.commons.jcs.engine.memory.lru.LRUMemoryCache
+jcs.default.cacheattributes.MemoryCacheName=org.apache.commons.jcs.engine.memory.lru.LRUMemoryCache
jcs.default.cacheattributes.UseMemoryShrinker=false
jcs.default.cacheattributes.MaxMemoryIdleTime=3600
jcs.default.cacheattributes.ShrinkerInterval=60
@@ -169,11 +167,9 @@ jcs.default.elementattributes.IsLateral=
# PRE-DEFINED CACHE REGIONS
jcs.region.testCache1=DC
-jcs.region.testCache1.cacheattributes=
- org.apache.commons.jcs.engine.CompositeCacheAttributes
+jcs.region.testCache1.cacheattributes=org.apache.commons.jcs.engine.CompositeCacheAttributes
jcs.region.testCache1.cacheattributes.MaxObjects=1000
-jcs.region.testCache1.cacheattributes.MemoryCacheName=
- org.apache.commons.jcs.engine.memory.lru.LRUMemoryCache
+jcs.region.testCache1.cacheattributes.MemoryCacheName=org.apache.commons.jcs.engine.memory.lru.LRUMemoryCache
jcs.region.testCache1.cacheattributes.UseMemoryShrinker=false
jcs.region.testCache1.cacheattributes.MaxMemoryIdleTime=3600
jcs.region.testCache1.cacheattributes.ShrinkerInterval=60
@@ -182,93 +178,145 @@ jcs.region.testCache1.elementattributes=
jcs.region.testCache1.elementattributes.IsEternal=false
# AVAILABLE AUXILIARY CACHES
-jcs.auxiliary.DC=
- org.apache.commons.jcs.auxiliary.disk.indexed.IndexedDiskCacheFactory
-jcs.auxiliary.DC.attributes=
- org.apache.commons.jcs.auxiliary.disk.indexed.IndexedDiskCacheAttributes
+jcs.auxiliary.DC=org.apache.commons.jcs.auxiliary.disk.indexed.IndexedDiskCacheFactory
+jcs.auxiliary.DC.attributes=org.apache.commons.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 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[
+]]>
+ </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.jcs.JCS;
import org.apache.commons.jcs.access.CacheAccess;
import org.apache.commons.jcs.access.exception.CacheException;
-. . .
-
- private static final String cacheRegionName = "city";
+public class JcsExample
+{
+ public static void main( String[] args )
+ {
+ JcsExample example = new JcsExample();
+ example.testCache();
+ }
private CacheAccess<String, City> cache = null;
-. . .
- // in your constructor you might do this
- try
+ public JcsExample()
{
- CacheAccess<String, City> c = JCS.getInstance(
this.getCacheRegionName() );
- setCache( c );
+ try
+ {
+ cache = JCS.getInstance( "default" );
+ }
+ catch ( CacheException e )
+ {
+ System.out.println( String.format( "Problem initializing cache:
%s", e.getMessage() ) );
+ }
}
- catch ( CacheException e )
+
+ public void putInCache( City city )
{
- log.error( "Problem initializing cache for region name ["
- + this.getCacheRegionName() + "].", e );
+ 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() ) );
+ }
}
-. . .
-
- // to get a city out of the cache by id you might do this:
- String key = "cityId:" + String.valueOf( id );
+ public City retrieveFromCache( String cityKey )
+ {
+ return cache.get( cityKey );
+ }
- City city = cache.get( key );
+ 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\"" );
+ }
- // to put a city object in the cache, you could do this:
- try
- {
- // if it isn't null, insert it
- if ( city != null )
+ City retrievedCity2 = retrieveFromCache( "New York" );
+ if ( retrievedCity2 != null )
{
- cache.put( key, city );
+ System.out.println( retrievedCity2.toString() );
+ }
+ else
+ {
+ System.out.println( "No object was found in the cache for the key
\"New York\"" );
}
}
- catch ( CacheException e )
+
+ // defined as a nested inner class to reduce number of .java files in the
example
+ public class City implements Serializable
{
- log.error( "Problem putting "
- + city + " in the cache, for key " + key, e );
+ 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>
+ </section>
- </body>
+ </body>
</document>
