Date & Time API

The Date & Time API was introduced in Java 8 to replace the old java.util.Date and Calendar classes, which were complex, error-prone, and not thread-safe.

The new API is part of the package:

java.time

👉 It is modern, clean, and much easier to use for handling date and time in Java applications.

Why New Date & Time API?

Old Java date classes had several problems:

• Confusing design that was hard to understand
• Mutable objects, meaning values could change unexpectedly
• Poor handling of time zones and formatting
• Difficult and error-prone date calculations

Java 8 solved these issues with a simple, powerful, and immutable API that makes date and time handling much easier and safer.

Main Classes in Date & Time API

Java 8 provides different classes in the java.time package to handle date and time in a simple and efficient way.

1. LocalDate (Only Date)

Used to represent a date without time (year, month, day).

import java.time.LocalDate;

LocalDate date = LocalDate.now();

System.out.println(date);

Example output:

2026-04-18

👉 This example prints the current system date.

2. LocalTime (Only Time)

Used to represent time without date (hours, minutes, seconds).

import java.time.LocalTime;

LocalTime time = LocalTime.now();

System.out.println(time);

👉 This example prints the current system time.

3. LocalDateTime (Date + Time)

Used to represent both date and time together.

import java.time.LocalDateTime;

LocalDateTime dateTime = LocalDateTime.now();

System.out.println(dateTime);

👉 This example prints the current date and time together.

4. ZonedDateTime (Date + Time + Time Zone)

Used to handle date and time with time zone information.

import java.time.ZonedDateTime;

ZonedDateTime zonedDateTime = ZonedDateTime.now();

System.out.println(zonedDateTime);

👉 This example shows the current date, time, and system time zone.

5. Instant (Machine Timestamp)

Represents a point in time (timestamp), mainly used in logging and backend systems.

import java.time.Instant;

Instant instant = Instant.now();

System.out.println(instant);

👉 This example prints the current timestamp in UTC format.

6. Working with Specific Date

Used to create a custom date manually.

LocalDate date = LocalDate.of(2026, 4, 18);

System.out.println(date);

👉 This example creates and prints a specific date.

7. Working with Specific Time

Used to create a custom time manually.

LocalTime time = LocalTime.of(10, 30);

System.out.println(time);

👉 This example creates and prints a specific time.

Date Manipulation

Java Date & Time API allows you to easily modify dates using built-in methods like adding or subtracting days, months, and years.

1. Adding Days

Used to move forward in time by a specific number of days.

LocalDate date = LocalDate.now();

System.out.println(date.plusDays(5));

👉 This example adds 5 days to the current date and prints the new date.

2. Subtracting Days

Used to move backward in time by a specific number of days.

LocalDate date = LocalDate.now();

System.out.println(date.minusDays(3));

👉 This example subtracts 3 days from the current date and prints the result.

3. Adding Months / Years

Used to change date by months or years easily.

LocalDate date = LocalDate.now();

System.out.println(date.plusMonths(2));
System.out.println(date.plusYears(1));

👉 This example:

• Adds 2 months to current date
• Adds 1 year to current date

Comparing Dates

Java provides simple methods to compare two dates in the Date & Time API.

1. isBefore()

Used to check whether one date comes before another date.

LocalDate d1 = LocalDate.of(2026, 4, 10);
LocalDate d2 = LocalDate.of(2026, 4, 18);

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

👉 This example checks if d1 is before d2.

• Returns true if first date is earlier
• Returns false if not

2. isAfter()

Used to check whether one date comes after another date.

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

👉 This example checks if d2 is after d1.

• Returns true if first date is later
• Returns false if not

3. isEqual()

Used to check whether two dates are exactly the same.

System.out.println(d1.isEqual(d2));

👉 This example compares both dates for equality.

• Returns true if both dates are same
• Returns false if different

Formatting Dates

Java provides DateTimeFormatter to convert date into a readable and custom format.

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

LocalDate date = LocalDate.now();

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

System.out.println(date.format(format));

👉 This example converts the current date into custom format (dd-MM-yyyy).

• Helps in converting date into readable format.
• Used for displaying date in required pattern.

Common Format Patterns

Java provides different patterns to format dates in various styles:

Zoned Date & Time (Time Zones)

ZonedDateTime is used to handle date and time with different time zones. It helps you work with global applications where users are in different locations.

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

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

System.out.println(zdt);

👉 This example shows the current date and time for Asia/Kolkata time zone.

• Used for handling global time zones
• Helps in international applications

Duration (Time Difference)

Duration is used to calculate the difference between two time values (like hours, minutes, seconds).

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

LocalTime t1 = LocalTime.of(10, 0);
LocalTime t2 = LocalTime.of(12, 30);

Duration duration = Duration.between(t1, t2);

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

👉 This example calculates the difference between two times in hours.

• Used for calculating time gaps or intervals
• Works with time-based values like hours and minutes

Period (Date Difference)

Period is used to calculate the difference between two dates (years, months, days).

importjava.time.LocalDate;
importjava.time.Period;

LocalDated1=LocalDate.of(2020,1,1);
LocalDated2=LocalDate.of(2026,4,18);

Periodperiod=Period.between(d1,d2);

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

👉 This example calculates the difference in years between two dates.

• Used for date-based calculations (years, months, days)
• Helps in finding age, duration, etc.

Advantages of Date & Time API

• Easy to use and understand.
• Immutable (values cannot be changed → safer).
• Thread-safe (works well in multi-threaded applications).
• Better performance compared to old Date/Calendar API.
• Clean and readable code structure.
• Strong and flexible time zone support.

Old Date API vs New Date API

Java provides a clear difference between the old Date/Calendar API and the new Java 8 Date & Time API (java.time).

Real-World Use Cases

Java Date & Time API is widely used in real-world applications where accurate date and time handling is important.

• Logging timestamps → Recording when events happen in applications.
• Booking systems → Hotel, flight, and ticket reservations.
• Financial applications → Handling transactions and interest calculations.
• Scheduling apps → Managing meetings, reminders, and calendars.
• APIs and backend systems → Storing and processing time-based data.

Conclusion

The Java Date & Time API (java.time) is a modern, powerful, and clean way to handle dates and times in Java.

It helps developers:

• Avoid common date-related errors.
• Write clean and readable code.
• Handle time zones easily and accurately.
• Perform date calculations efficiently.