dates and time

the picture

there's one clock for the whole universe: UTC, counted as seconds since 1970-01-01T00:00Z. every city also has a wall clock, and the wall clock is that universal time shifted by an offset that politicians choose, and change twice a year.

a LocalDateTime is a photo of a wall clock with the city cropped out. "03:30" tells you nothing about when, until someone says where. that's the root of most date bugs: code that treats a wall-clock reading as if it were a moment.

import java.time.*;
 
void main() {
    Instant moment = Instant.parse("2026-03-08T07:30:00Z");
    ZonedDateTime ny = moment.atZone(ZoneId.of("America/New_York"));
    IO.println(moment);
    IO.println(ny);
    IO.println(ny.toLocalDateTime());                          // the zone is cropped out
    IO.println(ny.toOffsetDateTime());                         // just the offset, no rules
    IO.println(moment.atZone(ZoneId.of("Asia/Kolkata")));      // same moment, another wall
}

2026-03-08T07:30:00Z
2026-03-08T03:30-04:00[America/New_York]
2026-03-08T03:30
2026-03-08T03:30-04:00
2026-03-08T13:00+05:30[Asia/Kolkata]

everything in java.time (java 8, JSR 310) is immutable and thread-safe: plusDays returns a new object, just like String. that alone fixes half the bugs of the old java.util.Date.

daylight saving: the hour that doesn't exist

on 2026-03-08, new york's clocks go from 01:59:59 straight to 03:00. so 02:30 that night isn't a time, it's a hole. on 2026-11-01 they go from 01:59:59 back to 01:00, so every minute between 01:00 and 02:00 happens twice, an hour apart.

these are the rules of ZonedDateTime.of(...) and LocalDateTime.atZone(...):

• gap: no exception. the time moves forward by the length of the gap (02:30 → 03:30-04:00).
• overlap: the earlier offset wins. withLaterOffsetAtOverlap() gives you the other one, withEarlierOffsetAtOverlap() goes back.
• strict: if a non-existent time should be an error, ZonedDateTime.ofStrict(...) throws DateTimeException instead.

this is why a job scheduled for 02:30 new york time can silently skip a day in march, one at 01:30 can run twice in november, and why you never store a LocalDateTime and hope.

Duration vs Period

two ways to say "how long", and they disagree whenever a day isn't 24 hours.

Duration

an exact amount of time: seconds and nanos. PT2H15M. what a stopwatch measures.

Period

an amount of calendar: years, months, days. P1Y2M3D. what a calendar flips through.

var sat = ZonedDateTime.of(2026, 3, 7, 12, 0, 0, 0, ZoneId.of("America/New_York"));
IO.println(sat.plus(Period.ofDays(1)));     // "same time tomorrow"
IO.println(sat.plus(Duration.ofHours(24))); // "24 hours from now"

import java.time.*;
 
void main() {
    IO.println(LocalDate.of(2026, 1, 31).plusMonths(1));               // no feb 31: clamps to the 28th
    IO.println(Period.between(LocalDate.of(2026, 1, 31), LocalDate.of(2026, 3, 1)));
    var ny = ZoneId.of("America/New_York");
    IO.println(Duration.between(LocalDate.of(2026, 3, 8).atStartOfDay(ny),
                                LocalDate.of(2026, 3, 9).atStartOfDay(ny)));
    IO.println(Duration.ofMinutes(135));
}

2026-02-28
P1M1D
PT23H
PT2H15M

rule of thumb: timeouts, rate limits and measurements are Duration (on Instants). subscriptions, due dates and "every month on the 15th" are Period (on LocalDates or ZonedDateTimes).

formatting and parsing

toString() and parse() use ISO-8601 (2026-03-08T03:30-04:00) everywhere, which is what you want for anything a machine reads. for humans, DateTimeFormatter:

DateTimeFormatter.ofPattern("EEE d MMM uuuu, HH:mm", Locale.UK)   // Sun 8 Mar 2026, 07:30

formatters are immutable and thread-safe, so make them static final constants. (the old SimpleDateFormat is neither, and sharing one between threads corrupts dates silently.)

the old API

before java 8 there was java.util.Date (a mutable wrapper around milliseconds, whose toString uses the JVM's default zone) and Calendar (months numbered from 0, lenient by default). you'll still meet them in older libraries and JDBC code.

var c = new GregorianCalendar(2026, 1, 30);   // month 1 is february
c.getTime();   // no feb 30: silently rolls to march 2

LocalDate.of(2026, 2, 30);   // month 2 is february
// DateTimeException: Invalid date 'FEBRUARY 30'

to cross the boundary: date.toInstant() and Date.from(instant). then stay in java.time.