Date & Time API

Why java.time?

15 min Lesson 1 of 13

Why java.time?

Java had date and time support from its very first release in 1995, and that original design aged poorly. By the time you reach this lesson you have already worked with lambdas, streams, and generics — so you know what clean, well-designed Java looks like. The old java.util.Date and java.util.Calendar classes are a textbook example of the opposite. Understanding why they were bad, and exactly what java.time fixes, will help you use the new API intentionally rather than by rote.

The Problems with java.util.Date

java.util.Date was introduced in JDK 1.0 and carries decades of baggage. Its core flaws:

Mutability. A Date object can be changed after construction. Anyone holding a reference can call setTime() and silently alter the value. This makes defensive programming necessary whenever you pass dates across method or thread boundaries.
Misleading name. Despite being called Date, it actually represents an instant in time (a millisecond offset from the Unix epoch). It does not model a calendar date. There is no separate type for a local date, a local time, or a time-zone-aware timestamp.
Month indexing. Months were zero-based: January = 0, December = 11. This caused off-by-one bugs in virtually every application that used the class.
Deprecated methods. Most of Date's own methods — getYear(), getMonth(), getDay() — were deprecated as early as Java 1.1 because they did not handle time zones correctly. The class delegated to Calendar but kept the broken API around.

// The old way — riddled with traps
import java.util.Date;

Date d = new Date(2024 - 1900, 0, 15); // year offset from 1900, month 0 = January
System.out.println(d); // prints a long locale-sensitive string; hard to reason about

// Mutability trap
Date start = new Date();
Date copy = start;       // still the SAME object — not a defensive copy
copy.setTime(0);         // start is now the epoch — surprise!
System.out.println(start.getTime()); // 0

Calendar Did Not Fix It

java.util.Calendar, added in Java 1.1, was intended to replace Date for calendar arithmetic. It failed on several fronts:

Still mutable. Calendar objects carry the same thread-safety problems as Date.
Verbose and error-prone API. Every operation goes through integer constants (Calendar.MONTH, Calendar.DAY_OF_WEEK), which are not type-safe and easy to misuse.
Mixed concerns. A single Calendar instance bundles a point in time, a time zone, and a locale all together, making it difficult to reason about what it represents at any given moment.
Month still zero-based. The constant Calendar.JANUARY has value 0.
Poor formatting. You had to reach for SimpleDateFormat, which is itself not thread-safe.

import java.util.Calendar;

Calendar cal = Calendar.getInstance();
cal.set(Calendar.YEAR, 2024);
cal.set(Calendar.MONTH, Calendar.JANUARY); // value 0 — easy to forget and write 1 instead
cal.set(Calendar.DAY_OF_MONTH, 15);

// Want to add 3 months?
cal.add(Calendar.MONTH, 3); // works, but verbose

// SimpleDateFormat is NOT thread-safe — sharing one instance across threads corrupts output
// java.text.SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");

SimpleDateFormat and threads. A common production bug: developers create one SimpleDateFormat as a static field to avoid repeated construction and then call it from multiple threads. Because SimpleDateFormat stores parsing state internally, concurrent access produces wrong dates or throws exceptions. The fix was typically a ThreadLocal — a workaround for a design flaw.

The Third-Party Stopgap: Joda-Time

The community eventually rallied around the open-source Joda-Time library, created by Stephen Colebourne. Joda-Time proved that date-time handling could be done well in Java: immutable value types, a clean separation of concepts (local date vs. instant vs. duration), and a fluent API. It became the de facto standard for serious Java applications from roughly 2005 onward.

Joda-Time was so successful that its design directly inspired JSR-310, the Java Specification Request that became java.time in Java 8. Stephen Colebourne himself led both efforts.

JSR-310 insight. Because java.time is essentially Joda-Time reimagined for the JDK, the two APIs look very similar. If you have ever read old code using Joda-Time, the concepts map almost one-to-one. The main difference is that java.time is in the standard library and benefits from tighter integration with the rest of Java.

What java.time Gets Right

The java.time package (and its sub-packages java.time.format, java.time.temporal, java.time.zone) was designed from first principles to address every failing of Date and Calendar:

Immutability. Every core type — LocalDate, LocalTime, LocalDateTime, ZonedDateTime, Instant — is immutable and thread-safe. Modifier methods (e.g., plusDays(), withYear()) return a new object; the original is never touched.
Clear separation of concepts. The API gives each concept its own type: a calendar date without time (LocalDate), a time without a date (LocalTime), a machine-oriented timestamp (Instant), a duration between instants (Duration), a calendar-based period (Period), and a full zoned date-time (ZonedDateTime). You pick the narrowest type that fits your need.
Human-friendly month constants. Months are represented by the Month enum: Month.JANUARY through Month.DECEMBER. No more zero-based confusion.
Thread-safe formatting. DateTimeFormatter is immutable and thread-safe. Define one instance as a constant and share it freely.
Fluent, readable API. Operations read like English: date.plusWeeks(2).withDayOfMonth(1). Method names are consistent across all types.
ISO-8601 by default. Parsing and formatting default to the ISO standard, so LocalDate.parse("2024-01-15") just works.

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

// Immutable — no accidental mutation
LocalDate today = LocalDate.now();
LocalDate nextMonth = today.plusMonths(1); // new object; today is unchanged

// Month enum — readable and type-safe
LocalDate conference = LocalDate.of(2024, Month.SEPTEMBER, 10);

// Expressive chaining
LocalDate firstOfNextMonth = today.plusMonths(1).withDayOfMonth(1);

System.out.println(today);            // 2024-01-15
System.out.println(firstOfNextMonth); // 2024-02-01

The Design Philosophy: Value-Based Classes

java.time types are value-based. That means you should compare them with .equals() (or the dedicated comparison methods like isBefore()/isAfter()), never with ==. Identity comparison on value-based classes is meaningless — two LocalDate objects representing the same date are equal even if they are distinct instances. This is the same contract used by String and boxed types like Integer.

import java.time.LocalDate;

LocalDate a = LocalDate.of(2024, 1, 15);
LocalDate b = LocalDate.of(2024, 1, 15);

System.out.println(a == b);      // false  — different instances (do NOT rely on this)
System.out.println(a.equals(b)); // true   — same calendar date
System.out.println(a.isEqual(b));// true   — chronology-aware equality (prefer for dates)

Prefer isEqual(), isBefore(), isAfter(). These methods are more expressive than compareTo() and communicate intent clearly. Use equals() for standard equality checks (e.g., in collections) and the named comparison methods everywhere else.

Summary

java.util.Date and java.util.Calendar were mutable, confusingly named, zero-indexed for months, and carried thread-safety hazards. Joda-Time proved a better design was possible, and java.time (Java 8, JSR-310) adopted that design as the standard library. The result is an API built around immutability, a clear taxonomy of date-time concepts, type-safe month constants, thread-safe formatting, and a fluent method chain. Every remaining lesson in this tutorial builds on these foundations.