[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

[shikhae6]

@julianhyde
I have proposed an alternate solution in Jira , here are the details:
Please do let me know your views on the proposed alternate soultion.
I was treating the listener as part of the program definition, but it is really runtime/session state.

I’m thinking of changing the approach so the listener is not passed to Programs.of at all. Instead, callers would continue to attach the listener to the runtime planner for the current planning session:

planner.addListener(listener);

Program program = Programs.of(hepProgram, noDag, metadataProvider);

program.run(planner, rel, traits, materializations, lattices);

Then, inside the existing Programs.of(HepProgram, boolean, RelMetadataProvider) implementation, when it creates the internal HepPlanner, it would propagate the listener from the runtime planner passed to Program.run.

if (planner instanceof AbstractRelOptPlanner) {

RelOptListener listener = ((AbstractRelOptPlanner) planner).getListener();

if (listener != null)

{ hepPlanner.addListener(listener); }
}

This keeps Program stateless and reusable, while preserving the listener’s session lifetime. It also makes the behavior generally useful: any listener registered on the runtime planner will receive events from the internal HEP planner used by this program, rather than requiring a special Programs.of overload with listener.

If this direction sounds reasonable, I’ll remove the new overload and update the test to register the listener on the planner passed into Program.run, then verify that HEP rule events are forwarded through that session listener.