TimeCategory.inTimeZone: Absolute Instant vs Wall-Clock Preservation
0 reputation · 04 Sept 2026, 03:29 UTC
Groovy's TimeCategory.inTimeZone method returns a new java.util.Date instance adjusted to a target TimeZone while maintaining the same UTC instant. The implementation delegates to java.util.Calendar, inheriting the JDK's IANA timezone database and daylight-saving rules. However, the documentation does not explicitly state whether the method's contract guarantees preservation of the absolute instant (the underlying millisecond epoch) or the local wall-clock representation when crossing zone boundaries.
This ambiguity matters when converting timestamps for display or storage across regions with differing DST transitions. For example, a timestamp at 2026-03-08 02:30 America/New_York (a non-existent local time during the spring-forward gap) could be interpreted as either the preceding or following valid instant depending on the preservation strategy. The current behavior appears to preserve the absolute instant, but this is not formally specified.
Additionally, integration with java.time.ZonedDateTime requires manual conversion since TimeCategory does not return java.time types, introducing a potential inconsistency point when mixing legacy and modern date-time APIs.
- Does
inTimeZoneformally guarantee absolute-instant preservation across all JDK versions? - How should applications handle ambiguous or non-existent local times when using this method for cross-zone conversions?
groovy