xdocs/ElementAttributes.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>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>
	<?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>