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 application development. Java provides powerful tools for this purpose. For a long time, the main class was java.util.Date, but it had serious drawbacks: mutability, confusion with months (starting from 0), and lack of time zone support. With the release of Java 8, the situation changed dramatically — a new Date/Time API (package java.time) appeared, which is thread-safe, immutable, and intuitive. In this article, we will cover both approaches, but the main focus will be on the modern API.

1. Legacy API: Date and Calendar

Although using old classes in new code is not recommended, you may encounter them in legacy projects. Let's look at the main points.

Date Class

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

import java.util.Date;

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

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

        // Comparing dates        Date earlier = new Date(0);        boolean isBefore = earlier.before(now); // true        System.out.println("Is earlier? " + isBefore);    }}

Calendar Class

java.util.Calendar is a more flexible but cumbersome tool. It allows manipulating date fields.

import java.util.Calendar;

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

        // Adding 2 weeks        cal.add(Calendar.WEEK_OF_YEAR, 2);        System.out.println("In 2 weeks: " + cal.getTime());

        // Getting individual fields        int dayOfMonth = cal.get(Calendar.DAY_OF_MONTH);        int month = cal.get(Calendar.MONTH) + 1; // +1, since January = 0        System.out.println("Day: " + dayOfMonth + ", Month: " + month);    }}

Drawbacks: mutability (the add method modifies the original object), complexity of formatting, confusion with time zones.

2. Modern Date/Time API (Java 8+)

The java.time package includes key classes: LocalDate, LocalTime, LocalDateTime, ZonedDateTime, Instant, and others. All of them are immutable and thread-safe.

LocalDate — Working with Date

Stores a date without time and time zone (year, month, day).

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 newYear = LocalDate.of(2025, Month.JANUARY, 1);        System.out.println("New Year: " + newYear);

        // Date arithmetic        LocalDate nextWeek = today.plusWeeks(1);        LocalDate lastMonth = today.minusMonths(1);        System.out.println("Next week: " + nextWeek);        System.out.println("Last month: " + lastMonth);

        // Comparison        boolean isAfter = today.isAfter(newYear); // false        System.out.println("Is today after New Year? " + isAfter);    }}

LocalTime — Working with Time

Stores time (hour