What is the java.time Date/Time API?

• LocalDate represents a date without time or timezone, such as 2026-03-31 for a financial year-end.
• LocalTime represents a time without date, such as 14:30:00 for a branch closing time.
• LocalDateTime combines date and time but carries no timezone information.
• ZonedDateTime attaches a timezone to a date-time, essential when Mumbai (IST) and London (GMT) must display the same instant differently.
• Instant is a point on the UTC timeline, ideal for machine timestamps stored in databases.
• Duration measures time-based amounts like 250 milliseconds for a transaction processing time.
• Period measures date-based amounts like 1 year 6 months for a fixed deposit tenure.
• DateTimeFormatter provides thread-safe formatting, replacing the non-thread-safe SimpleDateFormat.

What is the java.time Date/Time API?

The java.time API was introduced in Java 8 as JSR-310. Every class is immutable and thread-safe. Methods like plusMonths and minusDays return new instances, leaving the original unchanged. Months are 1-based (January equals 1), fixing the confusing 0-based months in the old Calendar class.

Why does java.time exist?

The legacy Date, Calendar, and SimpleDateFormat classes had serious problems. Date is mutable, so passing it between threads causes race conditions. Calendar uses 0-based months (January equals 0), which causes off-by-one bugs. SimpleDateFormat is not thread-safe, so sharing one instance across requests corrupts output.

package com.bank.service;

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

public class DateTimeApiDemo {
    public static void main(String[] args) {
        // LocalDate: date on a cheque
        LocalDate fdOpenDate = LocalDate.of(2024, 10, 15);
        LocalDate fdMaturity = fdOpenDate.plusMonths(18);
        System.out.println("FD opens: " + fdOpenDate);
        System.out.println("FD matures: " + fdMaturity);

        // Period: tenure calculation
        Period tenure = Period.between(fdOpenDate, fdMaturity);
        System.out.println("Tenure: " + tenure.getYears() + " years "
            + tenure.getMonths() + " months");

        // Instant: UTC machine timestamp
        Instant txnTimestamp = Instant.now();
        System.out.println("UTC timestamp: " + txnTimestamp);

        // ZonedDateTime: display in customer's timezone
        ZonedDateTime mumbaiTime = txnTimestamp.atZone(ZoneId.of("Asia/Kolkata"));
        ZonedDateTime londonTime = txnTimestamp.atZone(ZoneId.of("Europe/London"));
        System.out.println("Mumbai: " + mumbaiTime);
        System.out.println("London: " + londonTime);

        // Duration: measure processing time
        Instant start = Instant.now();
        BigDecimal interest = new BigDecimal("100000")
            .multiply(new BigDecimal("0.07"));
        Instant end = Instant.now();
        Duration elapsed = Duration.between(start, end);
        System.out.println("Calculation took: " + elapsed.toNanos() + " ns");
    }
}

FD opens: 2024-10-15
FD matures: 2026-04-15
Tenure: 1 years 6 months
UTC timestamp: 2025-01-15T10:30:00.123456Z
Mumbai: 2025-01-15T16:00:00.123456+05:30[Asia/Kolkata]
London: 2025-01-15T10:30:00.123456Z[Europe/London]
Calculation took: 48200 ns

How is Instant different from ZonedDateTime?

| Aspect | Instant | ZonedDateTime |
|--------|---------|---------------|
| Purpose | Machine timestamp (storage) | Human display (UI) |
| Timezone | Always UTC | Carries a specific ZoneId |
| Use in DB | Store as TIMESTAMP WITH TIME ZONE | Convert from Instant for display only |
| Comparison | Compare directly (UTC) | Convert to Instant first |
| Created by | Instant.now() | instant.atZone(zoneId) |

How is java.time different from legacy Date and Calendar?

| Aspect | Legacy (Date/Calendar) | java.time |
|--------|----------------------|----------|
| Mutability | Mutable (setTime changes state) | Immutable (plusDays returns new object) |
| Thread safety | Not thread-safe | Thread-safe by design |
| Month numbering | 0-based (January = 0) | 1-based (January = 1) |
| Formatter | SimpleDateFormat (not thread-safe) | DateTimeFormatter (thread-safe) |
| Timezone | TimeZone class (mutable) | ZoneId (immutable) |

What are common mistakes with java.time?

package com.bank.core;

import java.time.LocalDate;

public class DateTimeMistakes {
    public static void main(String[] args) {
        LocalDate deposit = LocalDate.of(2024, 1, 15);

        // WRONG: ignoring the return value (LocalDate is immutable!)
        deposit.plusMonths(6); // returns new object, deposit is unchanged!
        System.out.println("Wrong: " + deposit); // still 2024-01-15

        // CORRECT: capture the return value
        LocalDate maturity = deposit.plusMonths(6);
        System.out.println("Correct: " + maturity); // 2024-07-15
    }
}

Wrong: 2024-01-15
Correct: 2024-07-15

What about DateTimeFormatter thread safety?

package com.bank.service;

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;

public class FormatterDemo {
    // SAFE: DateTimeFormatter is thread-safe, can be shared
    private static final DateTimeFormatter STATEMENT_FORMAT =
        DateTimeFormatter.ofPattern("dd-MMM-yyyy");

    public static void main(String[] args) {
        LocalDate today = LocalDate.now();
        String formatted = today.format(STATEMENT_FORMAT);
        System.out.println("Statement date: " + formatted);
    }
}

What about Duration vs Period?

Duration measures machine time in seconds and nanoseconds. Use it for measuring elapsed time, timeouts, and processing durations. Period measures human calendar time in years, months, and days. Use it for calculating age, tenure, and billing cycles.

What should a senior engineer know?

Always store timestamps as Instant (UTC) in the database column TIMESTAMP WITH TIME ZONE. Convert to ZonedDateTime only at the display layer when showing the time to a customer in their local timezone. Never store wall-clock times without a timezone because daylight saving transitions cause ambiguity. Use Clock for testability: inject Clock.fixed(...) in tests instead of calling Instant.now() directly.