| <?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.jcs.engine.CompositeCacheAttributes |
| jcs.default.cacheattributes.MaxObjects=1000 |
| 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.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> |