Java Cookbook, 1st Edition

Chapter 6. Dates and Times

6.0 Introduction

Developers suffered for a decade and a half under the inconsistencies and ambiguities of the Date class from Java 1.0 and its replacement wannabe, the Calendar class from Java 1.1. Several alternative Date replacement packages emerged, including the simple and sensible Date4J and the more comprehensive Joda-Time package. Java 8 introduced a new, consistent, and well-thought-out package for date and time handling under the aegis of the Java Community Process, JSR-310,¹ shepherded by developer Stephen Colebourne. Stephen says that “JSR-310 started from scratch, but with an API ‘inspired by Joda-Time,’” his earlier package, with several important design changes.² This package is biased toward ISO 8601 dates; the default format is, for example, 2015-10-23T10:22:45. But it can, of course, work with other calendar schemes.

One of the key benefits of the new API is that it provides useful operations such as adding/subtracting dates/times. Much time was wasted by developers reimplementing these useful operations for the old APIs. With the new APIs, one can use the built-in functionality. That said, millions of lines of code are based on the old APIs, so we’ll review them briefly and then consider interfacing the new API to legacy code, in the final recipe of this chapter, Recipe 6.9.

Another advantage of the new API is that almost all objects are immutable and thus thread-safe. This can be of considerable benefit as we move headlong into the ...