Skip to main content

Date and Calendar

Before the introduction of the modern java.time package in Java 8, developers primarily relied on the java.util.Date and java.util.Calendar classes to handle dates and times.

While these classes are now considered legacy and should generally be avoided in new development in favor of the java.time API (like LocalDate and LocalDateTime), you will undoubtedly encounter them in older codebases.

1. The Date Class​

The java.util.Date class represents a specific instant in time, with millisecond precision. Despite its name, it actually represents both a date and a time.

import java.util.Date;

public class LabDate1 {

  public static void main(String args[]) {
    // Calling the default constructor creates a Date object initialized
    // with the current date and time of the system.
    Date now = new Date();

    System.out.println("Current Date and Time: " + now.toString());

    // Getting the time in milliseconds since the UNIX epoch (Jan 1, 1970)
    long epochTime = now.getTime();
    System.out.println("Milliseconds since Epoch: " + epochTime);
  }
}

Why is Date deprecated?​

Most of the constructors and methods (like getYear(), getMonth(), getDate()) in the Date class have been deprecated since Java 1.1 because they were poorly designed and didn't handle internationalization well. To manipulate dates (like adding days or months), Java introduced the Calendar class.

2. The Calendar Class​

The java.util.Calendar class is an abstract class that provides methods for converting between a specific instant in time and a set of calendar fields such as YEAR, MONTH, DAY_OF_MONTH, HOUR, etc.

Because it is abstract, you cannot instantiate it directly with new Calendar(). Instead, you use the static factory method Calendar.getInstance(), which returns a calendar initialized with the current date and time in the default time zone and locale.

import java.util.Calendar;

public class LabDate2 {

  public static void main(String args[]) {
    // Getting a Calendar instance
    Calendar calendar = Calendar.getInstance();

    // Extracting specific fields
    int year = calendar.get(Calendar.YEAR);

    // NOTE: Months in the Calendar class are 0-indexed! (January is 0, December is 11)
    int month = calendar.get(Calendar.MONTH) + 1;

    int day = calendar.get(Calendar.DAY_OF_MONTH);

    System.out.println("Current Date: " + year + "-" + month + "-" + day);

    // Manipulating the calendar (Adding 10 days)
    calendar.add(Calendar.DAY_OF_MONTH, 10);
    System.out.println("Date after 10 days: " + calendar.getTime());
  }
}

Transitioning to Java 8 Time API​

Due to the mutability issues, confusing 0-indexed months, and lack of thread-safety in Date and Calendar, Java 8 introduced a completely new Date and Time API located in the java.time package.

If you are writing new code, you should almost always use classes like LocalDate, LocalTime, and LocalDateTime instead of java.util.Date!

import java.time.LocalDate;
import java.time.LocalDateTime;

public class LabDate3 {

  public static void main(String args[]) {
    // Modern Java 8 approach!
    LocalDate today = LocalDate.now();
    LocalDateTime now = LocalDateTime.now();

    System.out.println("Modern Date: " + today);
    System.out.println("Modern Date/Time: " + now);

    // Adding days is much more intuitive
    LocalDate future = today.plusDays(10);
    System.out.println("10 days later: " + future);
  }
}