Essentials of Java’s Time API

How JSR310 changed the way we handle date and time

Clear Glass with Red Sand — Nile (Pixabay)

Dealing with date and time is a cumbersome task in many programming languages. But with Java 8, the JDK provides us with a comprehensive and completely new API, changing how we deal with time-related concepts.

Even though JSR310 was introduced with Java 8, the code example will use a Java 10 feature, local variable type inference, to improve readability.
The code examples themselves will all be Java 8 compatible, though.
The // => part of code examples will show the toString() output of the previous line/variable.

Table of Contents
Pre-JSR310
The Java Time API (JSR310)
Local Types
Time Zones and Offsets
Other Date and Time Types
General API Design
Android Support
Java Time API for Java 6 and 7
Resources

Pre-JSR310

Before the new API, the JDK provided only a few classes to handle date and time.

Here are the most commonly known ones:

• java.util.Date: a precise instant of time, millisecond precision, relative to January 1st, 1970, 00:00:00 GMT
• java.util.Calendar: the bridge between an instant of time and calendar fields (e.g., month, year, day, etc.)
• java.util.TimeZone: responsible for zone offset and handling daylight saving time (DST)
• java.text.DateFormat: formatting and parsing

At first glance, these four seem to cover the most common scenarios.

But are they really able to handle all delicate specialties of date and time?

Milliseconds

With java.util.Date being based on milliseconds since Unix timestamp "0", we tend to think of date and time in sums of milliseconds:

Using milliseconds might seem intuitive, but it will lead to bugs eventually.