Java Time API Guide: Mastering java.time & JSR-310

1. The java.time Type Hierarchy (JSR-310)

Introduced in Java 8 via JSR-310 (authored by Stephen Colebourne), the java.time package separates physical timeline concepts from human wall-clock concepts.

2. Instant vs. ZonedDateTime vs. OffsetDateTime

3. Migrating Legacy java.util.Date to Instant

// Converting legacy java.util.Date to modern Instant
java.util.Date legacyDate = new java.util.Date();
Instant instant = legacyDate.toInstant();

// Converting Instant to ZonedDateTime in Eastern Time
ZonedDateTime estDateTime = instant.atZone(ZoneId.of("America/New_York"));
System.out.println(estDateTime); 
// Output: 2026-07-30T10:00:00-04:00[America/New_York]

4. Formatting & Parsing with DateTimeFormatter

DateTimeFormatter is completely thread-safe (unlike legacy SimpleDateFormat):

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss z")
    .withZone(ZoneId.of("America/New_York"));

ZonedDateTime nowEst = ZonedDateTime.now(ZoneId.of("America/New_York"));
String formattedStr = formatter.format(nowEst);
System.out.println(formattedStr); // "2026-07-30 10:00:00 EDT"

5. Spring Boot, Jackson & JPA Database Mapping

In Spring Boot applications, configure Jackson to serialize OffsetDateTime cleanly as ISO strings:

# application.properties
spring.jackson.serialization.write-dates-as-timestamps=false
spring.jpa.properties.hibernate.jdbc.time_zone=UTC

6. Unit Testing with Clock Mocking

Avoid calling Instant.now() directly in business logic. Inject java.time.Clock:

// Service Class
public class OrderService {
    private final Clock clock;
    public OrderService(Clock clock) { this.clock = clock; }

    public Instant createOrder() {
        return Instant.now(clock);
    }
}

// Unit Test Class
Clock fixedClock = Clock.fixed(Instant.parse("2026-07-30T14:00:00Z"), ZoneId.of("UTC"));
OrderService service = new OrderService(fixedClock);
assertEquals(Instant.parse("2026-07-30T14:00:00Z"), service.createOrder());

7. Handling DST Shifts with Duration & Period

Use Duration for physical time (seconds) and Period for calendar time (days/months):

• ZonedDateTime.now().plus(Period.ofDays(1)) keeps 9:00 AM wall-clock time across DST shifts.
• ZonedDateTime.now().plus(Duration.ofHours(24)) advances exactly 86,400 physical seconds.

8. Code Snippets & Execution Cheatsheet

import java.time.*;
import java.time.format.DateTimeFormatter;

public class TimeZoneConverter {
    public static String convertGmtToEst(String isoUtcString) {
        Instant instant = Instant.parse(isoUtcString);
        ZonedDateTime estTime = instant.atZone(ZoneId.of("America/New_York"));
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss z");
        return estTime.format(formatter);
    }

    public static void main(String[] args) {
        System.out.println(convertGmtToEst("2026-07-30T18:00:00Z"));
        // Output: "2026-07-30 14:00:00 EDT"
    }
}

9. Frequently Asked Questions (FAQ)

Explore 20 detailed questions and answers about Java JSR-310 time zone development: