Date & Time API

Adding a Period of 1 day to a ZonedDateTime moves to the same wall-clock time next day, even if that day was 23 or 25 hours long. Adding a Duration of 24 hours adds exactly 24 hours of real time, so the wall-clock time can shift across a DST change.

Parsing bad text throws DateTimeParseException. The ResolverStyle decides how strict validation is: STRICT rejects out-of-range values, SMART (the default) corrects mild ones, LENIENT rolls overflow over (e.g. day 32 -> next month).

Because Date can be changed after creation, getters and constructors must return defensive copies, or callers can secretly mutate your object's state. java.time types are immutable, so no copying is needed and they are safe to share.

Feb 29 only exists in leap years. If you add one year to Feb 29 and the target year isn't a leap year, java.time adjusts the result to Feb 28 instead of failing. It never produces an invalid date like Feb 30.

Start of next month: date.with(firstDayOfNextMonth()).atStartOfDay(). The clean way to bound the current month is a half-open range [firstDayOfMonth at 00:00, firstDayOfNextMonth at 00:00), using less-than for the upper bound instead of trying to find the exact last instant.

When clocks change, some local times don't exist (spring-forward gap) and some happen twice (fall-back overlap). atZone resolves a gap by shifting the time forward, and an overlap by picking the earlier offset by default; you can override with withLaterOffsetAtOverlap().

java.time types never change after creation (immutable), so multiple threads reading the same instance can't interfere. The old Date is mutable and SimpleDateFormat keeps internal state, so sharing them across threads causes corruption.

OffsetDateTime is a local date-time plus a fixed UTC offset (like +02:00). ZonedDateTime is a local date-time plus a full region (like Europe/Paris) that knows daylight saving rules, so it can adjust offsets correctly over time.

Store an exact instant (UTC) for things that already happened, so they are unambiguous. For future events tied to a place's wall clock, store the local time plus the ZoneId (not a fixed offset), so the right offset is applied when DST rules change. Never store bare local time alone.

LocalDateTime has no time zone, so a stored value like 2026-02-14T09:30 is ambiguous — you can't tell which real moment it was. For timestamps that cross zones, store an Instant or OffsetDateTime instead, and keep LocalDateTime only for true wall-clock data.

The tz database is the global dataset of time-zone rules (offsets and daylight-saving changes) that Java uses behind ZoneId. Governments change those rules, so updates matter: a future local time stored as a region can resolve to a different instant if the rules change.

TemporalAdjuster has one method, so you can write it as a lambda. The easiest way is TemporalAdjusters.ofDateAdjuster, which takes a function from LocalDate to LocalDate; inside it you check the weekday and add the right number of days to skip the weekend.

Each call makes a small new object, but these are tiny and short-lived, so the JVM handles them cheaply. It only matters in very hot, high-volume loops; usually you measure first and prefer correctness and clarity over avoiding allocation.