You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by tv...@apache.org on 2026/02/09 16:03:21 UTC
(commons-jcs) 02/05: Document immutable records for element attributes
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 <tv...@apache.org>
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>