JB Header
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 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.
Core Ideas behind the design of new Date-Time API in Java 8
  1. Thread Safety: java.util.Date and java.util.DateTimeFormatter were 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.
  2. 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.LocalDate instead.
  3. 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.
Let us now take a look at the important Date-Time classes in the new 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
LocalDateread tutorialClick to Read tutorial on LocalDate\LocalTime\LocalDateTimePrimary class for holding a date, consisting of year-month-date, without a time zone.
LocalTimePrimary class for holding time, consisting of hour:min.seconds.nanoseconds, without a time zone.
LocalDateTimeHolds 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.
InstantAn 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.
ZoneIdread tutorialClick to Read tutorial on Java 8 Time Zone handlingUniquely identifies a time zone.
ZonedDateTimeHolds date-time instances with time zone. Can be created by combining LocalDate, LocalTime and ZoneId instances. Applies ZoneRules to time zone calculations.
ZoneOffsetHolds the time zone offset value in +-hours:minutes difference from UTC+00:00 time.
ZoneRulesEncapsulates the rules for converting a given Date-Time to a specific ZoneId. (java.time.zone package class)
ZoneRulesProviderResponsible for configuring of time zone rules at Java platform-level or environment level.(java.time.zone package class)
OffsetDateTimeContains date-time to nanosecond precision with time zone offset from UTC+00:00. Doesn't apply ZoneRules to time zone calculations.
OffsetTimeContains time upto nano second precision with offset from UTC+00:00.
PeriodHolds measure of time between 2 dates in days,months and years.
DurationHolds 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).
TemporalAdjusterread tutorialClick to Read Tutorial on TemporalAdjustersEncapsulates the strategy for modifying or adjusting Temporal objects.(Belongs to java.time.temporal package.)
ChronologyInterface 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.)
DateTimeFormatterProvides ability to print and parse Date and Time classes.(Belongs to java.time.format package.)
DateTimeFormatterBuilderProvides ability to build DateTimeFormatter as per your specific needs.(Belongs to java.time.format package.)

1. www.joda.org/joda-time