java.time API basics

Use immutable, clear date/time types instead of Date and Calendar.

Code Comparison

✕ Pre-Java 8

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

✓ Java 8+

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

Share 𝕏

See a problem with this code? Let us know.

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.*

Since JDK

Difficulty

Beginner

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.

Instant with nanosecond precision

Java 8

// Millisecond precision only
long millis =
    System.currentTimeMillis();
// 1708012345678

Java 9+

// Microsecond/nanosecond precision
Instant now = Instant.now();
// 2025-02-15T20:12:25.678901234Z
long nanos = now.getNano();

Hover to see modern ➜

JDK 9+ →

Date/Time Beginner

Duration and Period

Pre-Java 8

// How many days between two dates?
long diff = date2.getTime()
    - date1.getTime();
long days = diff
    / (1000 * 60 * 60 * 24);
// ignores DST, leap seconds

Java 8+

long days = ChronoUnit.DAYS
    .between(date1, date2);
Period period = Period.between(
    date1, date2);
Duration elapsed = Duration.between(
    time1, time2);

Hover to see modern ➜

JDK 8+ →

Date/Time Beginner

Date formatting

Pre-Java 8

// Not thread-safe!
SimpleDateFormat sdf =
    new SimpleDateFormat("yyyy-MM-dd");
String formatted = sdf.format(date);
// Must synchronize for concurrent use

Java 8+

DateTimeFormatter fmt =
    DateTimeFormatter.ofPattern(
        "uuuu-MM-dd");
String formatted =
    LocalDate.now().format(fmt);
// Thread-safe, immutable

Hover to see modern ➜

JDK 8+ →