Legacy Date-Time Code
Prior to the Java SE 8 release, the Java date and time mechanism was provided by the java.util.Date, java.util.Calendar, and java.util.TimeZone classes, as well as their subclasses, such as java.util.GregorianCalendar. These classes had several drawbacks, including:
Calendarclass was not type safe.
Because the classes were mutable, they could not be used in multithreaded applications.
Bugs in application code were common due to the unusual numbering of months and the lack of type safety.
Perhaps you have legacy code that uses the
java\.util date and time classes and you would like to take advantage of the
java\.time functionality with minimal changes to your code.
Added to the JDK 8 release are several methods that allow conversion between
Calendar.toInstant() converts the
Calendarobject to an
GregorianCalendar.toZonedDateTime() converts a
GregorianCalendarinstance to a
GregorianCalendar.from(ZonedDateTime) creates a
GregorianCalendarobject using the default locale from a
Date.from(Instant) creates a
Dateobject from an
Date.toInstant() converts a
Dateobject to an
TimeZone.toZoneId() converts a
TimeZoneobject to a
The following example converts a
Calendar instance to a
ZonedDateTime instance. Note that a time zone must be supplied to convert from an
Instant to a
Calendar now = Calendar.getInstance(); ZonedDateTime zdt = ZonedDateTime.ofInstant(now.toInstant(), ZoneId.systemDefault()));
The following example shows conversion between a
Date and an
Instant inst = date.toInstant(); Date newDate = Date.from(inst);
The following example converts from a
GregorianCalendar to a
ZonedDateTime , and then from a
ZonedDateTime to a
GregorianCalendar . Other temporal-based classes are created using the
GregorianCalendar cal = ...; TimeZone tz = cal.getTimeZone(); int tzoffset = cal.get(Calendar.ZONE_OFFSET); ZonedDateTime zdt = cal.toZonedDateTime(); GregorianCalendar newCal = GregorianCalendar.from(zdt); LocalDateTime ldt = zdt.toLocalDateTime(); LocalDate date = zdt.toLocalDate(); LocalTime time = zdt.toLocalTime();
Because the Java implementation of date and time has been completely redesigned in the Java SE 8 release, you cannot swap one method for another method. If you want to use the rich functionality offered by the
java\.time package, your easiest solution is to use the
toZonedDateTime methods listed in the previous section. However, if you do not want to use that approach or it is not sufficient for your needs, then you must rewrite your date-time code.
The table introduced on the Overview page is a good place to begin evaluating which
java\.time classes meet your needs.
There is no one-to-one mapping correspondence between the two APIs, but the following table gives you a general idea of which functionality in the
java\.util date and time classes maps to the
|java.util Functionality||java.time Functionality||Comments|
- Represents an instantaneous point of time on the timeline (UTC)
- Holds a time independent of a time zone
- Is represented as epoch-seconds (since 1970-01-01T00:00:00Z) plus nanoseconds
Human time representation is as follows:
|Code that sets the date to 1970-01-01 in a |
|Code that sets the time to 00:00 in a |
java\.time\.format\.DateTimeFormatter provides a powerful mechanism for formatting date and time values, you can also use the
java\.time temporal-based classes directly with
String\.format , using the same pattern-based formatting that you use with the
java\.util date and time classes.