Master Java 8 Date & Time API: From LocalDate to ZonedDateTime

1. Overview

Java 8 introduced a new Date and Time API to address the shortcomings of java.util.Date and java.util.Calendar.

This article examines the problems of the old API and demonstrates how the new classes such as LocalDate, LocalTime, LocalDateTime, ZonedDateTime, Period, and Duration solve them.

2. Problems with the old API (pre‑Java 8)

Thread safety – Date and Calendar are mutable and not thread‑safe.

API design – Complex, hard to understand, lacking common parsing/formatting methods.

Time‑zone handling – Requires extra logic; the new API provides built‑in zone support.

3. Using LocalDate, LocalTime and LocalDateTime

LocalDate

represents a date without time (ISO YYYY‑MM‑DD). Example: LocalDate localDate = LocalDate.now(); Creating a specific date:

LocalDate date = LocalDate.of(2015, 2, 20);
LocalDate date = LocalDate.parse("2015-02-20");

Adding and subtracting days, months, etc.:

LocalDate tomorrow = LocalDate.now().plusDays(1);
LocalDate previousMonth = LocalDate.now().minus(1, ChronoUnit.MONTHS);

LocalTime

represents a time without a date. Example: LocalTime now = LocalTime.now(); Parsing and creating specific times:

LocalTime sixThirty = LocalTime.parse("06:30");
LocalTime sixThirty = LocalTime.of(6, 30);
LocalTime sevenThirty = LocalTime.parse("06:30").plus(1, ChronoUnit.HOURS);

LocalDateTime

combines date and time:

LocalDateTime now = LocalDateTime.now();
LocalDateTime specific = LocalDateTime.of(2015, Month.FEBRUARY, 20, 6, 30);
LocalDateTime parsed = LocalDateTime.parse("2015-02-20T06:30:00");

Adding and subtracting units works the same as with LocalDate:

localDateTime.plusDays(1);
localDateTime.minusHours(2);

4. ZonedDateTime and time‑zone handling

ZonedDateTime

represents a date‑time with a specific zone. Example:

ZoneId zoneId = ZoneId.of("Asia/Shanghai");
ZonedDateTime zdt = ZonedDateTime.of(localDateTime, zoneId);

All available zone IDs can be obtained with ZoneId.getAvailableZoneIds(). OffsetDateTime provides a similar immutable representation with an explicit offset.

5. Period and Duration

Period

calculates the amount of time in years, months, and days between two dates:

LocalDate start = LocalDate.parse("2007-05-10");
LocalDate end = start.plus(Period.ofDays(5));
int days = Period.between(end, start).getDays();

Duration

works with time‑based amounts (seconds, nanoseconds):

LocalTime start = LocalTime.of(6, 30, 0);
LocalTime end = start.plus(Duration.ofSeconds(30));
int seconds = Duration.between(end, start).getSeconds();

6. Compatibility with the legacy Date/Calendar

The new API can be created from old objects using toInstant() and ofInstant(..., ZoneId.systemDefault()):

LocalDateTime ldt = LocalDateTime.ofInstant(date.toInstant(), ZoneId.systemDefault());
LocalDateTime ldt2 = LocalDateTime.ofInstant(calendar.toInstant(), ZoneId.systemDefault());

7. Alternative libraries

For projects on Java 6/7, the ThreeTen‑BP library provides the same API as Java 8.

<dependency>
    <groupId>org.threeten</groupId>
    <artifactId>threetenbp</artifactId>
    <version>LATEST</version>
</dependency>

Joda‑Time is another widely used date‑time library that offers comparable functionality.

<dependency>
    <groupId>joda-time</groupId>
    <artifactId>joda-time</artifactId>
    <version>LATEST</version>
</dependency>