Java Date and time API: the Instant class

The Date and time API in Java 8 has been completely revamped. Handling dates, time zones, calendars etc. had been cumbersome and fragmented in Java 7 with a lot of deprecated methods. Developers often had to turn to 3rd party date handlers for Java such as Joda time.

One of many new key concepts in the java.time package of Java 8 is the Instant class. It represents a point of time in a continuous timeline where this time point is accurate to the level of nanoseconds.

The immutable Instant class comes with some default built-in values:

Instant now = Instant.now();
Instant unixEpoch = Instant.EPOCH;
Instant minimumInstant = Instant.MIN;
Instant maximumInstant = Instant.MAX;

• “now”, as the name suggests, represent the current date, or current instance of time in the UTC time zone.
• “unixEpoch” will be the traditional UNIX epoch date from 1970 January 1 midnight. This is also an important point of reference of the timeline of the Instant class. E.g. the date 2014-01-01 will have a positive number as the “seconds since EPOCH” whereas 1960-01-01 will get a negative value for the same property.
• The minimum value of the Instant class is exactly 1 billion years ago, denoted as ‘-1000000000-01-01T00:00Z’ in the documentation. This is the starting point of the timeline of the Instant class
• The maximum value is consequently the last moment of the year of 1 billion. This is the end point of the timeline of the Instant class

Example

Suppose you’d like to measure the time it takes to run a method:

Instant start = Instant.now();
Thread.sleep(10000);
Instant end = Instant.now();
Duration duration = Duration.between(start, end);
long seconds = duration.getSeconds();

There we see yet another new object from the java.time package, namely Duration. The Duration object allows to easily retrieve the time span between two dates and retrieve the days, hours, seconds etc. of that time span. In this case “seconds” will be equal to 10 as expected.

Note, however, that the Instant class cannot be used for date purposes such as February 23 2013. There’s no concept of years, months and days in the Instant class like we have in Date and Calendar in Java 7. If you’re looking to handle dates then LocalDate, LocalDateTime and LocalTime classes will be more useful. Check out the the link at the end of this post to find the posts on these and various other date-related classes in Java 8.

Duration

The Duration class has a number of useful methods. Duration is very similar to the Period class we saw in the post referenced in the previous paragraph. Here come some examples.

Duration.between

Suppose you have two Duration classes and you’d like to see which one was longer. The “compareTo” method will help you:

Instant startOne = Instant.now();
Thread.sleep(1000);
Instant endOne = Instant.now();
Duration durationOne = Duration.between(startOne, endOne);

Instant startTwo = Instant.now();
Thread.sleep(100);
Instant endTwo = Instant.now();
Duration durationTwo = Duration.between(startTwo, endTwo);
    
int compareTo = durationOne.compareTo(durationTwo);

compareTo will be 1 in the above example as the first part of the comparison, i.e. durationOne is longer. It will be -1 if comparisonTwo is longer and 0 if they are of equal length.

divideBy

You can also divide a duration by a value to see how many sections of that value fit into a duration:

Duration dividedBy = durationOne.dividedBy(10);
long toMillis = dividedBy.toMillis();

Here we want to divide durationOne, i.e. 100 millis by 10 millis. The variable “dividedBy” will almost always get the value 10 as 100 / 10 = 10 but the exact timing can depend on the code execution when “startOne” and “startTwo” are created, so you might see 11 sometimes.

isZero

This is to check if two instances happened at the same time, i.e. there’s no duration between them:

Duration zeroDuration = Duration.between(startOne, startOne);
boolean zero = zeroDuration.isZero();

“zero” will be true in this case.

isNegative

isNegative will occur if the end date occurred before the start date. I’m not sure how that scenario can occur but let’s deliberately supply the wrong values to the between method:

Duration negativeDuration = Duration.between(endOne, startOne);
boolean negative = negativeDuration.isNegative();

“negative” will be true.

Plus and minus methods

You’ll find a range of methods whose names start with “plus” and “minus”. They are meant to add and subtract time units to and from a Duration instance. Examples:

Duration minusMinutes = durationOne.minusMinutes(10);
Duration plusDays = durationOne.plusDays(2);
Duration plus = durationOne.plus(durationTwo);

Read the next post on Java 8 Dates here.

View all posts related to Java here.