xdocs/RegionProperties.xml (205 lines of code) (raw):
<?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.jcs3.engine.memory.MemoryCache
interface. Alternatively, you can extend the
org.apache.commons.jcs3.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.jcs3.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.jcs3.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=200001
jcs.default.cacheattributes.MemoryCacheName=org.apache.commons.jcs3.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.jcs3.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.jcs3.engine.CompositeCacheAttributes
jcs.region.testCache1.cacheattributes.MaxObjects=123456
jcs.region.testCache1.cacheattributes.MemoryCacheName=org.apache.commons.jcs3.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.jcs3.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>