Modern Date & Time API (java.time JSR-310) & Temporal Modeling

Phase 14

📂 Module 2_ Java LTS Features \ Modern Core Java Date/Time

📖 Core Java Textbook Alignment: Cay S. Horstmann • Volume II — Chapter 6: The Date and Time API

17.1 The java.time Architecture vs Legacy java.util.Date Traps

📖 Cay S. Horstmann • Core Java Volume II — Chapter 6, Section 6.1 ("The Time Line")

“Java 1.0 had a java.util.Date class that was, frankly, an embarrassment. Years were offset by 1900, months were 0-based, and instances were mutable. The replacement java.util.Calendar was not much better. The java.time API, introduced in Java 8 and refined across LTS releases, introduces a clean separation between human time (local dates, days of week, time zones) and machine time (an instantaneous point along the continuous timeline). Every class in java.time is strictly immutable and thread-safe.”

Thread-Safety Axiom No Mutability: Unlike java.util.Date or SimpleDateFormat, classes in java.time are immutable. Calling plusDays(1) returns a brand-new instance; existing objects are never modified.
Machine vs Human Time Instant vs ZonedDateTime: Instant represents UTC nanoseconds since Unix epoch. LocalDate / ZonedDateTime models calendars and daylight saving offsets.

💡 Real-World Analogy: The Mutable Mechanical Watch vs The Atomic Server Timestamp

• Old java.util.Date: Like handing someone your wristwatch. If they adjust the dial to 3:00 PM, YOUR watch is now wrong everywhere in the building! (Mutable shared state bug).
• Modern java.time: Like sending a printed photo of an atomic clock. You can take a new photo tomorrow, but nobody can alter yesterday's photo.

⚡ Pro-Tip / Interview Memory Hook: Duration vs Period & SimpleDateFormat Ban

Duration vs Period: Use Duration for machine time (seconds, nanoseconds, e.g. cache TTLs). Use Period for human calendar time (days, months, years, e.g. age calculations).
SimpleDateFormat is DEAD: SimpleDateFormat is stateful and NOT thread-safe; sharing it across threads silently corrupts dates! Always use DateTimeFormatter.ISO_LOCAL_DATE or DateTimeFormatter.ofPattern(...).

📂 ModernDateTimeDemo.java — JSR-310 Production Temporal Patterns

package com.accenture.ltt.datetime;

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

public class ModernDateTimeDemo {
    public static void main(String[] args) {
        // 1. Machine Timestamp (Instant UTC)
        Instant nowUtc = Instant.now();
        System.out.println("UTC Instant: " + nowUtc);

        // 2. Human Calendar Time (LocalDate & ZonedDateTime)
        LocalDate releaseDate = LocalDate.of(2026, Month.OCTOBER, 10);
        ZonedDateTime tokyoTime = releaseDate.atStartOfDay(ZoneId.of("Asia/Tokyo"));
        System.out.println("Tokyo Schedule: " + tokyoTime);

        // 3. Elapsed Time Calculations (Duration vs Period)
        LocalDate birthDate = LocalDate.of(2000, 1, 15);
        Period age = Period.between(birthDate, LocalDate.now());
        System.out.println("Years: " + age.getYears() + ", Months: " + age.getMonths());

        // 4. Safe Thread-Safe Formatting
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss z");
        System.out.println("Formatted: " + tokyoTime.format(formatter));
    }
}

👁 Execution & Memory Breakdown • java.time Immutability

Step 1: LocalDate.of() creates a private final record structure with zero heap mutability.

Step 2: DateTimeFormatter instances are pure constants; can safely be assigned to public static final fields without synchronization locks.