This is an automated email from the ASF dual-hosted git repository. tv pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-jcs.git
commit 73e5889081a274641697a33f604b3dd313a6bb06 Author: Thomas Vandahl <[email protected]> AuthorDate: Mon Feb 9 16:51:28 2026 +0100 Document immutable records for element attributes --- .../jcs4/engine/control/CompositeCache.java | 10 +- .../jcs4/engine/control/CompositeCacheManager.java | 2 +- xdocs/ElementAttributes.xml | 187 +++++++++++---------- 3 files changed, 104 insertions(+), 95 deletions(-) diff --git a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/engine/control/CompositeCache.java b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/engine/control/CompositeCache.java index dbd75c08..e6cf7b1b 100644 --- a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/engine/control/CompositeCache.java +++ b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/engine/control/CompositeCache.java @@ -43,7 +43,6 @@ import org.apache.commons.jcs4.access.exception.CacheException; import org.apache.commons.jcs4.access.exception.ObjectNotFoundException; import org.apache.commons.jcs4.auxiliary.AuxiliaryCache; import org.apache.commons.jcs4.engine.CacheStatus; -import org.apache.commons.jcs4.engine.ElementAttributes; import org.apache.commons.jcs4.engine.behavior.ICache; import org.apache.commons.jcs4.engine.behavior.ICacheElement; import org.apache.commons.jcs4.engine.behavior.ICompositeCacheAttributes; @@ -500,18 +499,13 @@ public class CompositeCache<K, V> } /** - * Gets the default element attribute of the Cache object This returns a copy. It does not - * return a reference to the attributes. + * Gets the default element attribute of the Cache object. * * @return The attributes value */ public IElementAttributes getElementAttributes() { - if (attr != null) - { - return new ElementAttributes(attr); - } - return null; + return attr; } /** diff --git a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/engine/control/CompositeCacheManager.java b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/engine/control/CompositeCacheManager.java index b139178a..2749e124 100644 --- a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/engine/control/CompositeCacheManager.java +++ b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/engine/control/CompositeCacheManager.java @@ -613,7 +613,7 @@ public class CompositeCacheManager */ public IElementAttributes getDefaultElementAttributes() { - return new ElementAttributes(this.defaultElementAttr); + return this.defaultElementAttr; } /** diff --git a/xdocs/ElementAttributes.xml b/xdocs/ElementAttributes.xml index 33014716..5b9164c9 100644 --- a/xdocs/ElementAttributes.xml +++ b/xdocs/ElementAttributes.xml @@ -36,14 +36,14 @@ </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> + <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 @@ -56,121 +56,136 @@ jcs.default.elementattributes.IsEternal=false jcs.default.elementattributes.MaxLife=700 jcs.default.elementattributes.MaxIdleTime=1800 ]]> - </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> + </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 <code>cacheattributes</code> + 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>MaxIdleTime</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>MaxIdleTime</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. + The default is <code>true</code>. </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. + The default is <code>true</code>. </p> <p> <code>IsLateral</code> determines whether or not the element can be laterally distributed, if a lateral auxiliary is configured for the region. + The default is <code>true</code>. </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> + <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(); + // ElementAttributes is an immutable record + IElementAttributes defaultAttributes = jcs.getDefaultElementAttributes(); + + // set some special values + IElementAttributes attributes = new ElementAttributes( + defaultAttributes.isSpool(), + defaultAttributes.isLateral(), + defaultAttributes.isRemote(), + /* isEternal */ false, + /* maxLife */ 1800, + /* maxIdleTime */ 900, + defaultAttributes.timeFactorForMilliseconds()); - // 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> + </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(); + // ElementAttributes is an immutable record + IElementAttributes defaulAttributes = jcs.getDefaultElementAttributes(); + + // set some special values + IElementAttributes attributes = new ElementAttributes( + defaultAttributes.isSpool(), + defaultAttributes.isLateral(), + defaultAttributes.isRemote(), + /* isEternal */ false, + /* maxLife */ 1800, + /* maxIdleTime */ 900, + defaultAttributes.timeFactorForMilliseconds()); - // set some special value - attributes.setIsEternal( true ); jcs.setDefaultElementAttributes( attributes ); ]]> - </source> + </source> </subsection> - </section> </body> </document>
