11.12.2023 –
Java’s legacy date and time API, which includes classes such as „java.util.Date“, „java.util.Calendar“, has been replaced by the newer „java.time“ package introduced in Java 8. The legacy classes have several issues, like properly dealing with timezones. The newer API is more comprehensive, easier to use, and less error-prone.
The following table helps to get an overview of the legacy type, the matching equivalent of the new date API and which time information is stored within the datatype.
| Feature |
| Date |
Time |
Millis |
TZ |
| ❌ |
✅ |
✅ |
❌ |
|
| Data Type |
| Legacy |
Modern |
| – |
java.time.LocalTime |
|
| Example |
|
| Feature |
| Date |
Time |
Millis |
TZ |
| ✅ |
❌ |
❌ |
❌ |
|
| Data Type |
| Legacy |
Modern |
java.sql.Date
|
java.time.LocalDate |
|
| Example |
|
| Feature |
| Date |
Time |
Millis |
TZ |
| ✅ |
✅ |
✅ |
❌ |
|
| Data Type |
| Legacy |
Modern |
| – |
java.time.LocalDateTime |
|
| Example |
|
| Feature |
| Date |
Time |
Millis |
TZ |
| ✅ |
✅ |
✅ |
✅ UTC |
|
| Data Type |
| Legacy |
Modern |
java.util.Date
java.util.Timestamp |
java.time.Instant |
|
| Example |
| 2021-12-07 10:00:00.000 UTC |
|
| Feature |
| Date |
Time |
Millis |
TZ |
| ✅ |
✅ |
✅ |
✅ Offset |
|
| Data Type |
| Legacy |
Modern |
| – |
java.time.OffsetDateTime |
|
| Example |
| 2021-12-07 10:00:00.000 +01:00 |
|
| Feature |
| Date |
Time |
Millis |
TZ |
| ❌ |
✅ |
✅ |
✅ Offset |
|
| Data Type |
| Legacy |
Modern |
| – |
java.time.OffsetTime |
|
| Example |
|
| Feature |
| Date |
Time |
Millis |
TZ |
| ✅ |
✅ |
✅ |
✅ Region |
|
| Data Type |
| Legacy |
Modern |
java.util.GregorianCalendar
java.util.XMLGregorianCalendar |
java.time.ZonedDateTime |
|
| Example |
| 2021-12-07 10:00:00.000 Europe/Berlin |
|
| Feature |
⏰ NOW
| Date |
Time |
Millis |
TZ |
| ✅ |
✅ |
✅ |
✅ Region |
|
| Data Type |
| Legacy |
Modern |
| – |
java.time.Clock
java.time.Instant.now() |
|
| Example |
| ⏰ 2021-12-07 10:00:00.000 Europe/Berlin |
|
Image Credits: all graphics are own illustrations
| Interested in more articles about „Dealing with timezones“? Here are all the posts:
|
