Java Reference
In-Depth Information
Is the third time the charm? Here is a third attempt to provide a correct, powerful, and extensible Date-Time API.
At least, so we say at the time of this writing! The new API is not a free ride, however. It has a steep learning curve if you
want to use its full potential. It consists of about 80 classes. Do not worry about the big number of classes. They have
been carefully designed and named. Once you understand the thoughts behind its design, it's relatively easy to figure
out the name of a class and the methods that you need to use in a particular situation. As a developer, you need to
understand about 15 classes to use the new Date-Time API effectively in your daily programming.
Design Principles
Before you start learning the details of the new Date-Time API, you will need to understand a few basic concepts about
dates and times. The new Date-Time API is based on ISO-8601 date-time standards. A Java date-time framework
named Joda-Time inspired the new API. If you have used Joda-Time before, you will be able to learn the new
Date-Time API quickly. You can find the details of the Joda-Time project at
http://joda-time.sourceforge.net
.
The new API makes a distinction between how dates and times are used by machines and humans. Machines
deal with time as continual ticks as a single incrementing number measured in seconds, milliseconds, etc. Humans
use a calendar system to deal with time in terms of year, month, day, hour, minute, and second. The Date-Time API
has a separate set of classes to deal with machine-based time and calendar-based human time. It lets you convert
machine-based time to human-based time and vice versa.
The legacy Date-Time API has been around for over 15 years. It is very likely that you will encounter legacy
date-time classes while working with existing applications. The legacy date-time classes have been retrofitted to work
seamlessly with the new classes. When you write new code, use the new Date-Time API classes. When you receive
objects of legacy classes as input, convert the legacy objects into new date-time objects, and use the new
Date-Time API.
The new Date-Time API consists of mostly immutable classes. Because the new API is extensible, you are advised
to create immutable classes, whenever possible, to extend the API. An operation on a date-time object creates a new
date-time object. This pattern makes it easy to chain method calls.
Classes in the Date-Time API do not provide public constructors. They allow you to create their objects by
providing static factory methods named
of()
,
ofXxx()
, and
from()
. The new API uses a well-defined naming
convention for naming methods. Each class in the API has several methods. Knowing the method-naming convention
lets you find the right method for your purpose easily. I will discuss the method-naming convention shortly in a
separate section.
A Quick Example
Let's look at an example of working with dates and times using the new Date-Time API. An instance of the
LocalDate
class represents a local date without a time; an instance of the
LocalTime
class represents a local time without a date;
an instance of the
LocalDateTime
class represents a local date and time; an instance of the
ZonedDateTime
class
represents date and time with a time zone.
A
LocalDate
and a
LocalTime
are also called partials as they do not represent an instance on the timeline; they
are not aware of changes in Daylight Saving Time. A
ZonedDateTime
represents a point in time in a given time zone
that can be converted to an instant on the timeline; it is aware of Daylight Saving Time. For example, adding four
hours to a
LocalTime
of 1 AM will give you another
LocalTime
of 5 AM irrespective of the date and location. However,
if you add four hours to a
ZonedDateTime
representing 1 AM on March 9, 2014 in the Chicago/America time zone, it
will give you 6 AM time on March 9, 2014 in the same time zone, as the clock is moved forward by one hour at 2 AM
on that day because of Daylight Saving Time. Airline applications use instances of the
ZonedDateTime
class to store
departure time and arrival time of flights.
