WW-5540 Add caching to AbstractLocalizedTextProvider

[lukaszlenart]

Fixes WW-5540

What

Caches the class- and package-hierarchy traversal performed by
StrutsLocalizedTextProvider.findText(Class, …), so repeated lookups for the same
(classloader, class name, key, locale) collapse to a single ConcurrentHashMap
lookup instead of re-walking the class → interface → superclass → *.package
hierarchy on every call. This path backs every UI tag label and validation message
rendered per request; missing keys were especially costly (full hierarchy walk +
swallowed MissingResourceException per level, repeated every request).

How

• Raw / format split — resolution of the raw message pattern is separated from
  rendering. Only the raw pattern (or a NOT_FOUND identity sentinel) is cached;
  OGNL translateVariables and MessageFormat argument substitution still run per
  call, so dynamic ${…} messages and per-call args remain correct.
• Two caches in AbstractLocalizedTextProvider (classHierarchyCache,
  packageHierarchyCache), keyed on the classloader hash + class name (String) —
  never a Class object, so no classloader pinning.
• Invalidation wired into reloadBundles, clearBundle, and
  clearMissingBundlesCache; the reload check is hoisted to the top of findText so
  devMode/struts.i18n.reload=true clears the caches before they are read.
• getMessage / findMessage are retained as @Deprecated delegators for
  descendant classes.

Behavior

Behavior-preserving: lookup order, dynamic-message evaluation, argument formatting,
and devMode/reload semantics are unchanged. The one documented, accepted divergence is
a pathological case where the same key is redefined at multiple levels of a single class
hierarchy and the shallowest match formats to the literal string "null". Caches are
unbounded, consistent with the existing bundlesMap / missingBundles. See the design
spec under docs/superpowers/specs/ for details.

Testing

mvn test -DskipAssembly -pl core -Dtest=StrutsLocalizedTextProviderTest → 33/33 green
(11 new tests covering raw-only caching, per-call formatting/OGNL, miss caching, the
null-format fall-through, and cache invalidation at all three clear sites). Broader
localized-text slice: 54/54 green.

Follow-up

A separate, deferred cleanup (replacing the null-overloaded control flow with an
explicit result type) is filed as WW-5655.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR improves Struts i18n lookup performance by caching the expensive class/interface/superclass and *.package hierarchy traversals performed by StrutsLocalizedTextProvider.findText, while keeping OGNL translation and MessageFormat rendering per call to preserve dynamic behavior.

Changes:

• Split raw pattern lookup (cacheable) from formatting/translation (per call) in AbstractLocalizedTextProvider.
• Add two unbounded ConcurrentHashMap caches for class-hierarchy and package-hierarchy raw lookups, with invalidation wired into reload/clear paths.
• Add targeted regression tests and fixtures to verify cache hits, miss caching, per-call formatting/OGNL behavior, null-format fall-through, and invalidation.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/superpowers/plans/2026-07-23-WW-5540-localized-text-provider-caching.md	Implementation plan/spec documenting the caching approach and constraints.
core/src/main/java/org/apache/struts2/text/AbstractLocalizedTextProvider.java	Introduces raw-pattern resolution + formatting split, cache keys/sentinels, cache resolvers, and invalidation hooks.
core/src/main/java/org/apache/struts2/text/StrutsLocalizedTextProvider.java	Wires cached raw resolution into findText for class/model/package tiers and hoists reload.
core/src/test/java/org/apache/struts2/text/CacheFixture.java	Test fixture class used for cache behavior verification.
core/src/test/resources/org/apache/struts2/text/CacheFixture.properties	Bundle backing the cache tests (static, param, OGNL, null-format cases).
core/src/test/java/org/apache/struts2/text/StrutsLocalizedTextProviderTest.java	Adds new tests and exposes cache sizes via a test provider subclass.

Comments suppressed due to low confidence (1)

core/src/main/java/org/apache/struts2/text/AbstractLocalizedTextProvider.java:705

• resolvePackageHierarchyRaw’s cache key ignores indexedTextName even though the underlying walk checks both textKey and indexedTextName. If callers vary the indexed form for the same base key, this cache can return the wrong raw pattern. Include the indexed key in the cache key (or derive it internally and drop the parameter).

    protected String resolvePackageHierarchyRaw(Class<?> startClazz, String textKey, String indexedTextName, Locale locale) {
        TextCacheKey cacheKey = new TextCacheKey(currentLoaderHashCode(), startClazz.getName(), textKey, locale);
        String cached = packageHierarchyCache.get(cacheKey);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
89.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

core/src/main/java/org/apache/struts2/text/StrutsLocalizedTextProvider.java:73

• When valueStack is null, this falls back to reloadBundles(). If ActionContext.getContext() is also null, reloadBundles() will invoke reloadBundles(null), which cannot set the per-request RELOADED flag and will therefore clear bundlesMap and the new caches on every call in reload mode. Consider only calling the ActionContext-based overload when an ActionContext is present; otherwise skip the reload call (matching the previous behavior for stack-less calls and avoiding pathological repeated clears).

        // Trigger bundle reload (and cache invalidation) once, before any cached hierarchy lookup,
        // so that in reload/devMode the hierarchy caches are cleared before they are read. With no
        // value stack, fall back to the ActionContext-based overload so the RELOADED flag is still
        // tracked and the caches can warm on that path too.
        if (valueStack != null) {