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 acd25b001c92c7d45796686428cd62efc5571608 Author: Thomas Vandahl <[email protected]> AuthorDate: Thu Mar 19 14:21:36 2026 +0100 Document disk cache attributes --- .../commons/jcs4/admin/CacheElementInfo.java | 2 +- .../org/apache/commons/jcs4/admin/JCSAdmin.jsp | 2 +- .../disk/AbstractDiskCacheAttributes.java | 16 +-- .../jcs4/auxiliary/disk/block/BlockDisk.java | 30 ----- .../jcs4/auxiliary/disk/block/BlockDiskCache.java | 14 +-- .../disk/block/BlockDiskCacheAttributes.java | 25 ++-- .../disk/indexed/IndexedDiskCacheAttributes.java | 14 +-- .../auxiliary/disk/block/BlockDiskUnitTest.java | 2 +- .../src/test/test-conf/TestJCS-73.ccf | 2 +- src/changes/changes.xml | 3 + src/site/xdoc/BlockDiskCache.xml | 131 +++++++++++++++----- src/site/xdoc/IndexedDiskAuxCache.xml | 15 +-- src/site/xdoc/IndexedDiskCacheProperties.xml | 135 ++++++++++++--------- 13 files changed, 223 insertions(+), 168 deletions(-) diff --git a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/admin/CacheElementInfo.java b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/admin/CacheElementInfo.java index d31274dd..bb58c4f7 100644 --- a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/admin/CacheElementInfo.java +++ b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/admin/CacheElementInfo.java @@ -52,7 +52,7 @@ public record CacheElementInfo( buf.append( "\n Key [" ).append( key() ).append( "]" ); buf.append( "\n Eternal [" ).append( eternal() ).append( "]" ); buf.append( "\n CreateTime [" ).append( createTime() ).append( "]" ); - buf.append( "\n MaxLifeSeconds [" ).append( maxLife() ).append( "]" ); + buf.append( "\n MaxLife [" ).append( maxLife() ).append( "]" ); buf.append( "\n ExpiresInSeconds [" ).append( expiresInSeconds() ).append( "]" ); return buf.toString(); diff --git a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/admin/JCSAdmin.jsp b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/admin/JCSAdmin.jsp index b24d585c..203b15b7 100644 --- a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/admin/JCSAdmin.jsp +++ b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/admin/JCSAdmin.jsp @@ -218,7 +218,7 @@ <td><%=element.key()%></td> <td><%=element.eternal()%></td> <td><%=element.createTime()%></td> - <td><%=element.maxLifeSeconds()%></td> + <td><%=element.maxLife()%></td> <td><%=element.expiresInSeconds()%></td> <td> <a href="?action=item&cacheName=<%=cacheName%>&key=<%=element.key()%>"> View </a> diff --git a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/AbstractDiskCacheAttributes.java b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/AbstractDiskCacheAttributes.java index 76afb770..571b9e61 100644 --- a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/AbstractDiskCacheAttributes.java +++ b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/AbstractDiskCacheAttributes.java @@ -187,12 +187,11 @@ public abstract class AbstractDiskCacheAttributes extends AbstractAuxiliaryCache * The default is 60 seconds. * <p> * - * @param shutdownSpoolTimeLimit - * the time in seconds + * @param shutdownSpoolTimeLimit the time */ - public void setShutdownSpoolTimeLimit(final int shutdownSpoolTimeLimit) + public void setShutdownSpoolTimeLimit(final Duration shutdownSpoolTimeLimit) { - this.shutdownSpoolTimeLimit = Duration.ofSeconds(shutdownSpoolTimeLimit); + this.shutdownSpoolTimeLimit = shutdownSpoolTimeLimit; } /** @@ -206,10 +205,11 @@ public abstract class AbstractDiskCacheAttributes extends AbstractAuxiliaryCache { final StringBuilder str = new StringBuilder(); str.append("AbstractDiskCacheAttributes "); - str.append("\n diskPath = " + getDiskPath()); - str.append("\n maxPurgatorySize = " + getMaxPurgatorySize()); - str.append("\n allowRemoveAll = " + isAllowRemoveAll()); - str.append("\n ShutdownSpoolTimeLimit = " + getShutdownSpoolTimeLimit()); + str.append("\n DiskPath = ").append(getDiskPath()); + str.append("\n DiskLimitType = ").append(getDiskLimitType()); + str.append("\n MaxPurgatorySize = ").append(getMaxPurgatorySize()); + str.append("\n AllowRemoveAll = ").append(isAllowRemoveAll()); + str.append("\n ShutdownSpoolTimeLimit = ").append(getShutdownSpoolTimeLimit()); return str.toString(); } } diff --git a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDisk.java b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDisk.java index bb296a62..9f60bb03 100644 --- a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDisk.java +++ b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDisk.java @@ -30,7 +30,6 @@ import java.util.concurrent.atomic.AtomicLong; import org.apache.commons.jcs4.engine.behavior.IElementSerializer; import org.apache.commons.jcs4.log.Log; -import org.apache.commons.jcs4.utils.serialization.StandardSerializer; /** * This class manages reading an writing data to disk. When asked to write a value, it returns a @@ -45,9 +44,6 @@ public class BlockDisk implements AutoCloseable public static final byte HEADER_SIZE_BYTES = 4; // 4 bytes is the size used for ByteBuffer.putInt(int value) and ByteBuffer.getInt() - /** Defaults to 4kb */ - private static final int DEFAULT_BLOCK_SIZE_BYTES = 4 * 1024; - /** Size of the blocks */ private final int blockSizeBytes; @@ -75,32 +71,6 @@ public class BlockDisk implements AutoCloseable /** How many items have we put to disk */ private final AtomicLong putCount = new AtomicLong(); - /** - * Constructor for the Disk object - * - * @param file - * @param elementSerializer - * @throws IOException - */ - public BlockDisk(final File file, final IElementSerializer elementSerializer) - throws IOException - { - this(file, DEFAULT_BLOCK_SIZE_BYTES, elementSerializer); - } - - /** - * Creates the file and set the block size in bytes. - * - * @param file - * @param blockSizeBytes - * @throws IOException - */ - public BlockDisk(final File file, final int blockSizeBytes) - throws IOException - { - this(file, blockSizeBytes, new StandardSerializer()); - } - /** * Creates the file and set the block size in bytes. * diff --git a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskCache.java b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskCache.java index 6dcc7898..fea325dd 100644 --- a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskCache.java +++ b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskCache.java @@ -110,17 +110,9 @@ public class BlockDiskCache<K, V> try { - if ( cacheAttributes.getBlockSizeBytes() > 0 ) - { - this.dataFile = new BlockDisk( new File( rootDirectory, fileName + ".data" ), - cacheAttributes.getBlockSizeBytes(), - getElementSerializer() ); - } - else - { - this.dataFile = new BlockDisk( new File( rootDirectory, fileName + ".data" ), - getElementSerializer() ); - } + this.dataFile = new BlockDisk( new File( rootDirectory, fileName + ".data" ), + cacheAttributes.getBlockSizeBytes(), + getElementSerializer() ); keyStore = new BlockDiskKeyStore<>( cacheAttributes, this ); diff --git a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskCacheAttributes.java b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskCacheAttributes.java index 177b8071..6ffba82e 100644 --- a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskCacheAttributes.java +++ b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskCacheAttributes.java @@ -32,6 +32,9 @@ public class BlockDiskCacheAttributes /** Don't change */ private static final long serialVersionUID = 6568840097657265989L; + /** Defaults to 4kb */ + private static final int DEFAULT_BLOCK_SIZE_BYTES = 4 * 1024; + /** Maximum number of keys to be kept in memory */ private static final int DEFAULT_MAX_KEY_SIZE = 5000; @@ -39,7 +42,7 @@ public class BlockDiskCacheAttributes private static final Duration DEFAULT_KEY_PERSISTENCE_INTERVAL = Duration.ofSeconds(5 * 60); /** The size per block in bytes. */ - private int blockSizeBytes; + private int blockSizeBytes = DEFAULT_BLOCK_SIZE_BYTES; /** -1 means no limit. */ private int maxKeySize = DEFAULT_MAX_KEY_SIZE; @@ -56,7 +59,7 @@ public class BlockDiskCacheAttributes } /** - * @return the keyPersistenceIntervalSeconds. + * @return the keyPersistenceInterval. */ public Duration getKeyPersistenceInterval() { @@ -82,11 +85,11 @@ public class BlockDiskCacheAttributes } /** - * @param keyPersistenceIntervalSeconds The keyPersistenceIntervalSeconds to set. + * @param keyPersistenceInterval The keyPersistenceInterval to set. */ - public void setKeyPersistenceIntervalSeconds( final long keyPersistenceIntervalSeconds ) + public void setKeyPersistenceInterval(final Duration keyPersistenceInterval) { - this.keyPersistenceInterval = Duration.ofSeconds(keyPersistenceIntervalSeconds); + this.keyPersistenceInterval = keyPersistenceInterval; } /** @@ -106,13 +109,11 @@ public class BlockDiskCacheAttributes public String toString() { final StringBuilder str = new StringBuilder(); - str.append( "\nBlockDiskAttributes " ); - str.append( "\n DiskPath [" + getDiskPath() + "]" ); - str.append( "\n MaxKeySize [" + getMaxKeySize() + "]" ); - str.append( "\n MaxPurgatorySize [" + getMaxPurgatorySize() + "]" ); - str.append( "\n BlockSizeBytes [" + getBlockSizeBytes() + "]" ); - str.append( "\n KeyPersistenceIntervalSeconds [" + getKeyPersistenceInterval() + "]" ); - str.append( "\n DiskLimitType [" + getDiskLimitType() + "]" ); + str.append(super.toString()).append("\n"); + str.append( "BlockDiskAttributes " ); + str.append( "\n MaxKeySize = ").append(getMaxKeySize()); + str.append( "\n blockSizeBytes = ").append(getBlockSizeBytes()); + str.append( "\n keyPersistenceInterval = ").append(getKeyPersistenceInterval()); return str.toString(); } } diff --git a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/indexed/IndexedDiskCacheAttributes.java b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/indexed/IndexedDiskCacheAttributes.java index 2c20290b..738b6299 100644 --- a/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/indexed/IndexedDiskCacheAttributes.java +++ b/commons-jcs4-core/src/main/java/org/apache/commons/jcs4/auxiliary/disk/indexed/IndexedDiskCacheAttributes.java @@ -140,14 +140,12 @@ public class IndexedDiskCacheAttributes public String toString() { final StringBuilder str = new StringBuilder(); - str.append( "IndexedDiskCacheAttributes " ); - str.append( "\n diskPath = " + super.getDiskPath() ); - str.append( "\n maxPurgatorySize = " + super.getMaxPurgatorySize() ); - str.append( "\n maxKeySize = " + maxKeySize ); - str.append( "\n optimizeAtRemoveCount = " + optimizeAtRemoveCount ); - str.append( "\n shutdownSpoolTimeLimit = " + super.getShutdownSpoolTimeLimit() ); - str.append( "\n optimizeOnShutdown = " + optimizeOnShutdown ); - str.append( "\n clearDiskOnStartup = " + clearDiskOnStartup ); + str.append(super.toString()).append("\n"); + str.append( "IndexedDiskCacheAttributes" ); + str.append( "\n MaxKeySize = ").append(maxKeySize); + str.append( "\n OptimizeAtRemoveCount = ").append(optimizeAtRemoveCount); + str.append( "\n OptimizeOnShutdown = ").append(optimizeOnShutdown); + str.append( "\n ClearDiskOnStartup = ").append(clearDiskOnStartup); return str.toString(); } } diff --git a/commons-jcs4-core/src/test/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskUnitTest.java b/commons-jcs4-core/src/test/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskUnitTest.java index 21641ae5..5e0d1c03 100644 --- a/commons-jcs4-core/src/test/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskUnitTest.java +++ b/commons-jcs4-core/src/test/java/org/apache/commons/jcs4/auxiliary/disk/block/BlockDiskUnitTest.java @@ -69,7 +69,7 @@ class BlockDiskUnitTest { final File file = new File(rafDir, fileName + ".data"); file.delete(); - this.disk = new BlockDisk(file, new StandardSerializer()); + this.disk = new BlockDisk(file, 4096, new StandardSerializer()); } private void setUpBlockDisk(final String fileName, final int blockSize) throws IOException diff --git a/commons-jcs4-core/src/test/test-conf/TestJCS-73.ccf b/commons-jcs4-core/src/test/test-conf/TestJCS-73.ccf index d790c946..f60d222f 100644 --- a/commons-jcs4-core/src/test/test-conf/TestJCS-73.ccf +++ b/commons-jcs4-core/src/test/test-conf/TestJCS-73.ccf @@ -30,7 +30,7 @@ jcs.auxiliary.CACHE=org.apache.commons.jcs4.auxiliary.disk.indexed.IndexedDiskCa jcs.auxiliary.CACHE.attributes.DiskPath=target/test-sandbox/concurrent_cache jcs.auxiliary.CACHE.attributes.MaxPurgatorySize=-1 jcs.auxiliary.CACHE.attributes.MaxKeySize=-1 -jcs.auxiliary.CACHE.attributes.ShutdownSpoolTimeLimit=60 +jcs.auxiliary.CACHE.attributes.ShutdownSpoolTimeLimit=PT1m jcs.auxiliary.CACHE.attributes.OptimizeAtRemoveCount=30000 jcs.auxiliary.CACHE.attributes.OptimizeOnShutdown=true jcs.auxiliary.CACHE.attributes.EventQueueType=SINGLE diff --git a/src/changes/changes.xml b/src/changes/changes.xml index a9504454..8d75f096 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -76,6 +76,9 @@ behavior. </action> <!-- UPDATE --> + <action dev="tv" type="update"> + Introduce java.time.Duration for all time-related configuration parameters + </action> <action dev="tv" type="update"> Most immutable data container classes have been moved to Java records </action> diff --git a/src/site/xdoc/BlockDiskCache.xml b/src/site/xdoc/BlockDiskCache.xml index 2a4c01ba..81ac3e63 100644 --- a/src/site/xdoc/BlockDiskCache.xml +++ b/src/site/xdoc/BlockDiskCache.xml @@ -26,40 +26,109 @@ <body> <section name="Block Disk Auxiliary Cache"> + <p> + The Block Disk Cache stores cached values on disk. Like + the Indexed Disk Cache, the Block Disk Cache keeps the + keys in memory. The Block Disk Cache stores the values + in a group of fixed size blocks, whereas the Indexed + Disk Cache writes items to disk in one chunk. + </p> + <p> + The Block Disk Cache has advantages over the normal + indexed model for regions where the size of the items + varies. Since all the blocks are the same size, the + recycle bin is very simple. It is just a list of block + numbers. Also, the Block Disk Cache will never need to + be optimized. Once the maximum number of keys is + reached, blocks will be reused. + </p> + + <subsection name="Size limitation"> <p> - The Block Disk Cache stores cached values on disk. Like - the Indexed Disk Cache, the Block Disk Cache keeps the - keys in memory. The Block Disk Cache stores the values - in a group of fixed size blocks, whereas the Indexed - Disk Cache writes items to disk in one chunk. - </p> - <p> - The Block Disk Cache has advantages over the normal - indexed model for regions where the size of the items - varies. Since all the blocks are the same size, the - recycle bin is very simple. It is just a list of block - numbers. Also, the Block Disk Cache will never need to - be optimized. Once the maximum number of keys is - reached, blocks will be reused. + There are two ways to limit the cache size: using element + count and element size. When using element count, in disk + store there will be at most MaxKeySize elements (not disk + blocks). When using element size, there will be at most + KeySize kB of elements stored in the data file. As the Block + Disk Cache doesn't need optimization, the data file + will be not longer than specified. The limit does not + cover the key file size. The mode is chosen using DiskLimitType. + Allowed values are: COUNT and SIZE. </p> - - <section name="Size limitation"> - <p> - There are two ways to limit the cache size: using element - count and element size. When using element count, in disk - store there will be at most MaxKeySize elements (not disk - blocks). When using element size, there will be at most - KeySize kB of elements stored in the data file. As the Block - Disk Cache doesn't need optimization, the data file - will be not longer than specified. The limit does not - cover the key file size. The mode is chosen using DiskLimitType. - Allowed values are: COUNT and SIZE. - </p> - </section> + </subsection> + + <subsection name="Block Disk Configuration Properties"> + <table> + <tr> + <th>Property</th> + <th>Description</th> + <th>Required</th> + <th>Default Value</th> + </tr> + <tr> + <td>DiskPath</td> + <td>The directory where the disk cache should write its files. + </td> + <td>Y</td> + <td>n/a</td> + </tr> + <tr> + <td>MaxPurgatorySize</td> + <td>The maximum number of items allowed in the queue of items to + be written to disk.</td> + <td>N</td> + <td>5000</td> + </tr> + <tr> + <td>DiskLimitType</td> + <td>There are two ways to limit the cache size: using element + count (COUNT) and element size (SIZE) When using element count, + in disk store there will be at most <code>MaxKeySize</code> + elements. When using element size, there will be at most KeySize kB + of elements stored in the data file.</td> + <td>N</td> + <td>COUNT</td> + </tr> + <tr> + <td>ShutdownSpoolTimeLimit</td> + <td>Sets the amount of time we will wait for elements to move to + disk during shutdown for a particular region.</td> + <td>N</td> + <td>PT1m</td> + </tr> + <tr> + <td>AllowRemoveAll</td> + <td>If this is false, we will not execute remove all.</td> + <td>N</td> + <td>true</td> + </tr> + <tr> + <td>MaxKeySize</td> + <td>The maximum number of keys that the block disk cache can + have. Since the keys are stored in memory, you may want to limit + this number to something reasonable. The default is a bit small.</td> + <td>N</td> + <td>5000</td> + </tr> + <tr> + <td>blockSizeBytes</td> + <td>The size per block in bytes.</td> + <td>N</td> + <td>4096</td> + </tr> + <tr> + <td>keyPersistenceInterval</td> + <td>The keys will be persisted at this interval. + 0 means never.</td> + <td>N</td> + <td>PT5m</td> + </tr> + </table> + </subsection> - <subsection name="Example cache.ccf"> - <source> - <