1. Introduction
Java 8 introduced a new set of date and time classes. Knowing which ones to use and when can be confusing. In this tutorial, we’ll look at the difference between the Instant and LocalDateTime classes.
2. The Instant Class
The easiest way to think of the Instant class is as a single moment in time in the UTC time zone. If we think of time as a line, Instant just represents a single point on the line.
Under the hood, the Instant class is really just counting the number of seconds and nanoseconds relative to the standard Unix epoch time of January 1, 1970, at 00:00:00. This point in time is denoted by 0 seconds and 0 nanoseconds, and everything else is just an offset from it.
By storing the number of seconds and nanoseconds relative to this specific point in time, it allows the class to store both negative and positive offsets. In other words, the Instant class can represent times both before and after the epoch time.
2.1. Using Instant
Let’s look at how we can work with the Instant class. First, it provides various static methods for quickly computing an instant along the timeline.
For example, the Instant.now() method gives us an Instant object that represents the current UTC time. We can also do some basic arithmetic with Instant:
Instant twelveHoursFromNow = Instant.now().plus(12, ChronoUnit.HOURS);
Instant oneWeekAgo = Instant.now().minus(7, ChronoUnit.DAYS);
Additionally, we can compare two Instants:
Instant instant1 = Instant.now();
Instant instant2 = instant1.plus(1, ChronoUnit.SECONDS);
assertTrue(instant1.isBefore(instant2));
assertFalse(instant1.isAfter(instant2));
2.2. Limitations
The Instant class is straightforward but does have some drawbacks. First, it doesn’t exactly match other standards that account for leap seconds. Instead of adding or removing a single second at the end of a day, it uses its own time scale that spreads out the second across the final 1000 seconds of that day.
In doing so, it can essentially treat every day as having exactly 86,400 seconds. However, this isn’t how other time standards work, so Instant isn’t as precise.
Also, because Instant simply stores the number of seconds and nanoseconds from a fixed epoch time, it’s limited in how much time it can represent. Specifically, the number of seconds in an Instant is stored using the long data type. This means there’s a limit to how far before and after the Unix epoch time we can represent with an Instant.
Luckily, the min and max are roughly 1 billion years before and after, so this limitation may not impact most applications.
3. The LocalDateTime Class
Now let’s look at the LocalDateTime class. The first thing to know is that, despite its name, it’s not tied to any time zone. Essentially the Local prefix means the date and time are in whatever locality we happen to be in.
We can think of it as simply a calendar set to a specific day of the year, along with a clock at a certain time of day. In fact, the underlying date and time values are stored using LocalDate and LocalTime types, respectively. Both of these values exist independently of any locality. They aren’t part of any particular timeline like the Instant class.
The LocalDateTime class is great at representing a possible event that occurs regardless of time zone. For example, New Year’s Day is always on January 1 at midnight. This exact time happens in every time zone eventually, but clearly not at the same time. While people in London countdown to a new year, people in Los Angeles are happily going about their afternoons.
Thus, on its own, the LocalDateTime class isn’t practical for scenarios that require time zones. Imagine asking a colleague in a different time zone to meet at 3:00 pm on June 15th, 2023. Or imagine setting a reminder to call a friend at 5:00 pm and then flying across the country. Without any knowledge of the time zone, there’s a good chance we’ll miss the meeting with our colleague and forget to call our friend.
3.1. Using LocalDateTime
Let’s look at some examples of using the LocalDateTime class. We can easily calculate the current date and time for the default time zone using the LocalDateTime.now() method.
Just like Instant, there are a number of static methods that let us supply various combinations of the date and time values:
LocalDateTime.of(2023, 6, 1, 12, 0);
LocalDateTime.of(2023, 6, 1, 12, 0, 0);
LocalDateTime.of(2023, 6, 1, 12, 0, 0, 0);
We can also do basic arithmetic with LocalDateTime:
LocalDateTime tomorrow = LocalDateTime.now().plus(1, ChronoUnit.DAYS);
LocalDateTime oneYearAgo = LocalDateTime.now().minus(1, ChronoUnit.YEARS);
Finally, we can compare two LocalDateTime objects:
LocalDateTime now = LocalDateTime.now();
LocalDateTime y2k = LocalDateTime.of(2000, 1, 1, 0, 0);
assertTrue(now.isAfter(y2k));
assertTrue(y2k.isBefore(now));
4. Other Java Date & Time Classes
So what happens if we need to deal with time zones? We saw above that both Instant and LocalDateTime aren’t equipped for this, but luckily Java provides a number of other classes that handle time zones. Below we’ll briefly look at a few of them.
4.1. ZoneOffset
The ZoneOffset class represents an offset in hours, minutes, and seconds before or after the standard UTC zone. It’s only the offset information only and nothing more. There’s no name, knowledge of Daylight Savings, etc.
4.2. ZoneId
The ZoneId class is much more detailed than the ZoneOffset class. While it also defines the hour, minutes, and seconds from the UTC zone, it contains additional information such as a name, unique ID, Daylight Savings rules, and more.
The rules for specific time zones are set by local governments and thus change somewhat frequently. Therefore the ZoneId class encapsulates all the specific rules of each zone, as well as a history of any changes.
4.3. ZonedDateTime
Finally, we get to the ZoneDateTime class. We can think of this class as an Instant with ZoneId information. While we should always store date and time values using a consistent zone for all users, the ZoneDateTime class is useful for displaying those values in a specific zone for individual users.
5. Conclusion
Java 8 provides a rich set of APIs that are far superior to the legacy Date class for handling date and time. However, knowing which one to use for specific use cases isn’t always obvious.
In this article, we looked at two of the new classes, Instant and LocalDateTime. While they have similar APIs, they are quite different. We saw the Instant is just a negative or positive offset from the Unix epoch time and is always tied to the UTC time zone. We also saw that LocalDateTime is just a calendar and clock without any time zone information.
Both can be useful for different things, but if we require time zone information, neither will be sufficient by itself.
As always, the code examples above can be found over on GitHub.
