BackendBench
Coffee

Unravel โ€บ Java concepts โ€บ Time and dates

Java language

java.time dates and times

The java.time classes separate a point on the timeline (Instant), a calendar date or time without a zone (LocalDate, LocalDateTime) and a zoned moment (ZonedDateTime).

๐Ÿ”Ž Unravel this example

At a glance

Mental model

Instant is a stopwatch reading shared by the whole world; LocalDateTime is what a wall clock shows with no country attached; ZonedDateTime is the wall clock in a specific city.

What happens, in order
  1. 1Store and exchange moments as Instant (UTC) or ISO-8601 stringsConvert to ZonedDateTime with a ZoneId only when showing to a person.
  2. 2LocalDate is a date with no time or zone (a birthday)LocalDateTime has no zone, so it does not identify a moment; do not store it for events.
  3. 3Duration measures time-based amounts (hours, seconds) and Period date-based amounts (months, days)They are immutable; plus returns a new object.
  4. 4DateTimeFormatter formats and parsesIt is thread safe, unlike the old SimpleDateFormat.
Remember
Watch out
Storing LocalDateTime for real eventsAdding 24 hours when meaning "next day"Calling now() everywhere, which makes code untestableThe legacy Date and SimpleDateFormat
Example (highlighted lines explain it)
Instant now = clock.instant();ZonedDateTime inTokyo = now.atZone(ZoneId.of("Asia/Tokyo"));LocalDate tomorrow = LocalDate.now(clock).plusDays(1);Duration timeout = Duration.ofSeconds(30);String text = DateTimeFormatter.ISO_LOCAL_DATE.format(tomorrow);
  1. line 1 uses Instant, the core of java.time dates and times
  2. line 2 uses ZonedDateTime, the core of java.time dates and times
  3. line 3 uses LocalDate, the core of java.time dates and times
  4. line 4 uses Duration, the core of java.time dates and times
  5. line 5 uses DateTimeFormatter, the core of java.time dates and times
Read the full explanation (about 1 min)

The java.time classes separate a point on the timeline (Instant), a calendar date or time without a zone (LocalDate, LocalDateTime) and a zoned moment (ZonedDateTime). Choosing the right one avoids time zone bugs.

A mental model

Instant is a stopwatch reading shared by the whole world; LocalDateTime is what a wall clock shows with no country attached; ZonedDateTime is the wall clock in a specific city.

How it works

Store and exchange moments as Instant (UTC) or ISO-8601 strings. Convert to ZonedDateTime with a ZoneId only when showing to a person.

LocalDate is a date with no time or zone (a birthday). LocalDateTime has no zone, so it does not identify a moment; do not store it for events.

Duration measures time-based amounts (hours, seconds) and Period date-based amounts (months, days). They are immutable; plus returns a new object.

DateTimeFormatter formats and parses. It is thread safe, unlike the old SimpleDateFormat.

Going deeper

Daylight saving makes "add one day" differ from "add 24 hours" in a zone. A local time can be skipped (spring forward) or occur twice (fall back). Inject a Clock instead of calling now() directly so tests control the time.

Under the hood

An Instant is seconds plus nanoseconds since the epoch. Zone rules come from the tz database bundled with the JDK, so an old JDK can have stale rules.

Common mistakes

  • Storing LocalDateTime for real events.
  • Adding 24 hours when meaning "next day".
  • Calling now() everywhere, which makes code untestable.
  • The legacy Date and SimpleDateFormat.

How Unravel recognises it

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

Part of a learning path

Builds on this

Time zones, DST and InstantJava languageFormatting, parsing and date arithmeticJava language

Frequently asked questions

What is java.time dates and times?

The java.time classes separate a point on the timeline (Instant), a calendar date or time without a zone (LocalDate, LocalDateTime) and a zoned moment (ZonedDateTime). Choosing the right one avoids time zone bugs.

What are the most common mistakes with java.time dates and times?

Storing LocalDateTime for real events. Adding 24 hours when meaning "next day". Calling now() everywhere, which makes code untestable. The legacy Date and SimpleDateFormat.

How can I see java.time dates and times in real code?

Paste your own Java into Unravel and it will point out where java.time dates and times appears, explain how it works at the detail level you choose, and draw the flow of the code around it.