Instants and time zones

Written Explanation

Instant: a point on the timeline

An Instant is one point on the global timeline. The Javadoc describes it as a count of seconds (plus nanoseconds) from the epoch, 1970-01-01T00:00:00Z. It has no zone, because it needs none: a moment is a moment. Its text form is always in UTC and ends with Z.

Instant i = Instant.parse("2026-05-04T07:00:00Z");
System.out.println(i + " " + i.getEpochSecond() + " " + i.plusSeconds(3600));

2026-05-04T07:00:00Z 1777878000 2026-05-04T08:00:00Z

Instant.now() gives the current moment. Because it is independent of zone, two machines anywhere in the world get the same value for the same moment (provided their clocks are right). That is what makes it the best type for "when did this happen".

ZoneId: which clock to read

A ZoneId identifies a set of rules for finding the offset from UTC. There are two kinds, according to the Javadoc:

• Region IDs such as Europe/London and Asia/Riyadh. Their rules can change the offset during the year.
• Fixed offsets (ZoneOffset) such as +03:00, which never change.

Prefer region IDs for anything that has a real-world location. Europe/London knows that its offset is +00:00 in winter and +01:00 in summer; the fixed offset +01:00 does not. The default source of region data is the IANA Time Zone Database. Use exact spellings: a made-up ID like Riyadh throws a DateTimeException (Unknown time-zone ID: Riyadh).

ZoneId riyadh = ZoneId.of("Asia/Riyadh");

ZonedDateTime: date, time and zone

A ZonedDateTime combines a local date-time, a zone, and the resulting offset. It identifies one exact moment, in a way readers can understand.

ZonedDateTime z = ZonedDateTime.of(2026, 5, 4, 10, 0, 0, 0, ZoneId.of("Asia/Riyadh"));
System.out.println(z);               // 2026-05-04T10:00+03:00[Asia/Riyadh]
System.out.println(z.toInstant());   // 2026-05-04T07:00:00Z

ZonedDateTime.of takes year, month, day, hour, minute, second, nanosecond and the zone. The arguments are many; you can also build one from a LocalDateTime with ldt.atZone(zone), or from an Instant with instant.atZone(zone).

Converting between the types:

Converting to another zone: same instant or same local?

Two methods look alike and mean different things.

ZonedDateTime london = z.withZoneSameInstant(ZoneId.of("Europe/London"));
// 2026-05-04T08:00+01:00[Europe/London]   same moment, London's clock
ZonedDateTime other = z.withZoneSameLocal(ZoneId.of("Europe/London"));
// 2026-05-04T10:00+01:00[Europe/London]   same clock reading, a different moment

• withZoneSameInstant keeps the moment and changes the clock reading. This is what you want when showing one meeting in another city.
• withZoneSameLocal keeps the clock reading and changes the moment. Use it only when you really mean "10:00 wherever it is".

Mixing them up gives a meeting that is an hour or more off.

Gaps and overlaps

Because zones change their offset, some local date-times are special. The ZonedDateTime Javadoc names three cases:

• Normal: one valid offset.
• Gap: clocks jump forward, so the local time does not exist. Java shifts the time forward by the length of the gap.
• Overlap: clocks go back, so the local time occurs twice. Java keeps the earlier offset by default (or the previous offset, if it is valid).

ZoneId ny = ZoneId.of("America/New_York");
ZonedDateTime.of(LocalDateTime.of(2026, 3, 8, 2, 30), ny);
// 2026-03-08T03:30-04:00[America/New_York]    gap: 02:30 does not exist
ZonedDateTime.of(LocalDateTime.of(2026, 11, 1, 1, 30), ny);
// 2026-11-01T01:30-04:00[America/New_York]    overlap: earlier offset
ZonedDateTime.of(LocalDateTime.of(2026, 11, 1, 1, 30), ny).withLaterOffsetAtOverlap();
// 2026-11-01T01:30-05:00[America/New_York]    the second occurrence

You do not need to memorize the method names. Remember the idea: a local time plus a zone is usually one moment, but at two times a year it can be none or two, and Java makes a documented choice.

Why store in UTC (outcome 4)

Now the rule can be explained.

• A UTC timestamp (an Instant) is one fixed reference. It has no daylight saving, so it never skips or repeats.
• Sorting and comparing UTC timestamps is correct: later moments are always larger. Local times are not: in the repeated hour, two different moments have the same clock reading.
• Data from users in many zones agrees, because everything is on one scale.
• The user's zone is a display concern. A person in Riyadh sees +03:00, a person in New York sees their own offset, both derived from the same stored value.
• Zone rules change (governments adjust them). If you store only the instant, a changed rule alters how it is displayed, never which moment it was.

So: store Instant (UTC), convert to ZonedDateTime at the edges. Persisting a zone ID alongside it is only needed when the zone itself is part of the data (for example, a flight's departure city).

Which type? A decision guide