Java 101: Catching up with the Java Date and Time API

Get to know the java.time classes you're most likely to use in Java 8

Page 2 of 7

Joda Time in JSR 310

Joda Time is an open source date and time API. Released by Stephen Colebourne in February 2005, it became a popular alternative to the standard Java date and time APIs. While the JSR 310: Date and Time API isn't Joda Time (due to various design flaws) it is heavily influenced by it. In fact, Colebourne is a JSR 310 co-lead.

Java Date and Time API overview

JSR 310: Date and Time API was developed to overcome numerous problems with Java's previous date and time APIs. As a result, it has been architected around a number of important design principles:

  • Immutability and thread safety: All of the Date and Time API's core classes are immutable, which ensures that you don't have to worry about threading issues caused by lack of thread synchronization. Immutable objects are simple to construct, use, and test, they make for good hash keys, and so on.
  • Fluency: Date and Time presents a fluent interface, which should make its methods more readable and easier to learn, especially when chained together. Fluent factory methods (e.g., now(), from(), and of-prefixed methods) are used as an alternative to constructors. You'll also be able to use with-prefixed methods if you need to return a copy of the current instance with additional information.
  • Clarity: Each method in the Date and Time API is well-defined and clear about what it accomplishes. Additionally, Date and Time rejects null arguments early. Unless otherwise noted, passing a null argument to a method in any class or interface will cause a NullPointerException to be thrown. Validation methods that take object arguments and return Boolean values are an exception: they generally return false when null is passed.
  • Extensibility: The Strategy design pattern is used throughout the API to allow for extension while avoiding confusion. For example, although Date and Time's classes are based on the ISO-8601 calendar system, you can also work with the non-ISO calendars (such as Japanese Imperial) that are included in the API, or you could even introduce your own calendar.

Date and Time is described by some 60 types (at the time of this writing) that are organized into a main package and four subpackages:

  • java.time presents classes that represent the principal date-time concepts: instants, durations, dates, times, time zones, partials, and periods. All of this package's classes are immutable and thread-safe.
    • java.time.chrono provides a generic API that describes calendar systems other than the default ISO-8601 calendar system.
    • java.time.format presents classes for formatting and parsing date-time objects.
    • java.time.temporal offers field, unit, or adjustment access to a temporal object such as a date.
    • java.time.zone presents classes that support time zones and their rules.

The types in the java.time package should serve most of your needs. You'll work directly with the types in the other four packages only when you need to go beyond java.time's default ISO-8601 calendar system.

Retrofitting the old date and time APIs

To ease the transition to the new Date and Time API, the old date and time APIs have been retrofitted to interoperate with Date and Time. For example, an Instant toInstant() method has been added to java.util.Date to convert a Date instance to an Instant instance.

Touring the Date and Time API

Date and Time's many types can seem overwhelming. However, you'll often work with only a subset of the types in the java.time package. The remainder of the article will be a tour of the java.time types that you are most likely to use: classes used to store and manipulate machine time, local date and time, and international time zones in your Java applications. For each of the API types I'll include a brief overview followed by one or more working applications that demonstrate how classes are instantiated, how instances are accessed, and how instances are manipulated to obtain new instances.

| 1 2 3 4 5 6 7 Page 2