maintenance portlet | Implement Cache Management Apis #35190

[hassandotcms]

Summary

Add 3 new REST endpoints to CacheResource and fix missing side effects on the existing flush-all endpoint, replacing legacy JSP/Struts cache management with modern REST APIs for the Maintenance portlet
Cache tab.

New endpoints:

• GET /api/v1/caches — Alphabetically sorted list of cache region names (replaces JSP scriptlet calling CacheLocator.getCacheIndexes())
• GET /api/v1/caches/stats — JVM memory stats + per-provider per-region cache statistics (replaces cachestats_guava.jsp)
• DELETE /api/v1/caches/region/{regionName} — Flush a specific cache region across all providers, or pass "all" to flush everything. Includes permission reference reset and conditional PushPublishing
  filter reload

Bug fix:

• DELETE /api/v1/caches/provider/{p}/flush — Added resetAllPermissionReferences() + PushPublishing filter reload that were missing vs the legacy Struts action (ViewCMSMaintenanceAction._flush())

Implementation details:

• CacheMaintenanceHelper (@ApplicationScoped) extracts shared flush side-effect logic used by both the new and existing flush endpoints
• Typed @Value.Immutable views (JvmMemoryView, CacheProviderStatsView, CacheStatsView) with full Swagger/OpenAPI annotations
• Region name validation against CacheIndex — unknown names return 400 instead of silently flushing all caches (legacy NPE-catching behavior)
• /region/ path prefix avoids JAX-RS conflict with existing DELETE /api/v1/caches/menucache

Test plan

• Integration tests pass: ./mvnw verify -pl :dotcms-integration -Dcoreit.test.skip=false -Dit.test=CacheResourceIntegrationTest
• GET /api/v1/caches returns sorted region list matching the Cache tab dropdown
• GET /api/v1/caches/stats returns memory + provider stats matching cachestats_guava.jsp output
• DELETE /api/v1/caches/region/Permission flushes Permission cache and returns 200
• DELETE /api/v1/caches/region/all flushes all caches and returns 200
• DELETE /api/v1/caches/region/InvalidName returns 400
• DELETE /api/v1/caches/region/System triggers PushPublishing filter reload
• Existing DELETE /api/v1/caches/provider/{p}/flush still returns 200 with "flushed all"
• Existing Postman collection CacheResource.postman_collection.json passes unchanged

Closes #35196, Closes #35197, Closes #35198

[claude]

Claude finished @hassandotcms's task in 1m 56s —— View job

---

PR Review: Cache Management APIs #35190

• Gather context
• Read changed files
• Analyze and post review

---

Fixed since last review: @ApplicationScoped removed, reloadPublishingFilters() wrapped in try-catch, regionName path extended to .*, flushAll() Swagger documents ignored param, serverName added to stats response.

---

Issues

1. getProvider() wrong comparison — pre-existing bug, still not fixed

CacheResource:113 compares cache.getName().equals(group) but the intent is to find a provider by name, so it should be cache.getName().equals(provider). As-is, this method never finds a match (unless the provider and group happen to share a name) and always throws DotStateException. This breaks showProviders, getKeys, showObject, showObjects, flushGroup, and flushObject. Was flagged in the previous review — still present.

Fix this →

---

2. Race condition on method field — still not fixed

CacheResource:62 — private Method method = null; with a lazy-init block at lines 83–98 that is not synchronized and the field is not volatile. Jersey runs CacheResource as a singleton by default. Two concurrent requests can both see null and race to set method. The write/read has no happens-before guarantee.

Fix: initialize in the constructor, or add volatile, or synchronize the block.

Fix this →

---

3. resetAllPermissionReferences() fires on every region flush, including unrelated regions

CacheMaintenanceHelper:89–99 — performPostFlushActions() always calls permissionAPI.resetAllPermissionReferences() regardless of which region was flushed. Flushing "Contentlet", "FieldVariable", or any other region triggers a potentially expensive permission reset. The legacy Struts action did the same, but that ran as a single user-triggered action, not an API endpoint that might be called frequently. If this is intentional, add a comment explaining why (e.g. "any cache flush can affect permission caching indirectly").

---

4. InetAddress.getLocalHost() can block in buildCacheStatsView()

CacheResource:568–572 — InetAddress.getLocalHost().getHostName() performs a DNS reverse lookup. In containerized environments with misconfigured DNS or search domains this can block for several seconds on the hot path of the stats endpoint. The try-catch prevents it from failing, but the timeout cost is paid silently. Consider using InetAddress.getLocalHost().getHostAddress() (IP, no DNS) or caching the result at startup.

---

5. Integration tests still bypass HTTP layer

CacheResourceIntegrationTest calls Java methods directly on CacheResource. JAX-RS routing, content negotiation, serialization, and HTTP status code mapping are all untested. The test test_flushRegion_unknown_returns_400 asserts a Java BadRequestException is thrown — but what actually matters is that the HTTP response is 400. The HttpStatusCodeExceptionMapper that converts it could be misconfigured without these tests catching it. Not a blocker, but the PR test-plan claim "returns 400" is technically unverified.

---

Minor

• buildCacheStatsView() (line 529) has no error handling if getCacheStatsList() throws — the stats endpoint would 500.
• listRegions() and flushRegion() return typed views; all older endpoints return raw Response. Inconsistent in the same class.

[claude]

Claude finished @hassandotcms's task in 1m 35s —— View job

---

PR Review: Cache Management APIs #35190

• Gather context
• Read changed files
• Analyze and post review

