Apache Commons JCS 3.2.1 配置参数详解
详解 Apache Commons JCS 3.2.1 的 cache.ccf 配置：jcs.default/jcs.region/jcs.auxiliary 参数逐项说明、LRU 内存缓存与 IndexedDiskCache 磁盘持久化生命周期，全部附真实运行回显。
Apache Commons JCS 3.2.1 配置参数详解
目标：逐项讲解 Apache Commons JCS 3.2.1 的
cache.ccf配置——区域定义（jcs.region）、默认属性（jcs.default）、辅助缓存（jcs.auxiliary）、内存淘汰与磁盘持久化参数——每个参数的含义均以真实运行日志回显佐证。以下全部命令与回显均已在 Ubuntu 22.04（x86_64）实测通过。
一、环境信息
本节固定实测基线，所有配置效果验证均基于同一工程。
- 操作系统：Ubuntu 22.04（x86_64）
- JDK：OpenJDK 17.0.20.1
- 构建工具：Apache Maven 3.6.3
- 目标库：Apache Commons JCS 3.2.1（
org.apache.commons:commons-jcs3-core:3.2.1） - 示例工程目录：
/opt/jcs-demo - 配置文件：
/opt/jcs-demo/conf/cache.ccf（以目录方式加入 classpath） - 运行时 classpath 文件：
/opt/jcs-demo/cp.txt（内容仅 core jar 一行） - 磁盘缓存数据目录：
/opt/jcs-demo/disk-cache - 演示程序：
demo.BasicCacheDemo（内存读写与统计）、demo.DiskCacheDemo（磁盘缓存写入/读回，源码见《Apache Commons JCS 3.2.1 常用 API 与工具详解》）
JCS 的全部行为开关都集中在名为 cache.ccf 的 properties 文件中，理解它等于理解 JCS 的运行时形态。
二、前置条件
配置验证需要一个能编译运行的 JCS 工程，先确认依赖与 classpath 就绪。
- 工程已引入
commons-jcs3-core:3.2.1并编译通过（工程搭建全程见《Ubuntu 22.04 安装 Apache Commons JCS 指南》第四章，此处直接复用同一目录）。 - 确认依赖版本解析正确：
cd /opt/jcs-demo && mvn -B dependency:list 2>&1 | grep "commons-jcs3-core"
输出：
[INFO] org.apache.commons:commons-jcs3-core:jar:3.2.1:compile
[INFO] BUILD SUCCESS
- 生成并确认运行时 classpath（仅 core jar，无传递依赖）：
cd /opt/jcs-demo && cat cp.txt
输出：
/root/.m2/repository/org/apache/commons/commons-jcs3-core/3.2.1/commons-jcs3-core-3.2.1.jar
💡 说明：本文所有配置改动只涉及
conf/cache.ccf与 JVM 参数，无需重新编译程序；改配置后直接以第五章同款命令重跑即可观察效果，例如cd /opt/jcs-demo && java -Dfile.encoding=UTF-8 -cp target/classes:conf:$(cat cp.txt) demo.BasicCacheDemo。
三、配置文件位置与加载机制
写配置之前必须搞清楚「JCS 从哪里读配置、读不到会怎样」，这是 3.2.1 最关键的加载语义。
JCS 从 classpath 上查找名为 cache.ccf 的资源（日志显示为 /cache.ccf，表示类路径根），找到后按 properties 解析。实测两种放置方式都有效：src/main/resources（随编译进 target/classes）或独立目录加入 -cp（本文工程采用 conf/）。找不到时不会回退默认配置，而是直接抛 NullPointerException——先实测复现这个行为：
cd /opt/jcs-demo && java -cp target/classes:$(cat cp.txt) demo.BasicCacheDemo
输出：
Oct 14, 2026 10:25:01 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Instance is null, creating with config [/cache.ccf]
Oct 14, 2026 10:25:01 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Creating cache manager from config file: /cache.ccf
Exception in thread "main" java.lang.NullPointerException: inStream parameter is null
at java.base/java.util.Objects.requireNonNull(Objects.java:235)
at java.base/java.util.Properties.load(Properties.java:410)
at org.apache.commons.jcs3.engine.control.CompositeCacheManager.configure(CompositeCacheManager.java:328)
at org.apache.commons.jcs3.engine.control.CompositeCacheManager.getInstance(CompositeCacheManager.java:188)
at org.apache.commons.jcs3.engine.control.CompositeCacheManager.getInstance(CompositeCacheManager.java:163)
at org.apache.commons.jcs3.JCS.getCacheManager(JCS.java:126)
at org.apache.commons.jcs3.JCS.getInstance(JCS.java:144)
at demo.BasicCacheDemo.main(BasicCacheDemo.java:16)
⚠️ 注意：栈顶
Properties.load的inStream parameter is null表明配置流为空——classpath 上没有 cache.ccf 时 3.2.1 直接 NPE。这不是可忽略的警告，应用启动即失败。
把 conf 目录加入 classpath 后配置被加载（后续章节所有回显均在此形态下采集）：
cd /opt/jcs-demo && java -Dfile.encoding=UTF-8 -cp target/classes:conf:$(cat cp.txt) demo.BasicCacheDemo
输出节选（实测；完整回显见《Ubuntu 22.04 安装 Apache Commons JCS 指南》4.6 节）：
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Instance is null, creating with config [/cache.ccf]
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Creating cache manager from config file: /cache.ccf
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheConfigurator
INFO: Parsed regions [diskRegion]
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Finished configuration in 67 ms.
验证点：Parsed regions [diskRegion] 表明配置文件被解析且识别出 diskRegion 区域；/cache.ccf 为类路径资源名，与文件系统路径 /opt/jcs-demo/conf/cache.ccf 并不冲突。
四、参数总览
本文实测配置文件（/opt/jcs-demo/conf/cache.ccf）与配置体系涉及的全部键如下，总览后逐项展开。
# JCS 配置: 仅对 diskRegion 启用索引磁盘缓存
# 内存缓存: LRU, 最多 100 条
# diskRegion: 内存上限 10 条, UPDATE 模式(写入即落盘), 辅助缓存 DC
jcs.region.diskRegion=DC
jcs.region.diskRegion.cacheattributes=org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.region.diskRegion.cacheattributes.MaxObjects=10
jcs.region.diskRegion.cacheattributes.MemoryCacheName=org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache
jcs.region.diskRegion.cacheattributes.DiskUsagePatternName=UPDATE
# DC = IndexedDiskCache, 磁盘文件目录
jcs.auxiliary.DC=org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCacheFactory
jcs.auxiliary.DC.attributes=org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCacheAttributes
jcs.auxiliary.DC.attributes.DiskPath=/opt/jcs-demo/disk-cache
| 配置键 | 作用 | 本文取值 | 实测效果（日志佐证） |
|---|---|---|---|
jcs.region.<名称> | 定义具名区域并绑定辅助缓存 | jcs.region.diskRegion=DC | Parsed regions [diskRegion] |
jcs.region.<名称>.cacheattributes | 区域缓存属性类 | CompositeCacheAttributes 全限定名 | 区域属性构造日志 |
jcs.region.<名称>.cacheattributes.MaxObjects | 内存最多缓存对象数 | 10 | maxObjs = 10 |
jcs.region.<名称>.cacheattributes.MemoryCacheName | 内存缓存淘汰实现 | LRU 全限定名 | initialized MemoryCache for diskRegion |
jcs.region.<名称>.cacheattributes.DiskUsagePatternName | 磁盘写入模式 | UPDATE | diskUsagePattern = UPDATE |
jcs.auxiliary.<名称> | 辅助缓存工厂类 | IndexedDiskCacheFactory 全限定名 | Indexed Disk Cache is alive. |
jcs.auxiliary.<名称>.attributes | 辅助缓存属性类 | IndexedDiskCacheAttributes 全限定名 | Set maxKeySize to: "5,000" |
jcs.auxiliary.<名称>.attributes.DiskPath | 磁盘缓存文件目录 | /opt/jcs-demo/disk-cache | Cache file root directory: /opt/jcs-demo/disk-cache |
jcs.default.cacheattributes | 默认区域属性（未显式定义区域的兜底） | 本文未写该键 | 走内置默认 maxObjs = 100 |
jcs.region.<名称>.elementattributes | 元素属性（过期等） | 本文未写该键 | 默认 IS_ETERNAL = true |
💡 技术拓展：
MemoryCacheName是一个多选配置——JCS 的内存淘汰策略可插拔。常见策略对比——
策略 淘汰依据 特点 适用场景 LRU（Least Recently Used） 最久未被访问者优先淘汰 命中率与实现复杂度均衡，JCS 默认选择 通用读多写少负载（本文实测采用） LFU（Least Frequently Used） 访问频率最低者优先淘汰 保护热点数据，冷热区分明显 访问频次分布集中的场景 FIFO（First In First Out） 先入先出 实现最简单，不感知访问模式 顺序访问、淘汰策略要求宽松 本文实测采用 LRU（
org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache）：JCS 默认实现、日志可见其基于双链表的实现基类AbstractDoubleLinkedListMemoryCache，通用负载下命中率表现稳健。本文实测仅覆盖 LRU，其余策略更换类名即可启用但未实测。
五、核心参数分类详解
5.1 jcs.default.*：默认区域属性（未定义时的兜底行为）
做什么：jcs.default.cacheattributes 为所有未显式定义的区域提供属性模板。为什么重要：本文实测配置文件故意没有写 jcs.default 键，此时 JCS 回退到内置默认值——理解这份「隐式默认」才能预判未配置区域的行为。
实测回显（demo.BasicCacheDemo 访问未定义区域 demoRegion 时，JUL INFO 日志）：
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Setting default auxiliaries to "null"
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheConfigurator
INFO: No special CompositeCacheAttributes class defined for key [jcs.default.cacheattributes], using default class.
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: setting defaultCompositeCacheAttributes to [ useLateral = true, useRemote = true, useDisk = true, maxObjs = 100, maxSpoolPerRun = -1, diskUsagePattern = SWAP, spoolChunkSize = 2 ]
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheConfigurator
INFO: No special ElementAttribute class defined for key [jcs.default.elementattributes], using default class.
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: setting defaultElementAttributes to [ IS_LATERAL = true, IS_SPOOL = true, IS_REMOTE = true, IS_ETERNAL = true, MaxLifeSeconds = -1, IdleTime = -1, CreateTime = 1791973634659, LastAccessTime = 1791973634659, getTimeToLiveSeconds() = -1, createTime = 1791973634659 ]
逐项解读这份内置默认值：
useLateral = true / useRemote = true / useDisk = true：区域默认允许接入横向同步、远端缓存与磁盘辅助缓存（仅当配置了对应辅助缓存才实际生效；本文只定义了磁盘 DC，lateral/remote 无实例）。maxObjs = 100：内存最多保留 100 个对象，超出后按淘汰策略换出（demoRegion实测即用该默认值，见 5.2 对照）。maxSpoolPerRun = -1：单次后台换盘条数不限（-1 表示不限制）。diskUsagePattern = SWAP：默认磁盘使用模式为「交换」——仅当内存放不下时才写盘（与本文为diskRegion显式设置的 UPDATE 形成对照，见 5.4）。spoolChunkSize = 2：换盘操作的块大小参数（默认值，实测日志原样回显）。- 元素属性默认
IS_ETERNAL = true、MaxLifeSeconds = -1、IdleTime = -1：条目永不过期（不存在时间上限与空闲过期）。
5.2 jcs.region.diskRegion：具名区域定义
做什么：jcs.region.<名称>=<辅助缓存列表> 把一个区域与辅助缓存绑定，并为它单独设定缓存属性。实测配置里 diskRegion 绑定 DC（IndexedDiskCache），内存上限压到 10 条：
jcs.region.diskRegion=DC
jcs.region.diskRegion.cacheattributes=org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.region.diskRegion.cacheattributes.MaxObjects=10
jcs.region.diskRegion.cacheattributes.MemoryCacheName=org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache
jcs.region.diskRegion.cacheattributes.DiskUsagePatternName=UPDATE
实测加载回显：
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.memory.AbstractDoubleLinkedListMemoryCache
INFO: initialized MemoryCache for diskRegion
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: Constructed cache with name [diskRegion] and cache attributes [ useLateral = true, useRemote = true, useDisk = true, maxObjs = 10, maxSpoolPerRun = -1, diskUsagePattern = UPDATE, spoolChunkSize = 2 ]
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheConfigurator
INFO: Parsed regions [diskRegion]
逐项对照：配置写的 MaxObjects=10 落到日志 maxObjs = 10；DiskUsagePatternName=UPDATE 落到 diskUsagePattern = UPDATE；未显式设置的 useLateral/useRemote/useDisk/maxSpoolPerRun/spoolChunkSize 沿用 5.1 的默认值。同一个程序里未定义的 demoRegion 则按默认 maxObjs = 100 构造（见《Ubuntu 22.04 安装 Apache Commons JCS 指南》4.6 回显），两条日志可直接对照验证「具名区域覆盖默认值」。
5.3 MemoryCacheName：LRU 内存缓存实现
做什么：指定内存层的数据结构与淘汰算法。实测取值 org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache。
实测回显：
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.engine.memory.AbstractDoubleLinkedListMemoryCache
INFO: initialized MemoryCache for diskRegion
解读：AbstractDoubleLinkedListMemoryCache 是 LRU 实现的基类（双链表维护访问顺序），日志证明该类被实例化并挂到 diskRegion。内存层满载后的换出行为与 DiskUsagePatternName（下节）共同决定数据是否落盘。
5.4 DiskUsagePatternName：UPDATE 与 SWAP 两种磁盘写入模式
做什么：决定内存层与磁盘层的写协同方式，是磁盘缓存最核心的语义开关。
| 模式 | 写入语义 | 数据位置 | 适用场景 |
|---|---|---|---|
UPDATE | 每次 put 都立即写入磁盘辅助缓存 | 内存 + 磁盘都有完整副本 | 重启恢复、崩溃保护（本文实测采用） |
SWAP | 仅当内存放不下（超过 MaxObjects）时才把换出条目写盘 | 磁盘只存「被挤出」的条目 | 纯溢出场景，磁盘仅作内存兜底 |
实测：diskRegion 配置 UPDATE 后，写 20 条、内存上限 10 条，demo.DiskCacheDemo put 运行日志可见「写入即落盘」与 dispose 时的内存排空：
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: In DISPOSE, [diskRegion] put 9 into auxiliary [diskRegion]
对照日志（put 全程回显见 5.6），Saving keys to: diskRegion, key count: 20 说明磁盘侧持有了全部 20 条；而默认 SWAP 模式（5.1 回显中 demoRegion/binRegion 的属性）下磁盘只承接内存淘汰出的条目。选择建议：需要「重启后数据完整读回」选 UPDATE；只关心热点不希望磁盘无限增长选 SWAP。
5.5 jcs.auxiliary.DC：IndexedDiskCache 辅助缓存
做什么：定义一个 IndexedDiskCache 辅助缓存实例（本文命名为 DC），包括工厂类、属性类与磁盘目录：
jcs.auxiliary.DC=org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCacheFactory
jcs.auxiliary.DC.attributes=org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCacheAttributes
jcs.auxiliary.DC.attributes.DiskPath=/opt/jcs-demo/disk-cache
实测启动回显：
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.auxiliary.AuxiliaryCacheConfigurator
INFO: No cache event logger defined for auxiliary [jcs.auxiliary.DC]
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.auxiliary.AuxiliaryCacheConfigurator
INFO: Using standard serializer [org.apache.commons.jcs3.utils.serialization.StandardSerializer@5025a98f] for auxiliary [jcs.auxiliary.DC]
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCache
INFO: Region [diskRegion] : Set maxKeySize to: "5,000"
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCache
INFO: Region [diskRegion] : Cache file root directory: /opt/jcs-demo/disk-cache
Oct 14, 2026 10:27:14 AM org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCache
INFO: Region [diskRegion] : Indexed Disk Cache is alive.
逐项解读：
jcs.auxiliary.DC=<Factory 全限定名>：DC是自定义名称，区域绑定串（如jcs.region.diskRegion=DC）按名字引用它。- 序列化器：默认
StandardSerializer（标准 Java 序列化），值对象需可序列化。 Set maxKeySize to: "5,000"：本文配置未设置 MaxKeySize，日志回显的是其默认值 5,000（键索引容量）。Cache file root directory：DiskPath的实测落地路径，缓存数据文件与键索引文件都生成在该目录下（5.6 有文件清单）。Indexed Disk Cache is alive.：辅助缓存初始化完成。
5.6 磁盘缓存生命周期日志与持久化验证
做什么：跑通「写入 → 关闭 → 新进程读回」全链路，验证 UPDATE 模式的持久化语义。写入端（java -Dfile.encoding=UTF-8 -cp target/classes:conf:$(cat cp.txt) demo.DiskCacheDemo put）：
cd /opt/jcs-demo && java -Dfile.encoding=UTF-8 -cp target/classes:conf:$(cat cp.txt) demo.DiskCacheDemo put 2>&1 | tail -35
输出节选（实测末尾 35 行；前段为 5.5 已展示的配置加载日志）：
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCache
INFO: Region [diskRegion] : Indexed Disk Cache is alive.
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.engine.control.CompositeCacheConfigurator
INFO: Parsed regions [diskRegion]
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Finished configuration in 68 ms.
put 完成: disk-key-1..20
get(disk-key-7) = disk-value-7
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: In DISPOSE, [diskRegion] fromRemote [false]
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.engine.control.event.ElementEventQueue
INFO: Element event queue destroyed: org.apache.commons.jcs3.engine.control.event.ElementEventQueue@27f723
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: In DISPOSE, [diskRegion] auxiliary [diskRegion]
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: In DISPOSE, [diskRegion] put 9 into auxiliary [diskRegion]
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.auxiliary.disk.AbstractDiskCache
INFO: In dispose, destroying event queue.
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.engine.PooledCacheEventQueue
INFO: Cache event queue destroyed: CacheEventQueue [listenerId=972252816, cacheName=diskRegion]
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCache
INFO: Region [diskRegion] : Saving keys to: diskRegion, key count: 20
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCache
INFO: Region [diskRegion] : Finished saving keys.
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCache
INFO: Region [diskRegion] : Shutdown complete.
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: In DISPOSE, [diskRegion] disposing of memory cache.
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.engine.memory.AbstractMemoryCache
INFO: Memory Cache dispose called.
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.auxiliary.disk.AbstractDiskCache
INFO: In dispose, destroying event queue.
Oct 14, 2026 10:27:28 AM org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCache
SEVERE: Region [diskRegion] : Not alive and dispose was called, filename: diskRegion
done
💡 说明：
put 完成与get(disk-key-7)是程序输出（值来自内存层），其后进入 dispose 序列——In DISPOSE, [diskRegion] put 9 into auxiliary [diskRegion]是内存层剩余条目在关闭前刷入辅助缓存，随后Saving keys to: diskRegion, key count: 20把键索引写盘（对应diskRegion.key文件），Shutdown complete.后管理器关闭。末尾的 SEVERE 是JCS.shutdown()对已 dispose 区域再次触发关闭时的状态记录（演示程序先cache.dispose()再JCS.shutdown()），进程仍以done正常退出，属实测关闭序列的一部分。
验证数据文件是否生成：
ls -la /opt/jcs-demo/disk-cache/
输出：
total 24
drwxr-xr-x 2 root root 4096 Oct 14 10:25 .
drwxr-xr-x 6 root root 4096 Oct 14 10:24 ..
-rw-r--r-- 1 root root 9742 Oct 14 10:27 diskRegion.data
-rw-r--r-- 1 root root 815 Oct 14 10:27 diskRegion.key
💡 说明：
diskRegion.data（9,742 字节）存序列化后的值对象，diskRegion.key（815 字节）存键索引——Saving keys to: diskRegion, key count: 20写盘的正是它。
新开进程读回（模拟应用重启；get 模式完整命令与 20 行逐条回显见《Apache Commons JCS 3.2.1 快速入门与集成示例》第六章，此处给关键验证段）：
cd /opt/jcs-demo && java -Dfile.encoding=UTF-8 -cp target/classes:conf:$(cat cp.txt) demo.DiskCacheDemo get 2>&1 | grep -E "Loaded keys|命中条数|get\(disk-key-1\)|get\(disk-key-20\)"
输出：
Oct 14, 2026 10:27:37 AM org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCache
INFO: Region [diskRegion] : Loaded keys from [diskRegion], key count: 20; up to 5,000 will be available.
get(disk-key-1) = disk-value-1
get(disk-key-20) = disk-value-20
命中条数: 20/20
验证点：新进程启动即 Loaded keys from [diskRegion], key count: 20（键索引被加载，容量上限 5,000 与 5.5 回显一致），20 条全部命中——UPDATE 模式 + dispose 落盘 + 启动加载键索引 构成完整的持久化闭环。
5.7 元素属性（ElementAttributes）与过期机制
做什么：元素属性控制单个条目的存活策略。本文实测配置未设置任何 elementattributes 键，因此全部走 5.1 回显的内置默认：IS_ETERNAL = true、MaxLifeSeconds = -1、IdleTime = -1（永不过期、无空闲回收）。
按官方语义，可在 jcs.region.<名称>.elementattributes（或 jcs.default.elementattributes）下设置：IS_ETERNAL=false 关闭「永生」、MaxLifeSeconds=<秒> 设定创建后最长存活时间、IdleTime=<秒> 设定空闲过期时间。这些键在本文实测中仅验证了默认值回显，未做过期行为实测，落地前请以官方文档与自身场景为准。
⚠️ 注意：
CreateTime = 1791973634659等 ms 级字段在每次启动时都不同，属正常回显；若配置文件写了非法属性名，JCS 会按「未定义该键」处理并回退默认类——日志出现No special ElementAttribute class defined for key即该路径的标志。
六、生产配置模板
依据实测语义给出两套可直接使用的模板，按场景二选一并改 DiskPath/MaxObjects。
模板一：纯内存缓存（无磁盘），适合热点数据加速、重启可重建：
jcs.default.cacheattributes=org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=100
jcs.default.cacheattributes.MemoryCacheName=org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache
逐项说明：与《Ubuntu 22.04 安装 Apache Commons JCS 指南》5.4 的最小配置一致；内存上限按条目大小 × 100 评估堆占用；未定义区域全部走该默认。实测回显对应 5.1 的 defaultCompositeCacheAttributes 与《CentOS 8 安装 Apache Commons JCS 指南》4.6 的 Parsed regions []。
模板二：内存 + 磁盘持久化（UPDATE 模式），适合重启恢复、写入即保护的场景：
jcs.region.appRegion=DC
jcs.region.appRegion.cacheattributes=org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.region.appRegion.cacheattributes.MaxObjects=10
jcs.region.appRegion.cacheattributes.MemoryCacheName=org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache
jcs.region.appRegion.cacheattributes.DiskUsagePatternName=UPDATE
jcs.auxiliary.DC=org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCacheFactory
jcs.auxiliary.DC.attributes=org.apache.commons.jcs3.auxiliary.disk.indexed.IndexedDiskCacheAttributes
jcs.auxiliary.DC.attributes.DiskPath=/opt/jcs-demo/disk-cache
逐项说明：即本文实测配置把 diskRegion 换成业务区域名 appRegion；MaxObjects 控制内存占用量级，UPDATE 保证每条写入即有磁盘副本；DiskPath 指向独立数据盘目录。实测语义佐证：5.6 的 Saving keys to: diskRegion, key count: 20、Loaded keys from [diskRegion], key count: 20 与 20/20 读回命中率。注意：内存条目能否在重启后读回依赖「进程退出前完成 dispose/shutdown」（见第七章 Q2）。
七、常见问题（FAQ）
Q1：启动抛 NullPointerException: inStream parameter is null？
classpath 上没有 cache.ccf（第三章实测完整栈）。把配置放进 src/main/resources 或将 conf 目录加入 -cp。判定标准：日志出现 Creating cache manager from config file: /cache.ccf 且不再抛异常。
Q2：配置了 UPDATE 磁盘缓存，重启后读不回数据？
检查进程退出路径。实测（5.6）：键索引的落盘发生在 dispose 阶段（Saving keys to: diskRegion, key count: 20），程序需在结束前调用 cache.dispose()（DiskCacheDemo 还追加了 JCS.shutdown()）。若进程被强杀，索引未保存则读回不完整。
Q3：日志显示 Parsed regions [] 但程序仍能缓存？
区域未在配置中定义时，JCS 按 jcs.default（或内置默认）在首次 JCS.getInstance 时即时创建区域（《CentOS 8 安装 Apache Commons JCS 指南》4.6 实测回显 Parsed regions [] 随后出现 Constructed cache with name [centosRegion] and cache attributes [ useLateral = true, useRemote = true, useDisk = true, maxObjs = 100, maxSpoolPerRun = -1, diskUsagePattern = SWAP, spoolChunkSize = 2 ]）。需要精确控制内存上限时必须显式定义区域。
Q4：maxObjs = 10 但写入了 20 条，会丢数据吗？
UPDATE 模式下不会：每条 put 都写入磁盘辅助缓存，内存层只保留最近访问的 10 条（LRU），dispose 时内存剩余条目再刷入磁盘（5.6 回显 put 9 into auxiliary），最终磁盘侧键计数为 20，新进程 20/20 全部读回。
Q5：中文输出乱码？
默认编码为 ANSI_X3.4-1968 的系统上，运行命令需加 -Dfile.encoding=UTF-8（本文全部 java 命令均带此参数），工程源码层配 project.build.sourceEncoding=UTF-8。
Q6：改了 cache.ccf 不生效？
配置在进程启动时一次性加载（Finished configuration in 67 ms. 之后不再读文件），修改后必须重启进程；同时确认改的是 classpath 上实际命中的那份 cache.ccf（多目录场景下按 classpath 顺序首个命中者生效）。
八、参考链接
- Apache Commons JCS 官方站点：https://commons.apache.org/proper/commons-jcs/
- 官方站点 Getting Started（配置文件用法）：https://commons.apache.org/proper/commons-jcs/GetStarted.html
- Maven 中央仓库坐标页：https://repo1.maven.org/maven2/org/apache/commons/commons-jcs3-core/
- 源码仓库（GitHub 镜像，可核对属性类源码）：https://github.com/apache/commons-jcs
- 本文配套：《Apache Commons JCS 3.2.1 快速入门与集成示例》《Apache Commons JCS 3.2.1 常用 API 与工具详解》