Unravel › Java concepts › Time and dates

Learn these first

At a glance

1. 1Store and exchange moments as Instant (or UTC, or epoch milliseconds)Convert to a zone only for display: instant.atZone(ZoneId.of("Europe/Paris")).
2. 2zdt.withZoneSameInstant(ZoneId.of("Asia/Tokyo")) shows the same moment in Tokyo; withZoneSameLocal keeps the clock reading but changes the moment
3. 3Use region ids (America/New_York), not fixed offsets (-05:00), because offsets do not know about daylight saving timeZoneId.systemDefault() depends on the server.
4. 4On DST change days "add one day" and "add 24 hours" differ: zdt.plusDays(1) keeps the wall clock, plus(Duration.ofHours(24)) keeps elapsed time

• Local times can be ambiguous (the hour repeated when clocks go back) or non-existent (skipped when clocks go forward)
• A recurring "every day at 09:00" job must be stored as a local time plus a zone, not as UTC, or it drifts by an hour twice a year
• Zone rules come from the IANA tz database bundled with the JDK (tzdb.dat), so an old JDK may not know a recent government change; update the JDK or the tzdata

import java.time.*;public class Meetings {  static ZonedDateTime inTokyo(Instant when) { return when.atZone(ZoneId.of("Asia/Tokyo")); }  static Instant parisNineAm(LocalDate day) { return day.atTime(9, 0).atZone(ZoneId.of("Europe/Paris")).toInstant(); }  static ZonedDateTime convert(ZonedDateTime t) { return t.withZoneSameInstant(ZoneId.of("America/New_York")); }  static long nowMillis() { return Instant.now().toEpochMilli(); }}

1. line 3 uses atZone, the core of Time zones, DST and Instant
2. line 4 uses atZone, the core of Time zones, DST and Instant
3. line 5 uses withZoneSameInstant, the core of Time zones, DST and Instant
4. line 6 uses now, the core of Time zones, DST and Instant

How Unravel recognises it

When you paste code, Unravel looks for these signs of time zones, dst and instant. Spotting them yourself is a good habit when you read unfamiliar code:

• Types: ZoneOffset ZoneRules
• Method calls: withZoneSameInstant() withZoneSameLocal() atZone() ZoneId.of() ZoneId.systemDefault() toInstant() Instant.now() ofEpochSecond() ofEpochMilli() toEpochMilli() ZonedDateTime.now() getOffset() atOffset()

Part of a learning path

• I/O, networking and time · previous: Formatting, parsing and date arithmetic · next: Legacy Date, Calendar and SimpleDateFormat

Related concepts