DO NOT MERGE: #34154: test(java25): ThreadLocal and ScopedValue are not the same idiom

[fabrizzio-dotCMS]

Why this exists

ThreadLocal and ScopedValue get described as alternatives, and dotCMS has a great deal of the
first — so a migration reads as mechanical: change the type, delete the cleanup. It is not
mechanical, and this is the argument, executed rather than asserted.

Study material for the Lunch & Learn (#34154). DO NOT MERGE.

java dotCMS/src/test/java/com/dotcms/jdk/ThreadLocalVsScopedValue.java

JDK 25, no flags, no Maven, no dotCMS classpath.

What it proves

1 — A pooled thread remembers the last request.

deep code during request A   sees: request-A
deep code during request B   sees: request-A

Task B set nothing. It read A's value, on a thread the container handed it clean. Nothing failed
and nothing logged — it just served the wrong request's context.

2 — setRequest(null) is not remove(). This is the cleanup idiom dotCMS actually uses, and it
writes null into the entry rather than releasing it:

first read (runs the initial supplier) : computed-118203673637583
after set(null)                        : null                       <- supplier did NOT re-run
after remove()                         : computed-118203674187416   <- entry was gone

3 — A scoped value cannot outlive its scope, on the same pooled thread, with no cleanup call to
forget: isBound() is false in the next task.

4 — The idiom inverts, and this is the real finding. There is no ScopedValue.set(). Deeper
code can only open a new binding, invisible to the frame above it:

outer frame            : request-A
inner frame rebinds it : request-A-rewritten
back in the outer frame: request-A          <- the rebinding was never visible here

With a ThreadLocal the writer decides, at any depth, and the value persists until someone
removes it. With a ScopedValue the caller decides, by wrapping the call, and the value is
immutable for everyone underneath. So each set() site becomes "find the frame that owns the
lifetime and turn the call inside out" — ten wraps, not ten replacements.

And a value that flows outward — inner code informing outer code — has no equivalent at all.
That is exactly the shape of ThreadContextUtil.includeDependencies: written inside
wrapReturnNoReindex(fireWorkflowPreCheckin) and read inside the sibling
wrapVoidNoReindex(fireWorkflowPostCheckin). It is why that ThreadLocal cannot be fully removed,
and why #37106 migrated the other two fields and left this one.

The state of the codebase

HttpServletRequestThreadLocal, counted over dotCMS/src/main/java on 2026-09-07:

103	reads of getRequest(), across 95 classes
10	sites that set a real request
3	sites that clear it — all with setRequest(null)
0	calls to remove(), anywhere
6	classes that set it and never clear it

Those six: RequestCostApiImpl, JsServlet, VelocityLiveMode, VelocityServlet,
PageResourceHelper, WorkflowResource.

The class has no remove() method to call — getRequest() and setRequest() are the whole
API. So the leak is not an oversight at the call sites; it is the only thing the type allows. Its
own javadoc already warns that async work will not see the value, which is the same scoping
confusion from the other direction.

Not in scope

• No production change: nothing here alters how the request is stored or read.
• No migration of HttpServletRequestThreadLocal — that is ten call sites of restructuring and
  belongs in its own issue, with its own tests.
• ThreadContextUtil is discussed, not changed. DO NOT MERGE: #34154: refactor(java25): scoped values for reindex + config guard, flexible constructor for ISODateParam #37106 covers the two fields that do migrate.

Refs #34154

[claude]

Claude finished @fabrizzio-dotCMS's task in 1m 25s —— View job

---

Code Review

I read the added file, verified it against the repo (compiler settings, the real HttpServletRequestThreadLocal), and checked the technical claims it makes.

New Issues

No correctness bugs. The four demonstrations are technically accurate and the JDK-25 API usage is valid:

• The ThreadLocal pooled-thread leak (§1), set(null) ≠ remove() (§2), scope teardown on run() return (§3), and inward-only rebinding (§4) all behave exactly as narrated.
• ScopedValue is a final feature in JDK 25 (JEP 506), so the "no flags, no --enable-preview" claim for the single-file launcher holds. Under Maven, dotcms.core.compiler.release=25 + enablePreview=true (parent/pom.xml:31,40) compiles it fine too.
• The verdict's factual anchor checks out: HttpServletRequestThreadLocal (dotCMS/src/main/java/com/dotcms/api/web/HttpServletRequestThreadLocal.java) exposes only getRequest() / setRequest() with no remove(), and its javadoc already warns that async work won't see the value — matching the "same scoping confusion from the other direction" argument.

Notes (non-blocking)

• 🟡 Medium: dotCMS/src/test/java/com/dotcms/jdk/ThreadLocalVsScopedValue.java:74,83,96,… — Uses System.out.println throughout, which the Critical Rules forbid (Logger only). Here it's justified and correct — the whole point is a zero-dependency file runnable via java <file>.java with no dotCMS classpath, where Logger isn't available. Flagging only so it's a conscious exception, not a pattern to copy. No change recommended.
• 🟡 Medium: The file lives under src/test/java, so even though it's DO NOT MERGE it will be compiled by dotcms-core's test-compile in CI (it has a main, no @Test, so it never runs as a test — compile only). That's fine on JDK 25, but it does pin this module's test sources to a JDK-25-only API; anyone overriding -Ddotcms.core.compiler.release to an older value for local test builds would hit a compile error on ScopedValue. Consistent with the PR's "DO NOT MERGE / study material" intent.

Verdict

Clean as study material — the code does what the description says, and the description is accurate. The only real question is process, not code: a main-based demo in src/test/java compiles in CI forever once merged, which is precisely why the DO NOT MERGE label is the right call. If it ever needs a permanent home, consider a docs/-adjacent location or a scratch/example module excluded from the standard build rather than the test source root.
· issue-34154-java25-scopedvalue-idiom