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.
Calendar cal = new GregorianCalendar(2026, Calendar.MARCH, 9); // months are 0-based
Try it
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.
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
SimpleDateFormatbetween threads. Concurrent use corrupts results without any exception. Create one per use, or useDateTimeFormatter. - Mutability bites. A
Datereturned from a getter can be modified by the caller, so defensive copies are needed. Alljava.timetypes are immutable. - Zones are implicit.
Date.toString(),Calendar.getInstance()andnew 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) andybehave differently around the new year, which causes "December 31 shows next year" bugs. Preferyyyy. Dateis 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()andDate.from(...), then keepjava.timeinside your code.