[CALCITE-7553] Separate TIMESTAMP_TZ comparison semantics

[OldTruckDriver]

Fixes CALCITE-7553.

This PR separates TIMESTAMP_TZ's Java natural ordering from SQL value comparison semantics.

TimestampWithTimeZoneString.compareTo now compares by instant first, then by the canonical string value as a tie-breaker. This makes compareTo consistent with equals/hashCode, so Java sorted collections do not collapse distinct TIMESTAMP_TZ values that represent the same instant.

SQL comparison paths now use an explicit Rex SQL value comparison helper. For TIMESTAMP_TZ, the helper compares instants; other values keep their existing natural ordering. This preserves SQL semantics for literal folding and RexInterpreter evaluation.

RexBuilder and RexSimplify now avoid constructing Sarg ranges for TIMESTAMP_TZ values in the affected paths, because Sarg still relies on natural Comparable ordering. This keeps IN/BETWEEN and simplification paths from using the wrong ordering. Full TIMESTAMP_TZ SQL-value comparison support inside Sarg/range handling is left for a follow-up PR.

The TIMESTAMP_TZ epoch-millis conversion in RexLiteral now delegates to TimestampWithTimeZoneString.getMillisSinceEpoch(), using the same instant calculation as the comparison helper.

Tests:

• ./gradlew :core:test -Djunit.jupiter.execution.parallel.enabled=false --tests org.apache.calcite.rex.RexProgramTest --tests org.apache.calcite.rex.RexBuilderTest
• ./gradlew :core:check

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
84.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[mihaibudiu]

I think this deserves a little design discussion in Jira prior to an implementation.
I would expect to see an interface e.g., ComparableSqlValue implemented by all SqlLiterals.
Alternatively, there could be a Comparator interface implementation for SqlLiterals.

[OldTruckDriver]

Thanks. My intent with this PR was to separate Java natural ordering from SQL value comparison semantics, but the current helper is only a local implementation of that idea.

I will move the design proposal to Jira and wait for agreement there before updating this PR. In particular, I will describe the two options you mentioned: a ComparableSqlValue-style interface, or a central Comparator for SQL literal values.

[OldTruckDriver]

I updated the local version to introduce a ComparableSqlValue<T> interface and a shared SqlValueComparator. TimestampWithTimeZoneString implements the interface, so its Java natural ordering can remain consistent with equals, while SQL-value comparison uses the explicit comparator path.

[mihaibudiu]

This seems to be defined only for constant values (a concept which includes literals, but also perhaps constructors applied to constant arguments). The term "value" you used is very overloaded - it can be applied to runtime values as well.

[mihaibudiu]

Is the two-argument version of this function really necessary?
Is there a case where the one-argument and the two-argument would return different results for the same first argument?