Date and Time API

Java 8 introduced the java.time package to replace the old, error-prone java.util.Date and java.util.Calendar classes. The new API is modeled closely on the well-regarded Joda-Time library and fixes long-standing problems: the old classes were mutable, not thread-safe, used confusing zero-based months, and mixed date, time, and timezone concerns into a small number of overloaded classes.

Why it matters

Dates appear in almost every application: due dates, bookings, subscriptions, reports. The old Date and Calendar classes were mutable and easy to misuse, and they still appear in legacy code. The java.time API is what you should write today, and its immutability and clear class names remove most date bugs.

Core Classes

java.time splits date and time concerns into focused, purpose-built classes:

• LocalDate — a date without time or timezone, such as 2026-09-21.
• LocalTime — a time without date or timezone, such as 14:30:00.
• LocalDateTime — a combined date and time, still without timezone.
• Period — a date-based amount of time (years, months, days), used for differences between LocalDate values.
• Duration — a time-based amount (hours, minutes, seconds, nanoseconds), used for differences between time-based values.
• DateTimeFormatter — formats and parses date/time objects using a pattern, replacing the old and not-thread-safe SimpleDateFormat.

Immutability

Every class in java.time is immutable: methods like plusDays() or minusMonths() return a brand-new object with the adjusted value rather than modifying the original in place. This makes the classes inherently thread-safe and eliminates a whole category of bugs where a shared Date object was silently mutated by one part of a program and unexpectedly affected another.

Example

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

public class DateTimeDemo {
    public static void main(String[] args) {
        LocalDate today = LocalDate.of(2026, 9, 21);
        LocalDate nextMonth = today.plusMonths(1); // returns a new LocalDate, today is unchanged

        System.out.println("Today: " + today);
        System.out.println("Next month: " + nextMonth);

        LocalDate birthday = LocalDate.of(2000, 5, 15);
        Period age = Period.between(birthday, today);
        System.out.println("Age: " + age.getYears() + " years, " + age.getMonths() + " months");

        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("dd-MMM-yyyy");
        System.out.println(today.format(formatter));
    }
}

Today: 2026-09-21
Next month: 2026-10-21
Age: 26 years, 4 months
21-Sep-2026

Exercise

Starting from 31 January 2024, add one month and print the result, then print that date in the pattern dd/MM/yyyy. Finally print the number of days from 1 January 2024 to 1 March 2024.

Expected output: 2024-02-29, 29/02/2024, 60 (one per line)

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

public class DatePractice {
    public static void main(String[] args) {
        LocalDate start = LocalDate.of(2024, 1, 31);

        // TODO: add one month and print the new date
        // TODO: print the new date formatted as dd/MM/yyyy
        // TODO: print the days between 2024-01-01 and 2024-03-01
    }
}

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

public class DatePractice {
    public static void main(String[] args) {
        LocalDate start = LocalDate.of(2024, 1, 31);

        LocalDate next = start.plusMonths(1);
        System.out.println(next); // 2024-02-29 (2024 is a leap year)

        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("dd/MM/yyyy");
        System.out.println(next.format(formatter)); // 29/02/2024

        long days = ChronoUnit.DAYS.between(LocalDate.of(2024, 1, 1), LocalDate.of(2024, 3, 1));
        System.out.println(days); // 60
    }
}

Quick quiz

Interview questions