Overview of Java 8's new Date-Time API | java.time package tutorial
Motivation for the major Date and Time API upgrade in Java 8
Date and Time is one area where until Java 7 programmers had to do make do with a poorly designed API. Not only were the commonly used
Several design decisions around these classes were not up to the otherwise high JDK design standards. For example -
The primary class provided for date formatting,
Over the years, the lack of a good quality Date and Time library in core JDK led to the popularity of non-JDK date-time libraries such as Joda-Time1.
Java designers/architects, acknowledging the gradual loss of interest in core JDK Date-Time classes, and the popularity of non-JDK Date-Time libraries, went back to the drawing board to design Date and Time API from scratch for Java 8. The Date-Time team also included the architect of Joda-Time (Stephen Colebourne). The result was the new
Let us now understand the core driving forces (design goals) around which Java 8's new Date and Time API was created.
Core Ideas behind the design of new Date-Time API in Java 8
(Note - I will be adding links to tutorials for each of these classes in the table below as I write them.)
1. www.joda.org/joda-time
java.util.Date(from JDK 1) and java.util.Calendar(from JDK 1.1) classes mutable, they were non-thread safe as well.Several design decisions around these classes were not up to the otherwise high JDK design standards. For example -
Date’s year offset started from the year 1900, the value contained in the Date object was not really a 'date' but was an offset from the Java epoch in milliseconds, the month index of Calendar starts from 0 (instead of 1), and so on...The primary class provided for date formatting,
java.text.DateFormat, was not thread safe. As a result, two concurrent threads utilizing the same DateFormat instance could lead to corrupted results!Over the years, the lack of a good quality Date and Time library in core JDK led to the popularity of non-JDK date-time libraries such as Joda-Time1.
Java designers/architects, acknowledging the gradual loss of interest in core JDK Date-Time classes, and the popularity of non-JDK Date-Time libraries, went back to the drawing board to design Date and Time API from scratch for Java 8. The Date-Time team also included the architect of Joda-Time (Stephen Colebourne). The result was the new
java.time package being introduced in Java 8 which has completely re-built the Date-Time classes from the ground-up, and one which is heavily influenced by the Joda-Time API.Let us now understand the core driving forces (design goals) around which Java 8's new Date and Time API was created.
- Thread Safety:
java.util.Dateandjava.util.DateTimeFormatterwere not thread safe. In today's parallel programming paradigms, these are performance disasters waiting to happen. Java 8's Date-time classes have been defined as immutable by default. So, if you modify the date or time using any of the in-built library methods then what you get back is a new instance with new values, the old instance remains the same. Result - A siginificant boost for concurrent processing environments. - Domain-driven design: Domain-driven design refers to deriving the class design and interaction based on their actual usage in business systems. So, classes and their interactions and straightforward. For example: There is no need to create a date out of milliseconds from Java epoch if you do not really require that. Just use an instance of
java.time.LocalDateinstead. - In-built support for multiple calendar systems: Java 8 has significantly improved the handling of non-ISO 8601 calendar systems such as Japanese or Thai calenders. This should further improve the acceptability of the new date-time API for implementing non-standard chronology specific requirements.
java.time package.(Note - I will be adding links to tutorials for each of these classes in the table below as I write them.)
| Important Date-Time classes in Java 8’s new ‘java.time’ package | ||
| Class Name | Tutorial Link | Class capabilities |
| LocalDate | read tutorialClick to Read tutorial on LocalDate\LocalTime\LocalDateTime | Primary class for holding a date, consisting of year-month-date, without a time zone. |
| LocalTime | Primary class for holding time, consisting of hour:min.seconds.nanoseconds, without a time zone. | |
| LocalDateTime | Holds a date-time value, consisting of year-month-dateThour:min.seconds.nanoseconds, without a time zone. Can be created using a LocalDate and LocalTime instance taken together. | |
| Instant | An instant on the time scale. Consists of an offset in seconds elapsed from Java epoch (1970-01-01T00:00:00Z), with a nanosecond value storing precision inside the second. Ideal for machine timestamp capture purposes. | |
| ZoneId | read tutorialClick to Read tutorial on Java 8 Time Zone handling | Uniquely identifies a time zone. |
| ZonedDateTime | Holds date-time instances with time zone. Can be created by combining LocalDate, LocalTime and ZoneId instances. Applies ZoneRules to time zone calculations. | |
| ZoneOffset | Holds the time zone offset value in +-hours:minutes difference from UTC+00:00 time. | |
| ZoneRules | Encapsulates the rules for converting a given Date-Time to a specific ZoneId. (java.time.zone package class) | |
| ZoneRulesProvider | Responsible for configuring of time zone rules at Java platform-level or environment level.(java.time.zone package class) | |
| OffsetDateTime | Contains date-time to nanosecond precision with time zone offset from UTC+00:00. Doesn't apply ZoneRules to time zone calculations. | |
| OffsetTime | Contains time upto nano second precision with offset from UTC+00:00. | |
| Period | Holds measure of time between 2 dates in days,months and years. | |
| Duration | Holds measure of time in terms of seconds and nanoseconds inside the second. Quantity of time can be fetched in hours, minutes, days(24 hours),(seconds with nanoseconds inside the second). | |
| TemporalAdjuster | read tutorialClick to Read Tutorial on TemporalAdjusters | Encapsulates the strategy for modifying or adjusting Temporal objects.(Belongs to java.time.temporal package.) |
| Chronology | Interface Chronology holds together a Calendar system in its implementation. In-built Calendar systems include ThaiBuddhist, Japanese, Hijrah and ISO.(Belongs to java.time.chrono package.) | |
| DateTimeFormatter | Provides ability to print and parse Date and Time classes.(Belongs to java.time.format package.) | |
| DateTimeFormatterBuilder | Provides ability to build DateTimeFormatter as per your specific needs.(Belongs to java.time.format package.) | |
1. www.joda.org/joda-time
Tutorials on Java 8’s new Date and Time API
Overview of Java 8's new Date and Time APIClick to Read Overview of Java 8's new Date-Time API Working with time zones in Java 8| ZonedDateTime, ZoneId tutorial with examplesClick to Read tutorial on time zone handling in Java 8 How to convert LocalDate to String and String to LocalDateClick to Read tutorial on String to LocalDate conversions How to convert java.util.Date to java.time.LocalDateClick to Read tutorial on java.util.Date to LocalDate conversion Formatting localized dates in Spanish and FrenchClick to Read date formatting in Spanish & French How to get day-of-week for a given dateHow to get day-of-week using java.time.DayOfWeek enumDate Modification using TemporalAdjuster Click to Read Tutorial on TemporalAdjusters
Overview of Java 8's new Date and Time APIClick to Read Overview of Java 8's new Date-Time API Working with time zones in Java 8| ZonedDateTime, ZoneId tutorial with examplesClick to Read tutorial on time zone handling in Java 8 How to convert LocalDate to String and String to LocalDateClick to Read tutorial on String to LocalDate conversions How to convert java.util.Date to java.time.LocalDateClick to Read tutorial on java.util.Date to LocalDate conversion Formatting localized dates in Spanish and FrenchClick to Read date formatting in Spanish & French How to get day-of-week for a given dateHow to get day-of-week using java.time.DayOfWeek enumDate Modification using TemporalAdjuster Click to Read Tutorial on TemporalAdjusters