ThreeTen, the reference implementation of JSR 310 Date and Time API, is now included in JDK 8 Early Access b75. The Java Time API for JDK 8 is under the package java.time, moving away from the javax.time package of earlier implementations. The Java Time Javadoc draft is also available.
All the Java Time classes are immutable and thread-safe. They are based on the ISO 8601 calendar system, the de facto world calendar following the proleptic Gregorian rules. Support for other calendar systems are provided in the java.time.calendar and java.time.temporal packages. Besides classes for dates and times, the API also has classes for clocks, periods and durations, and enums for month and day-of-week.
There are a lot of classes in the Java Time API, but most applications can start with these date/time types.
- Instant
- A numeric timestamp, stored with nanosecond resolution. Useful for capturing a point in time, similar to System.currentTimeMillis(). Instant is the closest equivalent class to java.util.Date. The instant when printed looks like '2000-12-01T12:30:00.000Z'.
- LocalDate
- A date without a time, offset or time zone. Useful for storing a birthday for example. The date when printed looks like '2000-12-01'
- LocalTime
- A time without a date, offset or time zone. Useful for storing store hours for example. The time when printed looks like '12:30:00.000'.
- LocalDateTime
- A date and time without the offset or time zone. The date and time when printed looks like '2000-12-01T12:30:00.000'.
- ZonedDateTime
- A date and time with offset and time zone. Useful for performing calculations that takes into account the time zone like 'America/New_York'. ZonedDateTime is the closest equivalent class to java.util.GregorianCalendar. The date and time when printed looks like '2000-12-01T12:30:00.000-05:00[America/New_York]'
It is recommended whenever possible, to use a simpler classes without a time zone to model the domain, like LocalDate, LocalTime and LocalDateTime. The widespread use of time zones tends to add considerable complexity to an application. Many applications can use the simpler classes, with the time zone added only at the user interface layer.
Other notable classes in the Java Time API are:
- Clock
- A clock providing access to the current instant, date and time using a time zone. A clock can be used instead of System.currentTimeMillis() and TimeZone.getDefault(). Although all key date and time classes have a now() factory method that uses the system clock, the primary purpose of this abstraction is to allow alternate clocks to be injected, which can greatly simplify testing.
- Duration
- A duration between two instants on the time-line, stored with nanosecond resolution. This class models a duration of time and is not tied to any instant. The model is directed, meaning that the duration can be negative. The duration when printed looks like 'PT3600S'.
- Period
- A period of time expressed in units meaningful to humans, such as '1 Year, 2 Months and 3 Days'. The model is directed, meaning that individual parts of the period may be negative. The period when printed looks like 'P1Y2M3D'.
- ZoneId
- A time zone ID, such as America/New_York.
- ZoneOffset
- A time zone offset from Greenwich/UTC, such as +02:00.
The java.time.zone package provides support for time zones, their rules and the resulting gaps and overlaps in the local time-line typically caused by Daylight Saving Time. There is also the java.time.format package for printing and parsing date-time objects, although in most cases, the date and time classes' toString() and parse() methods should be sufficient. The java.time.temporal package provides access to date and time using fields and units, additional value type classes for the most important sub-parts of a date, and base support for calendar systems other than the default ISO. This package provides additional functionality for more advanced use cases.
Users who wish to try the new JDK 8 Time API can download JDK 8 b75, using the Javadoc as a guide. Users who would like to use an IDE with JDK 8 support can use the latest IntelliJ IDEA or Netbeans IDEs. Those looking for third party tutorials should make sure they are looking at recent articles as the API have had a lot of changes in the past few years. Also note that changes to the Java Time API classes and methods are expected to continue until JDK 8 is released. Developers interested in knowing all the features coming in JDK 8 and when they actually get included can review the JDK feature list and changesets.
InfoQ has covered the announcement of JSR 310 back in early 2007, when the JSR was originally planned to be shipped with JDK 7. InfoQ has also interviewed Stephen Colebourne, lead of the JSR 310, back in 2010, during the first of the JSR's early draft reviews. The last InfoQ coverage of JSR 310 was on September 2012, when the JSR was officially added to the Java 8 feature list.
