PHOENIX-7879 Tests for EXPLAIN text and ExplainPlanAttributes serialization compatibility

[apurtell]

Backward compatibility test harness for EXPLAIN output, for validating changes to EXPLAIN features and output formats in the future.

Adds new classes in org.apache.phoenix.query.explain, such as ExplainOracle, ExplainTextNormalizer, ExplainJsonNormalizer, and a new connectionless ExplainCompatibilityTest cases which freeze today's EXPLAIN format in text and JSON formats.

Stabilizes Jackson serialization of ExplainPlanAttributes via @JsonPropertyOrder plus RegionLocationsListSerializer and ServerMergeColumnsSerializer.

Normalize Phoenix temp aliases in dynamic-filter and sub-select line and JSON string fields for comparison.

Co-authored-by: Claude Opus 4.8[1m] noreply@anthropic.com

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[apurtell]

Test results

Scope

git show --stat HEAD shows the patch touches exactly these files:

File	Kind	Notes
phoenix-core-client/.../compile/ExplainPlanAttributes.java	prod	@JsonPropertyOrder + 2× @JsonSerialize annotations
phoenix-core-client/.../compile/RegionLocationsListSerializer.java	prod	new Jackson serializer
phoenix-core-client/.../compile/ServerMergeColumnsSerializer.java	prod	new Jackson serializer
phoenix-core-client/.../schema/MetaDataClient.java	prod	pure Javadoc reflow, no code change
phoenix-core/.../query/explain/ExplainCompatibilityTest.java	test (added)	the corpus, 44 cases
phoenix-core/.../query/explain/ExplainOracle.java	test (added)	tolerant comparator
phoenix-core/.../query/explain/ExplainTextNormalizer.java	test (added)	text normalization
phoenix-core/.../query/explain/ExplainJsonNormalizer.java	test (added)	JSON normalization
phoenix-core/.../query/explain/TempAliasRenumberer.java	test (added)	temp-alias renumbering

The only runtime behavior added is Jackson JSON serialization of ExplainPlanAttributes; text rendering is unchanged. Existing tests that use ExplainPlanAttributes via getters are not behaviorally affected. The directly-on-surface tests — added or pre-existing on the EXPLAIN rendering / attributes surface — are:

• Surefire: ExplainCompatibilityTest (added), ExplainPlanTextTest (pre-existing sibling).
• Failsafe: ExplainPlanWithStatsDisabledIT, ExplainPlanWithStatsEnabledIT (pre-existing ITs that walk EXPLAIN end-to-end through getPlanStepsAsAttributes()).

Surefire (unit tests)

mvn -am -pl phoenix-core test -Dtest='ExplainCompatibilityTest,ExplainPlanTextTest'

Test class	Run	Failures	Errors	Skipped	Time
org.apache.phoenix.query.explain.ExplainCompatibilityTest	44	0	0	0	2.242 s
org.apache.phoenix.query.ExplainPlanTextTest	2	0	0	0	1.962 s
Total	46	0	0	0	—

Failsafe (integration tests)

mvn -am -pl phoenix-core verify -Dit.test='ExplainPlanWithStatsDisabledIT,ExplainPlanWithStatsEnabledIT' \
  -Dtest=nothing -DfailIfNoTests=false -Dsurefire.failIfNoSpecifiedTests=false \
  -DskipNeedsOwnMiniClusterTests=true

Test class	Category	Run	Failures	Errors	Skipped	Time
org.apache.phoenix.end2end.ExplainPlanWithStatsEnabledIT	ParallelStatsEnabledTest	28	0	0	0	59.77 s
org.apache.phoenix.end2end.ExplainPlanWithStatsDisabledIT	ParallelStatsDisabledTest	17	0	0	0	44.24 s
Total	—	45	0	0	0	—

NeedTheirOwnClusterTests execution: skipped (no IT in scope was in that category).

Reactor summary: BUILD SUCCESS, total wall-clock 3:36 (mostly mini-cluster startup for the two Failsafe runs).

Roll-up

Phase	Classes	Tests	Pass	Fail	Error	Skip
Surefire	2	46	46	0	0	0
Failsafe	2	45	45	0	0	0
All	4	91	91	0	0	0

All tests added or affected by HEAD pass.