Java 8 DateTime

Whats your idea of a perfect date? 😉

This blog is supposed to be a simple introduction to Java 8 java.time library. From personal experience I can proudly say that timestamps are hard….Yes, proudly, this is because I’ve finally gotten somewhat of a hold on them — but by no means am I an expert. In this post I’ll briefly describe the different types of timestamps that are available to you through Java 8. The next post, Java 8 DateTime: Part 2 The Parsing, will jump into use cases and considerations of timestamps from the standpoint of a data producer and a data consumer, as well as a few code samples that I personally thought the internet was missing — maybe they are not anymore ¯\_(ツ)_/¯.

Understanding Timestamps

Timestamps are usually made up of a few reoccurring components. This will sound really dumb but stay with me. Timestamps include the following attributes:

Most of these aspects of a timestamp may seem pretty straight forward, with the exception of a few that you may not have expected. e.g. Year being optional — this is a very frustrating aspect of working with timestamps, but I’ve seen it countless times. Zone and offset information are two more useful components of timestamps that many may not know about. These last two fields will be the key difference when deciding which Timestamp class to use.

Timestamp Formats:

The 3 formats:

2007–12–03T10:15:30+01:00 Europe/Paris
2011–12–03T10:15:30–01:00
1970–01–01T00:00:00.123Z

The 3 main formats are ZonedDateTime, OffsetDateTime, and Instant. The difference between each of the timestamps is primarily just the “amount” of information provided, shown in the diagram below.

Information Scale of the 3 Timestamp Classes

Let’s start at the bottom— since this is the starting point for these 3 timestamp formats. Among the 3 formats, Instant provides the least information. Instant provides just the specific moment/instant in time and is stored as just the seconds and nanoseconds (to allow for greater granularity) from epoch. Just in case the realm of timestamps is completely new to you:

The “epoch” then serves as a reference point from which time is measured. - https://en.wikipedia.org/wiki/Epoch_(reference_date)

Instant uses “standard Java epoch of 1970-01-01T00:00:00” — Java Docs on Instant

Now using Instant as our reference point, we can explore the other two timestamps. Going up to OffsetDateTime, we add information related to the where the timestamp is from. It does not provide an exact zone, but we get information regarding how many hours and mins away from a time the timestamp represents. Using the second timestamp from the examples above, this essentially means the time provided is 1 hour away from UTC. Adding the offset back will provide the local time. Finally, instead of just providing the number of hours away from UTC, you can also provide more in-depth information by providing the Zone. ZonedDateTime adds all the rules with regards to time zones. The full rules take into account things like which zones follow daylight savings time, and whether it is currently daylights saving time or not. In summary, if you know where to look — the documentation does a good job at describing this more succinctly.

Instant is the simplest, simply representing the instant. OffsetDateTime adds to the instant the offset from UTC/Greenwich, which allows the local date-time to be obtained. ZonedDateTime adds full time-zone rules. — More Java Docs

Now that you understand the formats, I will see you over at part 2 of this blog post: Java 8 DateTime: Part 2 The Parsing!