It’s About Time

Everyone who has been working with Java for a while knows that the it lacks a decent API for working with dates, times and the like. In this blog post I want to briefly summarize what the problems with the existing APIs are. Then I’m going to discuss the new Java 8 Date-Time API .

It all began with java.util.Date . Although relatively simple and strait forward to use, this class has a series of flaws. At first, java.util.Date is not a date, but “a specific instant in time, with millisecond precision” . You might also be surprised by the output of

1System.out.println("Current year: " + new Date().getYear());

which in fact writes the current year minus 1900 to your terminal. Generally, the representations used by the various getters and setters of the date class are quite irregular. Also, being a lightweight value type, java.util.Date should clearly be immutable, which it is not. But the most serious flaw of the java.util.Date class is that is doesn’t properly support time zones. This is the
reason why java.util.Calendar was born. Unfortunately java.util.Calendar was never very popular among Java developers, as the related APIs are quite cumbersome. Also, as with java.util.Date , there is no proper way to deal with time intervals. Try to compute the number of days since you where born to see what I mean. To cut a long story short:

java.util.Date is a testament to the fact that even brilliant programmers can screw up. java.util.Calendar, which Sun licensed to rectify the Date mess, is a testament to the fact that average programmers can screw up, too.
http://stackoverflow.com/questions/1571265/why-is-the-java-date-api-java-util-date-calendar-such-a-mess

This is the reason why a lot of Java developers, including me, avoid the JDK date and time APIs wherever possible and use Joda Time instead.

With the upcoming release of Java 8, another date and time API is entering the picture. Before diving into details I want to give you a rough overview of the new API and discuss how it compares to its predecessors. Since JSR-310 was mostly driven by the creator of Joda Time , you will indeed notice a lot of similarities to the aforementioned library. Don’t expect Java 8 to bundle a copy of Joda Time under a different package though. There is a very interesting blog post where Stephen Colebourne explains the rationale behind some of the differences between Joda Time and the new Java time API. These include

• A different approach for supporting alternative calendar systems.
• Factory methods are strongly favoured over constructors (which are mostly private).
• A clear separation between human and machine timelines.
• Null arguments are treated as errors.

However, apart from the points mentioned above, the new Java 8 time API feels very much like Joda Time :

• All date time classes are immutable.
• Class and method names are often very similar or identical.
• The library uses unchecked exceptions only.
• The API is powerful and easy to use.

Notice the sharp contrast to java.util.Calendar , that is neither powerful nor easy to use, and heavily relies on mutable state. Another key difference of the new API to java.util.Calendar and the broken java.util.Date is that concepts like a date without a time, or a time without a date, are properly supported. The same applies for date time arithmetic and durations.

Let’s take a look at some simple examples. We start with a small program that deals with birthdays:

1package de.codecentric.java.time;
2 
3import java.time.LocalDate;
4import java.time.MonthDay;
5import java.time.temporal.ChronoUnit;
6 
7public class Birthdays {
8    public static void main(String[] args) {
9        LocalDate dateOfBirth = LocalDate.of(1981, 5, 1);
10        System.out.println("You are " + getDaysAlive(dateOfBirth) + " days alive;"
11            + " your next birthday is in " 
12            + getDaysToNextBirthday(MonthDay.from(dateOfBirth)) + " day(s).");
13    }
14 
15    private static long getDaysAlive(LocalDate dateOfBirth) {
16        return ChronoUnit.DAYS.between(dateOfBirth, LocalDate.now());
17    }
18 
19    private static long getDaysToNextBirthday(MonthDay birthday) {
20        LocalDate nextBirthday = getNextBirthday(birthday);
21        return ChronoUnit.DAYS.between(LocalDate.now(), nextBirthday);
22 
23    }
24 
25    private static LocalDate getNextBirthday(MonthDay birthday) {
26        LocalDate today = LocalDate.now();
27        LocalDate birthdayThisYear = birthday.atYear(today.getYear());
28        if(birthdayThisYear.isAfter(today) || birthdayThisYear.equals(today))
29            return birthdayThisYear;
30        return birthdayThisYear.plusYears(1);
31    }
32}

The code should be pretty self explanatory, so I won’t elaborate on it in detail, but you should notice the use of LocalDate, which is a date without a time or a timezone, as well as the MonthDay class, that just represents a month with a day.

In the next example we obtain the current time in Vladivostok:

1package de.codecentric.java.time;
2 
3import java.time.LocalTime;
4import java.time.ZoneId;
5import java.time.ZonedDateTime;
6 
7public class TimeInVladivostok {
8    public static void main(String[] args) {
9        System.out.println("Time in Vladivostok: " + getTimeInVladivostok());
10    }
11 
12    private static LocalTime getTimeInVladivostok() {
13        return ZonedDateTime.now(ZoneId.of("Asia/Vladivostok")).toLocalTime();
14    }
15}

The code is completely straight forward as it should be. ZonedDateTime is a date and a time with time zone information. LocalTime, which is the return type of ZonedDateTime#toLocalTime() is a time without a date and without a time zone. The next example is about DateTimeFormatters:

