Working with Dates and Time in Java: A Complete Guide

Introduction to working with dates and time in Java

Working with dates and time is one of the most common tasks in development. Whether it's event logging, deadline calculation, data filtering, or calendar display — you cannot do without a confident grasp of time APIs. In Java, the java.util.Date and java.util.Calendar classes were used for a long time, but they had many drawbacks: mutability, non-intuitive API, thread-safety issues.

Starting with Java 8, a new package java.time was added to the language, based on the ISO-8601 standard. It offers immutable and thread-safe classes that are much more convenient to use. In this article, we will cover both old and new approaches, and also show practical code examples.

1. Legacy classes: Date and Calendar

Despite the fact that using Date and Calendar is not recommended in new projects, you may encounter them in legacy code. Let's look at the main points.

Class java.util.Date

The Date class represents a specific moment in time with millisecond precision. It has many deprecated methods.

import java.util.Date;

public class DateExample {    public static void main(String[] args) {        // Current date and time        Date now = new Date();        System.out.println("Current time: " + now);

        // Constructor with milliseconds (since January 1, 1970)        Date specificDate = new Date(1000000000000L);        System.out.println("Date: " + specificDate);

        // Comparing dates        boolean after = now.after(specificDate);        System.out.println("now after specificDate? " + after);    }}

Class java.util.Calendar

Calendar is a more flexible, but still inconvenient class for date manipulation.

import java.util.Calendar;

public class CalendarExample {    public static void main(String[] args) {        Calendar cal = Calendar.getInstance();        // Setting a specific date        cal.set(2025, Calendar.MARCH, 15, 10, 30, 0);        System.out.println("Set date: " + cal.getTime());

        // Getting individual fields        int year = cal.get(Calendar.YEAR);        int month = cal.get(Calendar.MONTH) + 1; // Months are 0-based        int day = cal.get(Calendar.DAY_OF_MONTH);        System.out.println("Year: " + year + ", Month: " + month + ", Day: " + day);

        // Adding days        cal.add(Calendar.DAY_OF_MONTH, 10);        System.out.println("In 10 days: " + cal.getTime());    }}

Drawbacks: mutability (methods modify the object itself), complexity of working with time zones, confusion with month indices.

2. Modern API: java.time (Java 8+)

The java.time package solves all the problems of the old classes. Main classes:

• LocalDate — date without time (year, month, day);
• LocalTime — time without date (hours, minutes, seconds, nanoseconds);
• LocalDateTime — date and time without time zone;
• ZonedDateTime — date and time with time zone;
• Instant — moment in time in UTC;
• Duration and Period — for working with time intervals.

LocalDate — working with dates

import java.time.LocalDate;import java.time.Month;

public class LocalDateExample {    public static void main(String[] args) {        // Current date        LocalDate today = LocalDate.now();        System.out.println("Today: " + today);

        // Specific date        LocalDate specific = LocalDate.of(2025, Month.DECEMBER, 25);        System.out.println("Christmas: " + specific);

        // Adding days        LocalDate nextWeek = to