Explore upgrade from Commons JEXL 2.0.1 to 3.6.4

[ejboy]

Scope

Explore, propose, and separately review an upgrade of Scriptella from Commons JEXL 2.0.1 to Commons JEXL 3.6.4. This is intentionally not targeted at Scriptella 1.4; do not include implementation work in the 1.4 release branch until the proposal is approved.

Findings from the initial investigation

Commit with the experiment 806870f

• JEXL 3 moves the Java API from org.apache.commons.jexl2 to org.apache.commons.jexl3 and requires a direct integration migration (JexlExpression, JexlConnection, and JexlContextMap).
• Commons JEXL does not provide a general JEXL 2-to-3 source translator or an official compatibility layer for arbitrary old scripts.
• A trial Scriptella-side adapter that rewrote identifiers such as var, let, and const, and intercepted dotted parameter lookup, was rejected as unsafe and undocumented. It was reverted. Do not reintroduce source rewriting without an explicit compatibility proposal.
• Existing Scriptella behavior includes flat parameter names with periods (for example url.prefix) and expressions using names such as var; JEXL 3 may parse or resolve these differently.
• The JEXL driver also needs characterization of assignments, conditionals, loops, query.next(), callbacks, namespaces (date:, text:, class:), nested parameters, and concurrency.
• JEXL 3.6.4 runs on Java 8+, so JDK 17 is a viable runtime target, but engine permissions/features and trusted ETL behavior must be reviewed explicitly.

Questions to answer

1. Which real Scriptella ETLs, samples, and documented examples are affected by the JEXL 2-to-3 syntax or resolution changes?
2. Should users explicitly migrate affected scripts, or should Scriptella offer a narrowly scoped and opt-in compatibility layer?
3. If an adapter is considered, what exact constructs does it support, how does it avoid semantic rewriting, and what diagnostics does it provide?
4. What explicit JEXL 3.6.4 engine options preserve Scriptella's trusted-ETL behavior?
5. How should Maven, Ant, the bundled JAR, binary distribution, examples, service metadata, Commons Logging, and license/notice files be kept consistent?

Required deliverables

• A compatibility matrix covering JEXL 2.0.1 versus JEXL 3.6.4 behavior.
• A migration proposal with a clear recommendation and rationale.
• An inventory of affected in-repository and representative external-style scripts.
• Focused characterization tests written before changing behavior.
• User-facing migration notes and actionable diagnostics if incompatibilities remain.
• A separate implementation plan and release target after review.

Recommendation for Scriptella 1.4

Use JEXL 2.1.1.

Before merging:

run current expression and driver tests;
add tests for dotted variables, query.next(), namespaces, assignment, null parameters, method invocation, and repeated execution;
verify Maven, Ant, all-in-one JAR, examples, and licensing;
update the dependency note without implying a language migration.

This should be a small, bounded chunk.

For future version

[projctl decision] we use minor upgrade of jexl for 1.4. Long term jexl will be retired. We will probably make var interpolation built-in feature

Related context

The reverted exploratory implementation and detailed findings are documented in docs/releases/1.4/release-1.4-plan.md under Chunk 4. The implementation must remain deferred until this issue is reviewed.