---

Issues Found

1. @ApplicationScoped annotation is dead code

CacheMaintenanceHelper is annotated @ApplicationScoped but CacheResource constructs it with new CacheMaintenanceHelper() (line 69). CDI never manages this instance — the annotation does nothing and misleads readers. Either inject it via CDI or drop the annotation.

Fix this →

---

2. Race condition on method field in getProviders()

CacheResource.method (line 63) is a non-volatile mutable field. The lazy init at lines 84-98 is not synchronized. If JAX-RS creates a singleton resource (Jersey's default), two concurrent requests could both see method == null and race to set it. Even if the result is idempotent, the write/read of a non-volatile reference across threads has no happens-before guarantee.

Fix: initialize method eagerly in the constructor, or make it volatile, or synchronize the block.

Fix this →

---

3. getProvider() matches on wrong parameter — always throws

CacheResource.getProvider() at lines 109–121 calls cache.getName().equals(group) but it should be checking against provider. The correct comparison to find the right provider is cache.getName().equals(provider). As written, this method will never find a match (unless the provider name happens to equal the group name) and will always throw DotStateException. This is pre-existing code but is still present and broken.

Fix this →

---

4. reloadPublishingFilters() will throw ClassCastException silently

CacheMaintenanceHelper.reloadPublishingFilters() at line 94:

DotInitializer.class.cast(APILocator.getPublisherAPI()).init();

This casts the publisher API to DotInitializer. If the implementation doesn't implement that interface, it throws a ClassCastException that propagates uncaught through performPostFlushActions() and flushAllCaches(), aborting the flush response entirely. This also happens on every flush of the "System" region. A try-catch is missing here.

Fix this →

---

5. flushAllCaches() is called for DELETE /provider/{p}/flush — provider param ignored

The modified flushAll() endpoint calls cacheMaintenanceHelper.flushAllCaches() regardless of what provider path param is passed. The endpoint path implies it flushes only that provider, but it actually flushes everything. The PR description acknowledges this matches legacy behavior, but callers passing a specific provider name now also get an undocumented permission-reference reset + filter reload. This should be documented in the Swagger description at minimum.

---

6. resetAllPermissionReferences() called on every single region flush

performPostFlushActions() always resets permission references regardless of which region is being flushed (line 82–85). Flushing "Contentlet" or "FieldVariable" cache triggers a resetAllPermissionReferences(). This is consistent with the legacy Struts action, but it's a potentially expensive operation that should only be needed when permission-relevant caches are flushed. At minimum, document the reason this always fires.

---

7. regionName path param doesn't support slashes

@Path("/region/{regionName}") at line 485 uses a simple path variable with no regex. If any cache region name ever contains a /, the request will 404. The existing endpoints in this class use {group: .*} to handle this. Low risk now, but inconsistent with the established pattern.

Fix this →

---

8. Integration tests bypass HTTP layer entirely

The tests call Java methods directly on CacheResource instead of going through the HTTP stack. This means JAX-RS routing, content negotiation, serialization, and HTTP status code mapping are untested. The test plan claims "DELETE /api/v1/caches/region/InvalidName returns 400" but the test only asserts a Java BadRequestException is thrown — the actual HTTP 400 mapping is untested. Consider adding at least one end-to-end Postman or REST-assured test for the new endpoints.

---

Minor

• listRegions() returns ResponseEntityListStringView directly while flushAll() and older endpoints return Response. Inconsistent return types in the same class.
• CacheLocator.getCacheIndexes() returns Object[]. Storing and streaming as Object[] with .toString() is fragile and loses type safety all the way through listRegions() and isValidRegion().

[claude]

Rollback Safety Analysis

• Read rollback-unsafe categories reference
• Get full PR diff
• Analyze diff against all unsafe categories
• Apply label

---

Verdict: Safe to Rollback

All 8 changed files were checked against every category in the rollback-unsafe reference:

Category	Check	Result
C-1 Structural Data Model Change	No runonce tasks, no schema migrations	SAFE
C-2 Elasticsearch Mapping Change	No ES mapping code touched	SAFE
C-3 Content JSON Model Version Bump	No CURRENT_MODEL_VERSION change	SAFE
C-4 DROP TABLE or DROP COLUMN	No DDL drop statements	SAFE
H-1 One-Way Data Migration	No data transformation tasks	SAFE
H-2 RENAME TABLE or RENAME COLUMN	No renames	SAFE
H-3 PK or Unique Constraint Restructuring	No PK changes	SAFE
H-4 New ContentType Field Type	No new field type registered	SAFE
H-5 Binary Storage Provider Change	No storage provider changes	SAFE
H-6 DROP PROCEDURE or FUNCTION	None	SAFE
H-7 NOT NULL Column Without Default	No schema changes at all	SAFE
M-1 Non-Broadening Column Type Change	No column type changes	SAFE
M-2 Push Publishing Bundle Format Change	No bundler XML changes	SAFE
M-3 REST API Contract Change	Only new endpoints added; existing flush-provider endpoint response shape is unchanged	SAFE
M-4 OSGi Interface Breakage	No OSGi-exported interface changes	SAFE

Why this is safe: All changes are purely additive — new Java classes, new REST endpoints, new Swagger docs, and a new integration test. No database schema is altered, no data is transformed, and the one modified endpoint keeps its existing HTTP contract. Rolling back to N-1 simply removes the three new endpoints; nothing N wrote to storage would be unreadable by N-1.

Label applied: AI: Safe To Rollback

View job run