xdocs/ElementAttributes.xml (136 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>Element Attribute Configuration</title>
<author email="ASmuts@apache.org">Aaron Smuts</author>
</properties>
<body>
<section name="Element Attribute Configuration">
<p>
The following document describes the various
configuration options available for cache elements. Each
element put into the cache can be configured
independently. You can define element behavior in three
ways: as a default setting, as a region setting, or at
the element level.
</p>
<subsection name="Setting the defaults">
<p>
The configuration below can be put in the cache.ccf
configuration file. It establishes the default
behavior for all regions. A region can override
these defaults and an individual element can override
these defaults and the region settings.
</p>
<source>
<![CDATA[
# DEFAULT CACHE REGION
jcs.default=DC
jcs.default.cacheattributes=
org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=1000
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.IdleTime=1800
jcs.default.elementattributes.IsSpool=true
jcs.default.elementattributes.IsRemote=true
jcs.default.elementattributes.IsLateral=true
]]>
</source>
<p>
The default and region configuration settings have
three components. They define what auxiliaries are
available, how the cache should control the memory,
and how the elements should behave. This
configuration tells all regions to use an auxiliary
called DC by default. It also establishes several
settings for memory management (see
<a href="BasicJCSConfiguration.html">
Basic JCS Configuration
</a>
for more information on the cacheattribute
settings). In addition, by default all regions will
take these element configuration settings.
</p>
<p>
These settings specify that elements are not
eternal, i.e. they can expire. By default elements
are considered eternal.
</p>
<p>
You can define the maximum life of an item by
setting the
<code>MaxLife</code>
parameter. If an item has been in the cache for
longer than the set number of seconds it will not be
retrieved on a get request. If you use the memory
shrinker the item will be actively removed from
memory. Currently there is no background disk
shrinker, but the disk cache does allow for a
maximum number of keys (see
<a href="IndexedDiskAuxCache.html">
Indexed Disk Cache
</a>
for more information on the disk cache settings).
</p>
<p>
You can define the maximum time an item can live
without being accessed by setting the
<code>IdleTime</code>
parameter. This is different than the
<code>MaxMemoryIdleTimeSeconds</code>
parameter, which just specifies how long an object
can be in memory before it is subjected to removal
or being spooled to a disk cache if it is available.
Note: the
<code>IdleTime</code>
parameter may not function properly for items
retrieved from disk, if you have a memory size of 0.
</p>
</subsection>
<p>
<code>IsSpool</code>
determines whether or not the element can go to disk, if
a disk cache is configured for the region.
</p>
<p>
<code>IsRemote</code>
determines whether or not the element can be sent to a
remote server, if one is configured for the region.
</p>
<p>
<code>IsLateral</code>
determines whether or not the element can be laterally
distributed, if a lateral auxiliary is configured for
the region.
</p>
<subsection name="Programmatic Configuration">
<p>
Every element put into the cache has its own set of
attributes. By default elements are given a copy of
the default element attributes associated with a
region. You can also specify the attributes to use
for an element when you put it in the cache.
</p>
<source>
<![CDATA[
CacheAccess<String, String> jcs = JCS.getInstance( "myregion" );
. . .
// jcs.getDefaultElementAttributes returns a copy not a reference
IElementAttributes attributes = jcs.getDefaultElementAttributes();
// set some special value
attributes.setIsEternal( true );
jcs.put( "key", "data", attributes );
]]>
</source>
<p>
You can also programmatically modify the default
element attributes.
</p>
<source>
<![CDATA[
CacheAccess<String, String> jcs = JCS.getInstance( "myregion" );
. . .
// jcs.getDefaultElementAttributes returns a copy not a reference
IElementAttributes attributes = jcs.getDefaultElementAttributes();
// set some special value
attributes.setIsEternal( true );
jcs.setDefaultElementAttributes( attributes );
]]>
</source>
</subsection>
</section>
</body>
</document>