Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Date and Time

Date, Calendar and SimpleDateFormat

Reference for the legacy java.util.Date, Calendar and SimpleDateFormat classes: what they do, their pitfalls, and how to migrate to java.time safely.

Before Java 8 introduced java.time, dates were handled by three classes from java.util and java.text: Date, Calendar and SimpleDateFormat. They still appear in older code, libraries and database drivers, so you need to be able to read and migrate them, but you should not use them in new code.

java.util.Date is really an instant: a count of milliseconds since 1970-01-01T00:00:00Z, wrapped in a mutable object. Calendar (usually a GregorianCalendar) adds field-based access and arithmetic. SimpleDateFormat formats and parses text. Their well-known problems are mutability, thread-unsafety, zero-based months, two-digit year quirks and silent lenient parsing.

Java
Calendar cal = new GregorianCalendar(2026, Calendar.MARCH, 9);   // months are 0-based

Try it

Java Calendar, zero-based months and lenient parsing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java The same tasks with java.time

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Class Role Notes
java.util.Date An instant in milliseconds since the epoch Mutable; most constructors and getters (getYear(), getMonth()) are deprecated. Its toString() uses the default zone.
java.util.Calendar / GregorianCalendar Field-based date arithmetic Mutable; MONTH is 0-based, DAY_OF_WEEK starts at Sunday = 1, add and roll differ.
java.util.TimeZone A zone for a calendar or formatter Replaced by ZoneId.
java.text.SimpleDateFormat Pattern-based formatting and parsing Not thread-safe; lenient by default; setLenient(false) makes it strict.
java.sql.Date, Time, Timestamp JDBC subclasses Map to LocalDate, LocalTime, LocalDateTime via toLocalDate() and similar.

Usage notes

  • Do not share a SimpleDateFormat between threads. Concurrent use corrupts results without any exception. Create one per use, or use DateTimeFormatter.
  • Mutability bites. A Date returned from a getter can be modified by the caller, so defensive copies are needed. All java.time types are immutable.
  • Zones are implicit. Date.toString(), Calendar.getInstance() and new SimpleDateFormat(...) all use the JVM's default time zone, so the same code prints different text on different machines. Set the zone explicitly.
  • Pattern letters differ slightly. In SimpleDateFormat, Y (week-based year) and y behave differently around the new year, which causes "December 31 shows next year" bugs. Prefer yyyy.
  • Date is not a date. It has a time of day and no zone. Converting it to a calendar date needs a zone (see converting legacy and modern types).
  • Still necessary for old APIs: JDBC drivers before JDBC 4.2, some XML and serialization libraries, and a few Swing components.
  • Migration recipe: convert at the boundary with toInstant() and Date.from(...), then keep java.time inside your code.