1package de.codecentric.java.time;
2 
3import static org.junit.Assert.assertEquals;
4 
5import java.time.DateTimeException;
6import java.time.LocalDate;
7import java.time.LocalTime;
8import java.time.format.DateTimeFormatter;
9 
10import org.junit.Test;
11 
12public class TestDateTimeFormatters {
13    private static final DateTimeFormatter 
14        FMT_LOCAL_DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"),
15        FMT_LOCAL_TIME = DateTimeFormatter.ofPattern("HH:mm");
16 
17    @Test
18    public void testParse() {
19        assertEquals(LocalDate.of(1999, 12, 31), LocalDate.parse("1999-12-31"));
20        assertEquals(LocalTime.of(20, 15), LocalTime.parse("20:15", FMT_LOCAL_TIME));
21    }
22 
23    @Test
24    public void testFormat() {
25        assertEquals("2007-11-12", LocalDate.of(2007, 11, 12).format(FMT_LOCAL_DATE));
26        assertEquals("12:31", LocalTime.of(12, 31).format(FMT_LOCAL_TIME));
27    }
28 
29    @Test(expected = DateTimeException.class)
30    public void testIllegalParsing() {
31        LocalDate.parse("23:59", FMT_LOCAL_TIME);
32    }
33 
34    @Test(expected = DateTimeException.class)
35    public void testIllegalFormatting() {
36        LocalTime.of(23, 32).format(FMT_LOCAL_DATE);
37    }
38}

As you can see, the format string syntax is similar to SimpleDateFormat . Unlike SimpleDateFormat however, DateFormatters are thread safe. Also note that we can use them together with different types. When doing so, some care has to be taken to only use combinations that make sense. Constructing a LocalDate from a formatter that only extracts the time of day can’t possibly work. The same is true for extracting date related information from a LocalTime. These cases are illustrated in TestDateTimeFormatters#testIllegalParsing and TestDateTimeFormatters#testIllegalFormatting in the example above.

Another important class you should be aware of is Instant. It represents a single point on the time line, without any timezone information, in other words a timestamp. Executing

1package de.codecentric.java.time;
2 
3import java.time.Instant;
4import java.time.LocalDateTime;
5import java.time.ZoneId;
6 
7public class OneInstantMultipleTimes {
8    public static void main(String[] args) {
9        Instant zero = Instant.EPOCH;
10 
11        System.out.println("Start of the Epoch in Moscow    : " + toLocalDateTime(zero, "Europe/Moscow"));
12        System.out.println("Start of the Epoch in Washington: " + toLocalDateTime(zero, "America/New_York"));
13    }
14 
15    private static LocalDateTime toLocalDateTime(Instant instant, String zoneId) {
16        return instant.atZone(ZoneId.of(zoneId)).toLocalDateTime();
17    }
18}

demonstrates how one instant can be tied to different local dates and times:

1Start of the Epoch in Moscow    : 1970-01-01T03:00
2Start of the Epoch in Washington: 1969-12-31T19:00

It is therefore illegal to extract things like the year, moth, weekdays and so forth from an Instant, although the API might tempt you to do so. The following statement for example compiles flawlessly

1Year year = Year.from(Instant.now()));

but fails with an exception at runtime. Luckily there is Year.now(), which should normally to what you want without any nasty surprises.

In this connection I should also mention Duration and Period. A Duration models a time based amount, like 42 seconds, while a Period stands for a date based amount like 1 year, 3 month and 20 days. There is another, subtle difference between Period and Duration, as they might behave differently when added to a ZonedDateTime:

1package de.codecentric.java.time;
2 
3import java.time.Duration;
4import java.time.Period;
5import java.time.ZoneId;
6import java.time.ZonedDateTime;
7 
8public class DurationVsPeriod {
9    private static final ZoneId ZONE_ID = ZoneId.of("Europe/Berlin");
10 
11    public static void main(String[] args) {
12        ZonedDateTime beforeDstOverlap = ZonedDateTime.of(2013, 10, 26, 12, 0, 0, 0, ZONE_ID);
13        Duration dayDuration = Duration.ofDays(1);
14        Period dayPeriod = Period.ofDays(1);
15 
16        System.out.println("beforeDstOverlap.plus(dayDuration): " + beforeDstOverlap.plus(dayDuration));
17        System.out.println("beforeDstOverlap.plus(dayPeriod)  : " + beforeDstOverlap.plus(dayPeriod));
18    }
19}

Bear in mind that beforeDstOverlap is actually on the last day of daylight saving time when interpreting the output of the above program:

1beforeDstOverlap.plus(dayDuration): 2013-10-27T11:00+01:00[Europe/Berlin]
2beforeDstOverlap.plus(dayPeriod)  : 2013-10-27T12:00+01:00[Europe/Berlin]

As you can see, adding a Duration of a day is like adding the related number of seconds, while adding a Period maintains the local time.

The last part of the new date time API that I want to explicitly mention here is java.time.Clock. It is an abstract class that provides acess to the current instant and time zone and has been designed with dependency injection and test driven development in mind. Take a look at the following example to see how you can take advantage of it:

1package de.codecentric.java.time;
2 
3import java.time.Clock;
4import java.time.DayOfWeek;
5import java.time.LocalDateTime;
6import java.time.LocalTime;
7 
8public class Pub {
9    private final Clock clock;
10 
11    public Pub(Clock clock) {
12        this.clock = clock;
13    }
14 
15    public boolean isOpen() {
16        LocalDateTime now = LocalDateTime.now(clock);
17        if(now.getDayOfWeek() == DayOfWeek.SUNDAY)
18            return false;
19 
20        LocalTime time = now.toLocalTime();
21        return time.isAfter(LocalTime.of(19, 0)) && time.isBefore(LocalTime.of(23, 0));
22    }
23}

In production, you could use Clock#systemDefaultZone(), but for testing you might find Clock#fixed() helpful.

Summarizing it seems that the JDK has a proper date time API at last. If you understand the basic concepts, the API is very pleasant to use and leads to self documenting code. The only downside is that the library could catch a few more errors statically (that is at compile time), than by throwing exceptions at runtime. Note that I’ve only scratched to surface of what you can do. A much more detailed discussion of this topic can be found here .