Java - Java Date and Time API

The Java Date and Time API was introduced in Java 8 to provide a modern and reliable way to work with dates, times, time zones, durations, and periods. It is mainly available through the java.time package. The API was designed to overcome several limitations of the older Date and Calendar classes, such as confusing methods, mutable objects, and difficulties in handling time zones. The classes in the modern API are generally immutable and thread-safe, making them suitable for both simple and complex applications.

1. LocalDate

LocalDate represents a date without a time or time zone. It is useful when only the calendar date is important, such as a birthday, examination date, joining date, or holiday.

import java.time.LocalDate;

public class Main {
    public static void main(String[] args) {
        LocalDate today = LocalDate.now();

        System.out.println("Today's date: " + today);
    }
}

The now() method obtains the current date from the system clock. A specific date can also be created using of().

LocalDate date = LocalDate.of(2026, 10, 7);

System.out.println(date);

Output:

2026-10-07

LocalDate also provides methods for accessing individual components.

LocalDate date = LocalDate.of(2026, 10, 7);

System.out.println(date.getYear());
System.out.println(date.getMonth());
System.out.println(date.getDayOfMonth());

2. LocalTime

LocalTime represents a time without a date or time zone. It is useful for situations such as store opening times, class timings, or appointment times.

import java.time.LocalTime;

public class Main {
    public static void main(String[] args) {
        LocalTime time = LocalTime.now();

        System.out.println("Current time: " + time);
    }
}

A particular time can be created with of().

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

System.out.println(time);

Output:

10:30:15

You can retrieve individual components using methods such as getHour(), getMinute(), and getSecond().

3. LocalDateTime

LocalDateTime combines both a date and a time. It does not contain information about a time zone.

import java.time.LocalDateTime;

public class Main {
    public static void main(String[] args) {
        LocalDateTime current = LocalDateTime.now();

        System.out.println(current);
    }
}

A specific date and time can be created as follows:

LocalDateTime dateTime =
        LocalDateTime.of(2026, 10, 7, 14, 30);

System.out.println(dateTime);

Output:

2026-10-07T14:30

LocalDateTime is appropriate when an application needs both date and time but does not need to associate the value with a particular geographical time zone.

4. ZonedDateTime

ZonedDateTime represents a date and time together with a specific time zone. It is particularly important for applications that operate across different countries.

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

public class Main {
    public static void main(String[] args) {
        ZonedDateTime time =
                ZonedDateTime.now(ZoneId.of("Asia/Kolkata"));

        System.out.println(time);
    }
}

For example, the same instant can be represented in different time zones.

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

ZonedDateTime londonTime =
        ZonedDateTime.now(ZoneId.of("Europe/London"));

System.out.println("India: " + indiaTime);
System.out.println("London: " + londonTime);

This feature is useful for international applications, flight booking systems, online meetings, and global business systems.

5. Instant

Instant represents a specific moment on the UTC timeline. It is useful when an application needs to record an exact point in time independently of a user's local time zone.

import java.time.Instant;

public class Main {
    public static void main(String[] args) {
        Instant current = Instant.now();

        System.out.println(current);
    }
}

Instant is commonly useful for timestamps, logging, event tracking, and storing moments in distributed systems.

6. Formatting Dates and Times

Dates and times often need to be displayed in a particular format. Java provides DateTimeFormatter for this purpose.

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class Main {
    public static void main(String[] args) {
        LocalDateTime dateTime = LocalDateTime.now();

        DateTimeFormatter formatter =
                DateTimeFormatter.ofPattern("dd-MM-yyyy HH:mm:ss");

        String formatted = dateTime.format(formatter);

        System.out.println(formatted);
    }
}

A possible output is:

07-10-2026 14:30:25

Common formatting symbols include:

dd represents the day.
MM represents the month.
yyyy represents the year.
HH represents the hour in 24-hour format.
mm represents minutes.
ss represents seconds.

Formatting is useful when displaying dates to users or generating reports.

7. Parsing Dates and Times

Parsing means converting a string into a date or time object.

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

public class Main {
    public static void main(String[] args) {
        String text = "07-10-2026";

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

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

        System.out.println(date);
    }
}

This is useful when reading dates from user input, configuration files, databases, or external systems.

8. Adding and Subtracting Dates

The Date and Time API provides methods for performing date calculations.

LocalDate date = LocalDate.of(2026, 10, 7);

LocalDate nextWeek = date.plusDays(7);

System.out.println(nextWeek);

Other useful methods include:

date.plusMonths(2);
date.plusYears(1);
date.minusDays(5);
date.minusMonths(1);
date.minusYears(2);

Because these classes are immutable, these operations do not change the original object. Instead, they return a new date or time object.

9. Period

Period represents an amount of time in terms of years, months, and days. It is mainly used with date-based calculations.

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

public class Main {
    public static void main(String[] args) {
        LocalDate start = LocalDate.of(2020, 1, 1);
        LocalDate end = LocalDate.of(2026, 1, 1);

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

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

Period is useful for calculating age, the difference between two calendar dates, or the duration of a subscription.

10. Duration

Duration represents an amount of time in terms of seconds and smaller units. It is generally used for time-based calculations.

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

public class Main {
    public static void main(String[] args) {
        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

Duration is useful when measuring elapsed time, such as how long a task takes to execute.

11. Comparing Dates and Times

Java provides methods for comparing date and time objects.

LocalDate date1 = LocalDate.of(2026, 10, 7);
LocalDate date2 = LocalDate.of(2026, 10, 10);

System.out.println(date1.isBefore(date2));
System.out.println(date1.isAfter(date2));
System.out.println(date1.isEqual(date2));

Output:

true
false
false

These methods make date comparisons easier to understand and avoid manually comparing individual year, month, and day values.

12. Handling Time Zones

Java provides the ZoneId class for working with time zones.

import java.time.ZoneId;

public class Main {
    public static void main(String[] args) {
        ZoneId zone = ZoneId.of("Asia/Kolkata");

        System.out.println(zone);
    }
}

You can obtain the list of available time-zone identifiers:

ZoneId.getAvailableZoneIds()
       .forEach(System.out::println);

Examples include:

Asia/Kolkata
Europe/London
America/New_York
Asia/Tokyo
Australia/Sydney

Using named time zones is preferable to manually adding or subtracting hours because time-zone rules can change and some regions observe daylight-saving time.

Advantages of the Java Date and Time API

The modern API provides several important advantages. Its classes are largely immutable, which makes them safer to use in multithreaded programs. The API separates different concepts such as dates, times, date-times, instants, periods, durations, and time zones instead of placing everything into one confusing class. It also provides clear methods for formatting, parsing, comparison, and date arithmetic.

Another important advantage is improved time-zone support. Applications that operate internationally can use ZoneId and ZonedDateTime rather than relying on manual time calculations. The API also uses descriptive method names such as plusDays(), minusMonths(), isBefore(), and isAfter(), making Java date-related code easier to read and maintain.

Conclusion

The Java Date and Time API provides a comprehensive way to handle dates and times in Java applications. Important classes include LocalDate, LocalTime, LocalDateTime, ZonedDateTime, Instant, Period, Duration, ZoneId, and DateTimeFormatter. By using these classes appropriately, developers can perform date calculations, format and parse dates, compare dates, handle time zones, and measure elapsed time in a reliable and readable manner.