Java 8 introduced the java.time package as JSR-310, designed by Stephen Colebourne (creator of Joda-Time). The package centers on five main classes: Instant, OffsetDateTime, ZonedDateTime, LocalDateTime, and LocalDate. Each represents a different level of information about a moment in time, and choosing the right one is the foundation of correct time zone handling.
The selection rule is to use the class with the minimum information needed. Use LocalDate or LocalDateTime when no time zone is involved, OffsetDateTime when a UTC offset is sufficient, ZonedDateTime when you need IANA time zone semantics that follow future DST changes, and Instant when you only care about an absolute moment. Picking the least expressive type that fits prevents accidental information loss and simplifies reasoning.
| Class | Information stored | Typical use |
|---|---|---|
| Instant | Seconds and nanoseconds since the epoch, no zone | Logs, event times, machine timestamps |
| OffsetDateTime | Date-time plus a UTC offset such as +09:00 | Database columns, serialization, completed records |
| ZonedDateTime | Date-time plus an IANA zone such as Asia/Tokyo | Future appointments that must follow DST rule changes |
| LocalDateTime | Date-time only, no offset and no zone | Values where geography is irrelevant, raw form input |
| LocalDate | Date only | Birthdays, public holidays, closing dates |
The rows are not ranked by richness; they differ in meaning. The rule is to pick the class that carries exactly the information the value needs.
Instant represents an absolute moment as nanoseconds since the Unix epoch (1970-01-01T00:00:00Z). It carries no time zone information and represents the same moment everywhere on Earth. Log timestamps, event creation times, and API response times typically should be Instant because their meaning is independent of any local time zone.
Arithmetic on Instant is straightforward and predictable. plus(Duration.ofHours(1)) always advances exactly one physical hour, regardless of any DST transition. The trade-off is that Instant cannot directly answer questions like "what date is it in Tokyo?" without first being combined with a ZoneId. Conversion only happens at presentation, which is exactly the right place for it.
ZonedDateTime combines a LocalDateTime with a ZoneId such as Asia/Tokyo. It carries the IANA zone name and therefore tracks future DST changes and historical zone updates. For ambiguous wall-clock times during DST transitions, ZonedDateTime offers withEarlierOffsetAtOverlap() and withLaterOffsetAtOverlap() to make the choice explicit.
ZonedDateTime arithmetic switches time lines depending on the unit you add. The javadoc defines time-based methods such as plusHours as operating on the instant time line: adding one hour is always a duration of one hour later, and that may cause the local date-time to change by an amount other than one hour. Crossing a spring-forward boundary is exactly that case, and the wall clock appears to jump two hours. Date-based methods such as plusDays operate on the local time line instead, keeping the wall-clock time while moving the date, which is the human intuition of "the same time tomorrow." As the javadoc puts it, adding one day is not the same as adding 24 hours: the physical elapsed time can be 23 or 25 hours. Use plusHours or Duration when you want physical time, plusDays or Period when you want the wall clock preserved, and always include DST boundary tests when arithmetic is critical.
| Start | Operation | Result | Physical time elapsed |
|---|---|---|---|
| 2026-03-08T01:30-05:00 | plusHours(1) | 2026-03-08T03:30-04:00 | 1 hour |
| 2026-03-08T01:30-05:00 | plusDays(1) | 2026-03-09T01:30-04:00 | 23 hours |
| 2026-11-01T01:30-04:00 | plusHours(1) | 2026-11-01T01:30-05:00 | 1 hour |
| 2026-11-01T01:30-04:00 | plusDays(1) | 2026-11-02T01:30-05:00 | 25 hours |
Time-based addition keeps the elapsed column constant while the wall clock jumps two hours in March and does not move at all in November. Date-based addition keeps the wall clock at 01:30 and lets the elapsed time become 23 or 25 hours instead.
OffsetDateTime is similar to ZonedDateTime, but it stores only a UTC offset like +09:00 instead of a full IANA zone. The moment is unambiguous because the offset locks in the UTC time, but it does not track future DST policy changes. This makes it ideal for serialization formats like ISO 8601 and RFC 3339, where both the local time and the UTC offset are expressed verbatim.
PostgreSQL's TIMESTAMP WITH TIME ZONE column stores values as UTC internally, and the JDBC driver typically maps it to OffsetDateTime or Instant. Persisting OffsetDateTime preserves the original offset for audit purposes while still permitting unambiguous conversion to UTC. Using ZonedDateTime for stored data risks reinterpretation if the country later changes its DST policy retroactively.
Spring Boot 3.x and Hibernate 6 support Instant and OffsetDateTime as entity field types directly. Legacy code using java.util.Date or Calendar should be migrated, with column types selected to match: TIMESTAMP for unzoned local times, TIMESTAMPTZ (PostgreSQL) or TIMESTAMP (MySQL with serverTimezone configured) for absolute times. The mapping you pick at the entity level directly determines whether time zone bugs are possible at all.
JSON serialization with Jackson deserves attention as well. A plain Jackson setup with JavaTimeModule registered emits Instants as numeric epoch seconds, surprising API consumers expecting ISO 8601 strings. Rather than trusting framework defaults, pin the behaviour explicitly with a setting such as spring.jackson.serialization.write-dates-as-timestamps=false so the output stays ISO 8601, which is the modern standard and what JavaScript libraries like Day.js and Luxon expect. Aligning serialization conventions across the stack saves countless interop bugs.
Start with the question "do I need a notion of human geography here?" If the answer is no (logs, events, machine timestamps), use Instant. If yes, ask whether the value must follow future zone rule changes. For user-scheduled future events such as alarms, ZonedDateTime is correct. For historical records and completed transactions, OffsetDateTime is safer because the meaning is frozen at write time. For pure dates without any time-of-day component, LocalDate is the right answer.
It is normal and healthy for a single application to use multiple types from java.time. Forcing everything into ZonedDateTime gives logs more information than they need and complicates serialization. Document at the boundary layers (DTOs, DB columns, API contracts) which type each field uses, and 90 percent of timezone bugs simply disappear. The remaining 10 percent are usually about test coverage at DST boundaries, which proper unit tests can catch early.
Was this article helpful?
Python 3.9 introduced zoneinfo as the standard library solution for IANA time zones, but the long-established pytz package remains in many codebases. This article compares the two, explains the naive vs aware boundary, and covers practical pitfalls including Windows tzdata, the fold attribute, and migration strategy.
MySQL timezone bugs almost always trace back to a misunderstanding of three layers: server defaults, session settings, and column types. This article explains why TIMESTAMP and DATETIME behave differently, how the time_zone variable interacts with connections, and how to configure JDBC drivers correctly.
Building a timezone conversion API sounds simple but quickly hits IANA database management, DST gap handling, error semantics, and caching strategy. This article covers the design decisions that determine whether the endpoint stays reliable as policies and tzdata evolve.