[CALCITE-7549] Add Programs.of overload that accepts RelOptListener

[shikhae6]

Jira Link

CALCITE-7549

Changes Proposed

When multiple HEP phases are composed via Programs.sequence, each
phase constructs its HepPlanner internally with no hook to attach a
RelOptListener. This prevents observing rule firings across sequenced
optimization phases — a requirement for query optimizer tracing and
observability tooling.

This PR adds a new overload to Programs:

public static Program of(HepProgram, boolean noDag,
    RelMetadataProvider, @Nullable RelOptListener listener)
                                            
Behavior:                               
- If listener is non-null, it is attached via HepPlanner.addListener()
before setRoot / findBestExp.                                                                                                                            
- If listener is null, the method delegates directly to the existing
Programs.of(HepProgram, boolean, RelMetadataProvider) — zero behavior                                                                                    
change, zero overhead for current callers.  
                                        
Use case:
Production query optimizers built on Calcite structure optimization as                                                                                   
multiple HEP phases via Programs.sequence. To build a unified trace of
which rules fire, in which phase, and in what order, a shared                                                                                            
RelOptListener must be attached to each HepPlanner. Without this
overload the only alternatives are bypassing Programs.of entirely
(losing its metadata/materialization/lattice setup) or using reflection.                                                                                 
                                        
Backward compatibility:                                                                                                                                  
- The existing three-argument Programs.of is unchanged.                                                                                                  
- No changes to the Program interface or HepPlanner.   
- Null listener path delegates to the existing method.                                                                                                   
                
Summary                                     
                                        
- Added Programs.of(HepProgram, boolean, RelMetadataProvider, RelOptListener)
overload in core/src/main/java/org/apache/calcite/tools/Programs.java.                                                                                   
- The new method mirrors the existing Programs.of behavior exactly, with
a single addition: attaching the provided listener to the HepPlanner                                                                                     
before execution.                           
- Expanded star import org.apache.calcite.plan.* to explicit imports to                                                                                  
satisfy checkstyle.                                                                                                                                      
- Added @Nullable annotation (from org.checkerframework.checker.nullness.qual)                                                                           
to the listener parameter.                                                                                                                               
- Added @SuppressWarnings("deprecation") consistent with the existing                                                                                    
Programs.of method (for registerMetadataProviders).
                                                                                                                                                         
Testing                                 
                                                                                                                                                         
Two new tests in HepPlannerTest:                                                                                                                         
                                                                                                                                                         
- testProgramsOfWithListener — verifies the listener receives                                                                                            
ruleAttempted events when rules fire through Programs.of.
- testProgramsOfWithNullListener — verifies null listener is safely
ignored and produces a valid result.    

Reference XML (HepPlannerTest.xml) updated with new test case entries.                                                                                   
                                        
./gradlew :core:build passes.                                                                                                                            
                                                                                                                                                         
---
                                                                                                                                                         
**Commit message:**
[CALCITE-7549] Programs.of should allow attaching a RelOptListener to the internal HepPlanner

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
76.0% Coverage on New Code
36.8% Duplication on New Code

See analysis details on SonarQube Cloud

[mihaibudiu]

We'll probably merge this after the 1.43 release

[mihaibudiu]

Can't this be done without calling deprecated functions?

[julianhyde]

I raised some concerns in the jira case.

[xiedeyantu]

@shikhae6 Do you think this PR is still needed?

[shikhae6]

@xiedeyantu I have proposed an alternate way in Jira , awaiting @julianhyde view on it