Date and Time API
IntermediateJava 8's java.time package provides an immutable, thread-safe date and time API that replaces the error-prone legacy Date and Calendar classes.
Overview
The java.time package (JSR-310, Java 8+) introduces clean, immutable value types for dates, times, durations, and periods. Core types: LocalDate (date without time/zone), LocalTime (time without date/zone), LocalDateTime (date + time), ZonedDateTime (date + time + zone), Instant (Unix timestamp), Duration (time-based amount), Period (date-based amount). DateTimeFormatter handles parsing and formatting.
Core Date-Time Types
All java.time types are immutable and thread-safe. Creation via static factory methods (now(), of(), parse()). Arithmetic via plus/minus methods that return new instances.
Choose the right type: LocalDate for birthdays, LocalDateTime for meeting times without timezone context, ZonedDateTime or Instant for events that span timezones.
import java.time.*;
// Current values
LocalDate today = LocalDate.now();
LocalTime now = LocalTime.now();
LocalDateTime ldt = LocalDateTime.now();
Instant instant = Instant.now(); // Unix epoch millis
// Specific values
LocalDate dob = LocalDate.of(1990, Month.JUNE, 15);
LocalTime noon = LocalTime.of(12, 0);
ZonedDateTime zdt = ZonedDateTime.now(ZoneId.of("America/New_York"));
// Arithmetic — returns new instances (immutable)
LocalDate nextWeek = today.plusDays(7);
LocalDate lastMonth = today.minusMonths(1);
LocalDate nextYear = today.plusYears(1);
// Comparisons
boolean isBefore = dob.isBefore(today);
long daysOld = ChronoUnit.DAYS.between(dob, today);DateTimeFormatter
DateTimeFormatter is the thread-safe replacement for SimpleDateFormat. Use predefined constants (ISO_LOCAL_DATE) or build patterns with ofPattern().
Format with format(); parse with parse() or LocalDate.parse(str, formatter).
import java.time.format.DateTimeFormatter;
LocalDate date = LocalDate.of(2025, 6, 15);
// Predefined formatters
String iso = date.format(DateTimeFormatter.ISO_LOCAL_DATE);
// "2025-06-15"
// Custom pattern
DateTimeFormatter fmt =
DateTimeFormatter.ofPattern("dd MMM yyyy");
String pretty = date.format(fmt); // "15 Jun 2025"
// Parsing
LocalDate parsed = LocalDate.parse("15 Jun 2025", fmt);
// With locale
DateTimeFormatter localFmt = DateTimeFormatter
.ofPattern("MMMM dd, yyyy", Locale.US);
String us = date.format(localFmt); // "June 15, 2025"Duration, Period, and Timezones
Period is date-based (years, months, days). Duration is time-based (hours, minutes, seconds, nanos). Use ChronoUnit for precise unit-based calculations.
ZoneId and ZoneOffset handle timezones. Converting between Instant and ZonedDateTime requires a zone.
// Period — date-based
Period p = Period.between(
LocalDate.of(2020, 1, 1),
LocalDate.of(2025, 6, 15));
System.out.println(p.getYears()); // 5
// Duration — time-based
Duration d = Duration.between(
LocalTime.of(9, 0), LocalTime.of(17, 30));
System.out.println(d.toHours()); // 8
System.out.println(d.toMinutes()); // 510
// Timezone conversion
ZonedDateTime nyTime = ZonedDateTime.now(ZoneId.of("America/New_York"));
ZonedDateTime londonTime = nyTime.withZoneSameInstant(
ZoneId.of("Europe/London"));
// Instant ↔ ZonedDateTime
Instant inst = Instant.now();
ZonedDateTime zdt = inst.atZone(ZoneId.systemDefault());
Instant back = zdt.toInstant();Key Points to Remember
- All java.time types are immutable and thread-safe — use them instead of Date/Calendar.
- LocalDate for dates, LocalTime for times, LocalDateTime for both, ZonedDateTime for timezone-aware.
- DateTimeFormatter is thread-safe; SimpleDateFormat is not.
- Period is date-based (Y/M/D); Duration is time-based (H/M/S/nanos).
- Use Instant for machine timestamps; use ZonedDateTime for human-readable timezone events.
Practice Date and Time API in the Playground
Run and modify code directly in your browser - no setup needed.
Interview Questions
Sign in to ask AriaWhy was the old java.util.Date API replaced, and what problems did it have?
What is the difference between LocalDateTime and ZonedDateTime?
Why is SimpleDateFormat not thread-safe but DateTimeFormatter is?
What is the difference between Period and Duration?
How would you calculate the number of working days between two dates?
Ask Aria about Date and Time API
Your personal AI tutor — ask anything about this concept