Java 8 & Streams · Chapter 21

Date and Time API (java.time)

LocalDate, LocalTime, LocalDateTime, ZonedDateTime, Instant, Period, Duration and DateTimeFormatter — the immutable, thread-safe replacement for Date and Calendar.

◷ 5 min read§ 17 sections? 4 interview questions{ } 16 code examples

#Introduction

Java 8 introduced the java.time package to replace the old Date and Calendar APIs. The new API is immutable, thread-safe, and much easier to use.

#Important Classes

Class	Purpose
`LocalDate`	Date only
`LocalTime`	Time only
`LocalDateTime`	Date + time
`ZonedDateTime`	Date + time + time zone
`Instant`	UTC timestamp
`Period`	Difference in years, months, days
`Duration`	Difference in hours, minutes, seconds
`DateTimeFormatter`	Formatting and parsing dates

java.time
- Human date/time
  - LocalDatedate only
  - LocalTimetime only
  - LocalDateTimedate + time
  - ZonedDateTime+ time zone
- Machine time
  - InstantUTC timestamp
- Amounts
  - Periodyears, months, days
  - Durationhours, minutes, seconds

#LocalDate

Represents only a date (year-month-day).

Java

import java.time.LocalDate;

LocalDate today = LocalDate.now();
System.out.println(today);

Output

2026-06-15

Common Methods

Java

today.getYear();         // 2026
today.getMonth();        // JUNE (a Month enum)
today.getDayOfMonth();   // 15
today.getDayOfWeek();    // MONDAY (a DayOfWeek enum)

#LocalTime

Represents only time.

Java

import java.time.LocalTime;

LocalTime now = LocalTime.now();
System.out.println(now);

Output

10:30:45.123

Common Methods

Java

now.getHour();
now.getMinute();
now.getSecond();

#LocalDateTime

Represents both date and time without a time zone.

Java

import java.time.LocalDateTime;

LocalDateTime current = LocalDateTime.now();
System.out.println(current);

Output

2026-06-15T10:30:45

#Create a Custom Date

Java

LocalDate date = LocalDate.of(2026, 6, 15);
System.out.println(date);

Output

2026-06-15

#Add and Subtract Dates

Java

LocalDate today = LocalDate.now();

today.plusDays(5);
today.plusMonths(2);
today.plusYears(1);
today.minusDays(10);

Since LocalDate is immutable, these methods return a new object.

#Compare Dates

Java

LocalDate d1 = LocalDate.of(2026, 1, 1);
LocalDate d2 = LocalDate.of(2026, 12, 31);

System.out.println(d1.isBefore(d2));
System.out.println(d1.isAfter(d2));
System.out.println(d1.equals(d2));

Output

true
false
false

#Date Formatting

Java

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

LocalDate date = LocalDate.now();

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("dd-MM-yyyy");

String formatted = date.format(formatter);
System.out.println(formatted);

Output

15-06-2026

Common Formatting Patterns

Pattern	Example
`dd/MM/yyyy`	`15/06/2026`
`dd-MM-yyyy`	`15-06-2026`
`yyyy-MM-dd`	`2026-06-15`
`dd MMM yyyy`	`15 Jun 2026`
`dd MMMM yyyy`	`15 June 2026`
`HH:mm:ss`	`14:30:45` (24-hour)
`hh:mm a`	`02:30 PM` (12-hour)

#Parse a String into a Date

Java

String dateStr = "15-06-2026";

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("dd-MM-yyyy");

LocalDate date = LocalDate.parse(dateStr, formatter);

System.out.println(date);

Output

2026-06-15

#Period (Difference Between Dates)

Used to calculate the difference between two dates.

Java

import java.time.LocalDate;
import java.time.Period;

LocalDate start = LocalDate.of(2020, 1, 1);
LocalDate end = LocalDate.now();

Period period = Period.between(start, end);

System.out.println(period.getYears());
System.out.println(period.getMonths());
System.out.println(period.getDays());

#Duration (Difference Between Times)

Used to calculate the difference between two times.

Java

import java.time.Duration;
import java.time.LocalTime;

LocalTime start = LocalTime.of(10, 0);
LocalTime end = LocalTime.of(12, 30);

Duration duration = Duration.between(start, end);

System.out.println(duration.toHours());
System.out.println(duration.toMinutes());

Output

2
150

#Working with Time Zones

Java

import java.time.ZoneId;
import java.time.ZonedDateTime;

ZonedDateTime india = ZonedDateTime.now(ZoneId.of("Asia/Kolkata"));

System.out.println(india);

Output

2026-06-15T10:30:45.123+05:30[Asia/Kolkata]

Other Common Time Zones

Java

ZoneId.of("America/New_York");
ZoneId.of("Europe/London");
ZoneId.of("Asia/Tokyo");

#Instant (UTC Timestamp)

Instant represents a point on the UTC timeline.

Java

import java.time.Instant;

Instant instant = Instant.now();
System.out.println(instant);

Output

2026-06-15T05:00:00Z

Instant is commonly used for storing timestamps in databases, distributed systems and logging.

#Interview Questions

Q1Why was java.time introduced?

Date and Calendar were mutable.
They were not thread-safe (e.g. SimpleDateFormat).
Their API was difficult to understand (months start at 0 in Calendar, etc.).
java.time is immutable, thread-safe, and provides a cleaner API.

Q2Difference between Period and Duration?

Period	Duration
Date-based	Time-based
Years, months, days	Hours, minutes, seconds (and nanos)
`Period.between(LocalDate, LocalDate)`	`Duration.between(LocalTime / LocalDateTime / Instant, …)`

Q3Difference between LocalDateTime and ZonedDateTime?

LocalDateTime	ZonedDateTime
No time-zone information	Includes the time zone
Suitable for local applications	Suitable for global / distributed applications

Q4Difference between Date and Instant?

Date	Instant
Legacy Java API	Modern Java 8 API
Mutable	Immutable
Limited API	Rich API
Time-zone handling is cumbersome	UTC-based timestamp

#Common Spring Boot Usage

Modern JPA/Hibernate directly supports Java 8 date and time types.

Java

import jakarta.persistence.Entity;

@Entity
public class Employee {
    private LocalDate joiningDate;
    private LocalDateTime createdAt;
}

These types are preferred over java.util.Date because they are immutable, thread-safe, and integrate seamlessly with modern Java and Spring Boot applications.

#Chapter Summary

LocalDate, LocalTime, LocalDateTime — no time zone
ZonedDateTime and ZoneId
Instant — a UTC timestamp
Immutable plus…() / minus…() methods return new objects
DateTimeFormatter for formatting and parsing
Period (dates) vs Duration (times)