<?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>Cache Region Configuration</title>
		<author email="ASmuts@apache.org">Aaron Smuts</author>
	</properties>

	<body>
		<section name="Cache Region Configuration">

			<p>
				The following properties apply to any cache region. They
				can be specified as default values and specified on a
				region by region basis. There are three types of
				settings: auxiliary, cache, and element. The cache
				settings define the memory management for the region.
				The element settings define default element behavior
				within the region.
			</p>

			<subsection name="Region (Auxiliary) Properties">
				<table>
					<tr>
						<th>Property</th>
						<th>Description</th>
						<th>Required</th>
						<th>Default Value</th>
					</tr>
					<tr>
						<td></td>
						<td>
							You can specify the list of auxiliaries that
							regions can use. This has no attribute name.
							The list can be empty, otherwise it should
							be comma delimited.
						</td>
						<td>Y</td>
						<td>n/a</td>
					</tr>
				</table>
			</subsection>

			<subsection name="Region (Cache) Properties">
				<table>
					<tr>
						<th>Property</th>
						<th>Description</th>
						<th>Required</th>
						<th>Default Value</th>
					</tr>
					<tr>
						<td>MaxObjects</td>
						<td>
							The maximum number of items allowed in
							memory. Eviction of elements in excess of
							this number is determined by the memory
							cache. By default JCS uses the LRU memory
							cache.
						</td>
						<td>Y</td>
						<td>n/a</td>
					</tr>
					<tr>
						<td>MemoryCacheName</td>
						<td>
							This property allows you to specify what
							memory manager you would like to use. You
							can create your own memory manager by
							implementing the
							org.apache.commons.jcs.engine.memory.MemoryCache
							interface. Alternatively, you can extend the
							org.apache.commons.jcs.engine.memory.AbstractMemoryCache
							class. Several different memory caches are
							available: two LRU implementations, an LFU,
							and an adaptive replacement algorithm.
						</td>
						<td>N</td>
						<td>
							org.apache.commons.jcs.engine.memory.lru.LRUMemoryCache
						</td>
					</tr>
					<tr>
						<td>UseMemoryShrinker</td>
						<td>
							By default, the memory shrinker is shared by
							all regions that use the LRU memory cache.
							The memory shrinker iterates through the
							items in memory, looking for items that have
							expired or that have exceeded their max
							memory idle time.
						</td>
						<td>N</td>
						<td>false</td>
					</tr>
					<tr>
						<td>MaxMemoryIdleTimeSeconds</td>
						<td>
							This is only used if you are using the
							memory shrinker. If this value is set above
							-1, then if an item has not been accessed in
							this number of seconds, it will be spooled
							to disk if the disk is available. You can
							register an event handler on this event.
						</td>
						<td>N</td>
						<td>7200</td>
					</tr>
					<tr>
						<td>ShrinkerIntervalSeconds</td>
						<td>
							This specifies how often the shrinker should
							run, if it has been activated. If you set
							UseMemoryShrinker to false, then this
							setting has no effect.
						</td>
						<td>N</td>
						<td>30</td>
					</tr>
					<tr>
						<td>DiskUsagePatternName</td>
						<td>
							SWAP is the default. Under the swap pattern,
							data is only put to disk when the max memory
							size is reached. Since items puled from disk
							are put into memory, if the memory cache is
							full and you get an item off disk, the lest
							recently used item will be spooled to disk.
							If you have a low memory hit ration, you end
							up thrashing.

							The UPDATE usage pattern allows items to go
							to disk on an update. It disables the swap.
							This allows you to persist all items to
							disk. If you are using the JDBC disk cache
							for instance, you can put all the items on
							disk while using the memory cache for
							performance, and not worry about losing
							data from a system crash or improper
							shutdown. Also, since all items are on disk,
							there is no need to swap to disk. This
							prevents the possibility of thrashing.
						</td>
						<td>N</td>
						<td>SWAP</td>
					</tr>
				</table>
			</subsection>

			<subsection name="Region (Element) Properties">
				<table>
					<tr>
						<th>Property</th>
						<th>Description</th>
						<th>Required</th>
						<th>Default Value</th>
					</tr>
					<tr>
						<td>IsEternal</td>
						<td>
							If an element is specified as eternal, then
							it will never be subject to removal for
							exceeding its max life.
						</td>
						<td>N</td>
						<td>true</td>
					</tr>
					<tr>
						<td>MaxLife</td>
						<td>
							If you specify that elements within a region
							are not eternal, then you can set the max
							life seconds. If this is exceeded the
							elements will be removed passively when a
							client tries to retrieve them. If you are
							using a memory shrinker, then the items can
							be removed actively.
						</td>
						<td>N</td>
						<td>-1</td>
					</tr>
					<tr>
						<td>IsSpool</td>
						<td>
							By default, can elements in this region be
							sent to a disk cache if one is available.
						</td>
						<td>N</td>
						<td>true</td>
					</tr>
					<tr>
                        <td>IsLateral</td>
						<td>
							By default, can elements in this region be
							sent to a lateral cache if one is available.
						</td>
						<td>N</td>
						<td>true</td>
					</tr>
					<tr>
                        <td>IsRemote</td>
						<td>
							By default, can elements in this region be
							sent to a remote cache if one is available.
						</td>
						<td>N</td>
						<td>true</td>
					</tr>
				</table>
			</subsection>

			<subsection name="Example Configuration">
				<source>
					<![CDATA[
jcs.default=
jcs.default.cacheattributes=org.apache.commons.jcs.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=200001
jcs.default.cacheattributes.MemoryCacheName=org.apache.commons.jcs.engine.memory.lru.LRUMemoryCache
jcs.default.cacheattributes.UseMemoryShrinker=true
jcs.default.cacheattributes.MaxMemoryIdleTimeSeconds=3600
jcs.default.cacheattributes.ShrinkerIntervalSeconds=60
jcs.default.elementattributes=org.apache.commons.jcs.engine.ElementAttributes
jcs.default.elementattributes.IsEternal=false
jcs.default.elementattributes.MaxLife=700
jcs.default.elementattributes.IsSpool=true
jcs.default.elementattributes.IsRemote=true
jcs.default.elementattributes.IsLateral=true

# optional region "testCache1" specific configuration settings
jcs.region.testCache1=
jcs.region.testCache1.cacheattributes=org.apache.commons.jcs.engine.CompositeCacheAttributes
jcs.region.testCache1.cacheattributes.MaxObjects=123456
jcs.region.testCache1.cacheattributes.MemoryCacheName=org.apache.commons.jcs.engine.memory.lru.LRUMemoryCache
jcs.region.testCache1.cacheattributes.UseMemoryShrinker=true
jcs.region.testCache1.cacheattributes.ShrinkerIntervalSeconds=30
jcs.region.testCache1.cacheattributes.MaxMemoryIdleTimeSeconds=300
jcs.region.testCache1.cacheattributes.MaxSpoolPerRun=100
jcs.region.testCache1.elementattributes=org.apache.commons.jcs.engine.ElementAttributes
jcs.region.testCache1.elementattributes.IsEternal=false
jcs.region.testCache1.elementattributes.MaxLife=60000
jcs.region.testCache1.elementattributes.IsSpool=true
jcs.region.testCache1.elementattributes.IsLateral=true
jcs.region.testCache1.elementattributes.IsRemote=true
        ]]>
				</source>
			</subsection>

		</section>
	</body>
</document>
