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.,
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
NullPointerExceptionto 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.timepresents 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.chronoprovides a generic API that describes calendar systems other than the default ISO-8601 calendar system.
java.time.formatpresents classes for formatting and parsing date-time objects.
java.time.temporaloffers field, unit, or adjustment access to a temporal object such as a date.
java.time.zonepresents 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
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.