Date & Time API — Java Course

What you'll learn

Dates and times are deceptively tricky — leap years, time zones, daylight saving. Java's modern java.time API (introduced in Java 8) handles all of it cleanly and safely. This module gets you comfortable with it.

By the end you'll be able to:

Use LocalDate, LocalTime, and LocalDateTime
Represent amounts of time with Duration and Period
Work across time zones with Instant and ZonedDateTime
Format and parse dates, and do date arithmetic safely

Why java.time?

The old java.util.Date and Calendar classes were error-prone: mutable, poorly designed (months counted from 0!), and not thread-safe. The modern java.time package fixes all of that. Its types are immutable and thread-safe, with a clean, readable API. Always use it for new code.

The core types

The API separates concerns into focused, well-named types — pick the one that matches exactly what you mean:

The java.time types

LocalDate

A date: 2026-08-23

LocalTime

A time: 14:30

LocalDateTime

Date + time, no zone

ZonedDateTime

Date + time + zone

Instant

A point on the UTC timeline

Duration

An amount of time (hours, seconds)

Period

An amount of dates (years, months, days)

DateTime.java

import java.time.*;

LocalDate birthday = LocalDate.of(2000, 5, 15);
LocalTime noon = LocalTime.of(12, 0);
LocalDateTime meeting = LocalDateTime.of(2026, 8, 23, 14, 30);

System.out.println(birthday);   // 2000-05-15
System.out.println(noon);       // 12:00
System.out.println(meeting);    // 2026-08-23T14:30

// LocalDate.now() / LocalTime.now() give the current values

Duration, Period & arithmetic

Because these types are immutable, methods like plusDays and minusMonths return a new object rather than changing the original. Two types describe amounts of time: Period for date-based amounts (years, months, days) and Duration for time-based amounts (hours, minutes, seconds):

Amounts.java

import java.time.*;

LocalDate start = LocalDate.of(2026, 1, 1);
LocalDate end = start.plusMonths(2).plusDays(30);   // immutable: returns new
System.out.println(end);                            // 2026-03-31

Period age = Period.between(
    LocalDate.of(2000, 5, 15), LocalDate.of(2026, 8, 23));
System.out.println(age.getYears() + " years");      // 26 years

Duration d = Duration.ofHours(2).plusMinutes(30);
System.out.println(d.toMinutes() + " minutes");     // 150 minutes

Tip

Every plus/minus call returns a new value — remember to assign the result. Writing date.plusDays(1); on its own does nothing; use date = date.plusDays(1);.

Time zones

Instant is a single moment on the global UTC timeline — perfect for timestamps. ZonedDateTime attaches a ZoneId (like "Europe/Beirut" or "America/New_York") so the same instant can be shown in local time anywhere, with daylight saving handled for you.

Note

Best practice: store timestamps as Instant (UTC), and only convert to a ZonedDateTime for display. This avoids a whole category of time-zone bugs.

Formatting & parsing

Turn a date into text with format and text back into a date with parse, using a DateTimeFormatter to control the pattern (dd = day, MMM = month name, yyyy = year, and so on):

Formatting.java

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

LocalDate date = LocalDate.of(2026, 8, 23);
DateTimeFormatter fmt = DateTimeFormatter.ofPattern("dd MMM yyyy");
System.out.println(date.format(fmt));        // 23 Aug 2026

LocalDate parsed = LocalDate.parse("2026-12-25");   // ISO format
System.out.println(parsed.getDayOfWeek());   // FRIDAY

Recap & quick check

Key takeaways

Use the modern java.time API — its types are immutable and thread-safe.
LocalDate/LocalTime/LocalDateTime for zone-free values; ZonedDateTime/Instant for zones and timestamps.
Period measures date amounts (years/months/days); Duration measures time amounts (hours/minutes).
Methods like plusDays return a NEW object — always assign the result.
Store timestamps in UTC (Instant); convert to a zone only for display.

Quick check

1. Which type represents a date with no time or zone?

2. What does date.plusDays(1) do if you don't assign it?

3. Which measures an amount of years/months/days?

4. What should you store timestamps as, ideally?

5. Why prefer java.time over the old Date/Calendar?

Nicely done — dates and times hold no fear now. Next up: Module 17 — Functional Programming & Lambdas, a turning point in modern Java.