commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From t.@apache.org
Subject svn commit: r1673421 - /commons/proper/jcs/trunk/xdocs/getting_started/intro.xml
Date Tue, 14 Apr 2015 13:30:04 GMT
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="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 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="asmuts@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>



Mime
View raw message