java.time API basics

Code Comparison

// Mutable, confusing, zero-indexed months
Calendar cal = Calendar.getInstance();
cal.set(2025, 0, 15); // January = 0!
Date date = cal.getTime();
// not thread-safe

LocalDate date = LocalDate.of(
    2025, Month.JANUARY, 15);
LocalTime time = LocalTime.of(14, 30);
Instant now = Instant.now();
// immutable, thread-safe

Why the modern way wins

🔒

Immutable

Date/time values can't be accidentally modified.

📖

Clear API

Month.JANUARY, not 0. DayOfWeek.MONDAY, not 2.

🛡️

Thread-safe

No synchronization needed — share freely across threads.

Old Approach

Date + Calendar

Modern Approach

java.time.*

JDK Support

java.time API basics

Available

Widely available since JDK 8 (March 2014)

How it works

java.time provides LocalDate, LocalTime, LocalDateTime, Instant, ZonedDateTime — all immutable and thread-safe. Months are 1-indexed. No more Calendar.JANUARY = 0 confusion.