TimeCategory.inTimeZone: Absolute Instant vs Wall-Clock Preservation

Short answer

TimeCategory.inTimeZone preserves the absolute instant, not the wall-clock representation. The returned java.util.Date holds the same millisecond epoch as the input; only the zone used to interpret its fields changes. This behavior comes from java.util.Calendar delegation, not from a documented Groovy contract — so treat it as dependable today but not formally guaranteed.

Why it behaves this way

The implementation is roughly: copy the date into a Calendar, call setTimeZone(target), then return calendar.getTime(). Calendar.getTime() reconstructs a Date from the same epoch milliseconds, so the instant is invariant. A Date carries no zone at all — the zone only matters when the calendar interprets fields or when you format the result.

Confirmed fact: the epoch is unchanged. Likely-but-unspecified: that this stays true across future Groovy versions, since no GDK documentation states the contract explicitly and a reimplementation could change it.

Verify it yourself

use(groovy.time.TimeCategory) {
    def d = new Date(0)
    def converted = d.inTimeZone(TimeZone.getTimeZone('America/New_York'))
    assert converted.time == 0L   // same absolute instant
}

For a DST-gap check, interpret a local time in the target zone before and after conversion and compare formatted output — Calendar's default lenient mode shifts non-existent local times (e.g. 2026-03-08 02:30 in America/New_York) forward by the DST offset, and resolves fall-back overlaps to the first occurrence. You cannot configure this through inTimeZone.

Handling gaps, overlaps, and java.time interop

• Instant preservation (what inTimeZone does): with java.time, use instant.atZone(targetZone) or zonedDateTime.withZoneSameInstant(targetZone).
• Wall-clock preservation: use localDateTime.atZone(targetZone), which lets you detect gaps/overlaps explicitly via ZonedDateTime resolution rules.
• Interop risk: the returned Date has no zone metadata. If you later convert with date.toInstant().atZone(...), you must re-supply the intended zone — a common silent-mismatch point when mixing legacy and modern APIs. Record the target zone alongside any serialized value.

Recommendation

For new code, prefer java.time conversions where the preservation strategy is explicit and DST disambiguation is controllable. Keep inTimeZone for legacy paths, and pin the behavior with the epoch-assertion test above so a future Groovy upgrade can't silently change it. Assumes Groovy 2.x–4.x and standard JDK Calendar semantics.