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:

Pattern	Example
dd-MM-yyyy	18-04-2026
yyyy-MM-dd	2026-04-18
dd MMM yyyy	18 Apr 2026

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).

Feature	Old API	New API
Design	Complex and confusing	Simple and clean
Thread Safety	Not thread-safe	Thread-safe
Time Zone Support	Poor and limited	Strong and flexible
Readability	Low and hard to understand	High and easy to read

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.