feat: Parameterize TimestampWithTimeZoneType by precision

[Joe-Abraham]

Description

Parameterizes TimestampWithTimeZoneType by precision, following the same interning/factory pattern already established for TimestampType. TimestampWithTimeZoneType moves from a single hardcoded singleton to a static pool of interned instances for precisions 0..MAX_PRECISION (12), built once in a static initializer.

Adds createTimestampWithTimeZoneType(int precision) and getPrecision(). The existing TIMESTAMP_WITH_TIME_ZONE constant still refers to the same interned p=3 instance, and its TypeSignature is unchanged ("timestamp with time zone", no parameter), so existing serialized metadata continues to parse identically. getObjectValue() throws UnsupportedOperationException for any non-default precision, since SqlTimestampWithTimeZone has no sub-millisecond representation yet. equalTo/hash/compareTo are unchanged in behavior (still millis-only); precision-aware dispatch for those is left for a follow-up. equals/hashCode switch from class-based to reference-identity comparison, which is correct now that instances are interned per precision, with no observable change for the default precision (it was already effectively a singleton).

Motivation and Context

This is groundwork for full TIMESTAMP(p) WITH TIME ZONE type-system support, tracked in #27934. Introducing the interned per-precision instances now — without yet wiring them into the parser/type registry — lets later phases (parsing, function dispatch, connector support) build on a stable TimestampWithTimeZoneType API instead of bundling the type-model change with those larger changes.

Impact

No user-facing or behavioral change for the default precision (TIMESTAMP WITH TIME ZONE, p=3): the public constant, its type signature, and its equals/hashCode/getObjectValue behavior are unchanged from a caller's perspective. createTimestampWithTimeZoneType(p) for p != 3 is new API surface, but the resulting instances aren't yet reachable through SQL parsing or the type registry, so they must not be surfaced outside presto-common (e.g. returned from a connector's column type) until #27934 lands — instances with p != 3 will fail to round-trip through TypeSignature serialization since the parser doesn't recognize the "timestamp with time zone(p)" string form yet.

Test Plan

Added TestTimestampWithTimeZoneType covering:

• Interning: repeated calls to createTimestampWithTimeZoneType(p) return the same instance; different precisions return distinct instances.
• Backward compatibility: the TIMESTAMP_WITH_TIME_ZONE constant is identical to createTimestampWithTimeZoneType(3), and its type signature has no parameter.
• Invalid precision boundaries (negative, > MAX_PRECISION).
• getObjectValue() returns a SqlTimestampWithTimeZone for the default precision, and throws UnsupportedOperationException for every non-default precision.

Contributor checklist

• Please make sure your submission complies with our contributing guide, in particular code style and commit standards.
• PR description addresses the issue accurately and concisely. If the change is non-trivial, a GitHub Issue is referenced.
• Documented new properties (with its default value), SQL syntax, functions, or other functionality.
• If release notes are required, they follow the release notes guidelines.
• Adequate tests were added if applicable.
• CI passed.
• If adding new dependencies, verified they have an OpenSSF Scorecard score of 5.0 or higher (or obtained explicit TSC approval for lower scores).

Release Notes

== NO RELEASE NOTE ==

Summary by Sourcery

Parameterize the TIMESTAMP WITH TIME ZONE type by precision while preserving backward compatibility for the default precision and reference semantics.

New Features:

• Introduce precision-specific instances of TimestampWithTimeZoneType with a factory method to obtain types for all supported precisions.

Enhancements:

• Ensure TIMESTAMP WITH TIME ZONE default constant retains legacy unparameterized type signature for serialized metadata compatibility.
• Adjust equality and hashCode semantics of TimestampWithTimeZoneType to rely on instance identity rather than a single global constant.
• Restrict getObjectValue to the default precision to avoid silent truncation until sub-millisecond encodings are supported.

Tests:

• Add unit tests covering interning and pre-allocation of precision-specific instances, backward-compatible constant and type signature behavior, precision validation, reference equality, and getObjectValue behavior for non-default precision.

[sourcery-ai]

Reviewer's Guide

Parameterizes TimestampWithTimeZoneType by precision while preserving backward compatibility for the default precision and adds tests for interning, type signatures, precision validation, equality, and getObjectValue behavior.

File-Level Changes

Change	Details	Files
Make TimestampWithTimeZoneType precision-parameterized with preallocated, interned instances and backward-compatible default behavior.	Introduce MAX_PRECISION, DEFAULT_PRECISION, and an INSTANCES array of TimestampWithTimeZoneType indexed by precision. Add a precision field and constructor that builds a precision-aware TypeSignature, preserving the unparameterized signature for the default precision. Expose createTimestampWithTimeZoneType(int) with range validation and reuse of preallocated instances. Change TIMESTAMP_WITH_TIME_ZONE to reference the default-precision instance and add getPrecision(). Guard getObjectValue to throw UnsupportedOperationException for non-default precision to avoid silent truncation. Update equals to use reference equality and hashCode to System.identityHashCode for instance distinction.	presto-common/src/main/java/com/facebook/presto/common/type/TimestampWithTimeZoneType.java
Add unit tests covering precision behavior, interning, type signatures, equality, invalid inputs, and getObjectValue limitations.	Test that createTimestampWithTimeZoneType returns interned instances per precision and that precision is correctly stored. Verify TIMESTAMP_WITH_TIME_ZONE is the default-precision (3) instance with an unparameterized type signature. Validate reference equality and equals semantics across same-precision instances and the constant. Assert IllegalArgumentException for negative and too-large precisions. Confirm distinct instances for different precisions and UnsupportedOperationException from getObjectValue for non-default precisions using a default-precision block.	presto-common/src/test/java/com/facebook/presto/common/type/TestTimestampWithTimeZoneType.java

Possibly linked issues

• #Parameterised Timestamp for Presto: This PR delivers the Phase 1 precision registry for TimestampWithTimeZoneType, a core component of the issue’s plan.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.