xdocs/LocalCacheConfig.xml - commons-jcs - Git at Google

 <?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>Configuring the Local Cache</title>
     <author email="pete@kazmier.com">Pete Kazmier</author>
     <author email="ASmuts@therealm.com">Aaron Smuts</author>
   </properties>

   <body>
     <section name="Configuring the Local Cache">
       <p>
         This document is intended to provide various answers to
         questions regarding the configuration of a local cache.  The
         document is presented in a question / answer format.
       </p>
       <subsection name="Where is the configuration information?">
         <p>
           Configuration of local caches involves editing the cache
           configuration file, named <code>cache.ccf</code>.  The
           classpath should include the directory where this file is
           located or the file should be placed at the root of the
           classpath, since it is discovered automatically.
         </p>
       </subsection>
       <subsection name="What is in the cache.ccf file?">
         <p>
           The <code>cache.ccf</code> file contains default configuration
           information for cache regions and specific configuration
           information for regions that you predefine.  Regions not using
           default behaviors should generally be configured via the
           <code>cache.ccf</code> file.  If you can put configuration
           information in a class, you can edit a props file just as
           easily.  This makes modification of the regional setting more
           efficient and allows for startup error checking.
         </p>
         <p>
           There are three main sections of the <code>cache.ccf</code>
           file:
         </p>
         <ul>
           <li> the default and system settings </li>
           <li> the region specific settings </li>
           <li> the auxiliary cache definitions </li>
         </ul>
       </subsection>
       <subsection name="How do I set up default values for regions?">
         <p>
           You can establish default values that any non-preconfigured
           region will inherit.  The non-predefined region will be
           created when you call
           <code>CacheAccess.getAccess("cacheName")</code>.  The default
           setting look like this:
         </p>
         <source><![CDATA[
 # DEFAULT CACHE REGION

 # sets the default aux value for any non configured caches
 jcs.default=DC,RFailover
 jcs.default.cacheattributes=
     org.apache.commons.jcs3.engine.CompositeCacheAttributes
 jcs.default.cacheattributes.MaxObjects=1000
         ]]></source>
         <p>
           The most important line is
           <code>jcs.default=DC,Rfailover</code>. This tells the cache
           what auxiliary caches should be used.  Auxiliary caches are
           configured in the third section of the <code>cache.ccf</code>
           and are referenced in a comma separated list.  You can add as
           many auxiliary caches as you want, but the behavior of remote
           and lateral auxiliaries may conflict.  This allows you to
           define different configurations for auxiliary caches and to
           use these different configurations for different regions.
         </p>
       </subsection>
       <subsection name="How do I define a region?">
         <p>
           Defining a region involves specifying which auxiliary caches
           it will use and how many objects it will store in memory.  A
           typical region definition looks like:
         </p>
         <source><![CDATA[
 jcs.region.testCache=DC,RFailover
 jcs.region.testCache.cacheattributes=
     org.apache.commons.jcs3.engine.CompositeCacheAttributes
 jcs.region.testCache.cacheattributes.MaxObjects=1000
         ]]></source>
         <p>
           The region name is <code>testCache</code>.  It will have a
           1000 item memory limit and will use the DC and RFailover
           auxiliary caches.  If a typical element for this region was
           very large, you might want to lower the number of items stored
           in memory.  The size of the memory storage is dependent on the
           priority of the cache, the size of its elements, and the
           amount of RAM on the machine.
         </p>
       </subsection>
       <subsection name="How do I configure an auxiliary cache?">
         <p>
           Each auxiliary cache is created through a factory that passes
           an attribute object to the constructor.  The attributes are
           set via reflection and should be fairly simple to understand.
           Each auxiliary cache will be fully documented.  Plugging in
           your own auxiliary cache become a simple matter given the
           reflexive manner of initialization.
         </p>
         <p>
           The most important settings for common usage are the disk path
           and the remote cache location.  It is recommended that only
           disk and remote auxiliaries be used.  The lateral caches are
           functional but not as efficient.
         </p>
         <p>
           The default configuration code above specifies that
           non-preconfigured caches use the auxiliary cache by the name
           DC.  This cache is defined in the third section of the file:
         </p>
         <source><![CDATA[
 jcs.auxiliary.DC=
     org.apache.commons.jcs3.auxiliary.disk.DiskCacheFactory
 jcs.auxiliary.DC.attributes=
     org.apache.commons.jcs3.auxiliary.disk.DiskCacheAttributes
 jcs.auxiliary.DC.attributes.DiskPath=c:/dev/cache/raf
         ]]></source>
         <p>
           The only thing that needs to be set here is the
           <code>DiskPath</code> value.  Change it to wherever you want
           the cache to persist unused items.
         </p>
         <p>
           The default region is also set to use an auxiliary called
           <code>RFailover</code>.  This is a remote cache that is
           designed to failover to other remote servers in a cluster:
         </p>
         <source><![CDATA[
 jcs.auxiliary.RFailover=
     org.apache.commons.jcs3.auxiliary.remote.RemoteCacheFactory
 jcs.auxiliary.RFailover.attributes=
     org.apache.commons.jcs3.auxiliary.remote.RemoteCacheAttributes
 jcs.auxiliary.RFailover.attributes.RemoteTypeName=LOCAL
 jcs.auxiliary.RFailover.attributes.FailoverServers=
     localhost:1102,localhost:1101
         ]]></source>
         <p>
           If you don't have more than one remote server running, just
           specify it by itself in the <code>FailoverServers</code>
           attribute.
         </p>
       </subsection>
     </section>
   </body>
 </document>
	<?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>Configuring the Local Cache</title>
	<author email="pete@kazmier.com">Pete Kazmier</author>
	<author email="ASmuts@therealm.com">Aaron Smuts</author>
	</properties>

	<body>
	<section name="Configuring the Local Cache">
	<p>
	This document is intended to provide various answers to
	questions regarding the configuration of a local cache. The
	document is presented in a question / answer format.
	</p>
	<subsection name="Where is the configuration information?">
	<p>
	Configuration of local caches involves editing the cache
	configuration file, named <code>cache.ccf</code>. The
	classpath should include the directory where this file is
	located or the file should be placed at the root of the
	classpath, since it is discovered automatically.
	</p>
	</subsection>
	<subsection name="What is in the cache.ccf file?">
	<p>
	The <code>cache.ccf</code> file contains default configuration
	information for cache regions and specific configuration
	information for regions that you predefine. Regions not using
	default behaviors should generally be configured via the
	<code>cache.ccf</code> file. If you can put configuration
	information in a class, you can edit a props file just as
	easily. This makes modification of the regional setting more
	efficient and allows for startup error checking.
	</p>
	<p>
	There are three main sections of the <code>cache.ccf</code>
	file:
	</p>
	<ul>
	<li> the default and system settings </li>
	<li> the region specific settings </li>
	<li> the auxiliary cache definitions </li>
	</ul>
	</subsection>
	<subsection name="How do I set up default values for regions?">
	<p>
	You can establish default values that any non-preconfigured
	region will inherit. The non-predefined region will be
	created when you call
	<code>CacheAccess.getAccess("cacheName")</code>. The default
	setting look like this:
	</p>
	<source><![CDATA[
	# DEFAULT CACHE REGION

	# sets the default aux value for any non configured caches
	jcs.default=DC,RFailover
	jcs.default.cacheattributes=
	org.apache.commons.jcs3.engine.CompositeCacheAttributes
	jcs.default.cacheattributes.MaxObjects=1000
	]]></source>
	<p>
	The most important line is
	<code>jcs.default=DC,Rfailover</code>. This tells the cache
	what auxiliary caches should be used. Auxiliary caches are
	configured in the third section of the <code>cache.ccf</code>
	and are referenced in a comma separated list. You can add as
	many auxiliary caches as you want, but the behavior of remote
	and lateral auxiliaries may conflict. This allows you to
	define different configurations for auxiliary caches and to
	use these different configurations for different regions.
	</p>
	</subsection>
	<subsection name="How do I define a region?">
	<p>
	Defining a region involves specifying which auxiliary caches
	it will use and how many objects it will store in memory. A
	typical region definition looks like:
	</p>
	<source><![CDATA[
	jcs.region.testCache=DC,RFailover
	jcs.region.testCache.cacheattributes=
	org.apache.commons.jcs3.engine.CompositeCacheAttributes
	jcs.region.testCache.cacheattributes.MaxObjects=1000
	]]></source>
	<p>
	The region name is <code>testCache</code>. It will have a
	1000 item memory limit and will use the DC and RFailover
	auxiliary caches. If a typical element for this region was
	very large, you might want to lower the number of items stored
	in memory. The size of the memory storage is dependent on the
	priority of the cache, the size of its elements, and the
	amount of RAM on the machine.
	</p>
	</subsection>
	<subsection name="How do I configure an auxiliary cache?">
	<p>
	Each auxiliary cache is created through a factory that passes
	an attribute object to the constructor. The attributes are
	set via reflection and should be fairly simple to understand.
	Each auxiliary cache will be fully documented. Plugging in
	your own auxiliary cache become a simple matter given the
	reflexive manner of initialization.
	</p>
	<p>
	The most important settings for common usage are the disk path
	and the remote cache location. It is recommended that only
	disk and remote auxiliaries be used. The lateral caches are
	functional but not as efficient.
	</p>
	<p>
	The default configuration code above specifies that
	non-preconfigured caches use the auxiliary cache by the name
	DC. This cache is defined in the third section of the file:
	</p>
	<source><![CDATA[
	jcs.auxiliary.DC=
	org.apache.commons.jcs3.auxiliary.disk.DiskCacheFactory
	jcs.auxiliary.DC.attributes=
	org.apache.commons.jcs3.auxiliary.disk.DiskCacheAttributes
	jcs.auxiliary.DC.attributes.DiskPath=c:/dev/cache/raf
	]]></source>
	<p>
	The only thing that needs to be set here is the
	<code>DiskPath</code> value. Change it to wherever you want
	the cache to persist unused items.
	</p>
	<p>
	The default region is also set to use an auxiliary called
	<code>RFailover</code>. This is a remote cache that is
	designed to failover to other remote servers in a cluster:
	</p>
	<source><![CDATA[
	jcs.auxiliary.RFailover=
	org.apache.commons.jcs3.auxiliary.remote.RemoteCacheFactory
	jcs.auxiliary.RFailover.attributes=
	org.apache.commons.jcs3.auxiliary.remote.RemoteCacheAttributes
	jcs.auxiliary.RFailover.attributes.RemoteTypeName=LOCAL
	jcs.auxiliary.RFailover.attributes.FailoverServers=
	localhost:1102,localhost:1101
	]]></source>
	<p>
	If you don't have more than one remote server running, just
	specify it by itself in the <code>FailoverServers</code>
	attribute.
	</p>
	</subsection>
	</section>
	</body>
	</document>