Instant Class in Java

1. Introduction

Java 8 introduced, through JSR 310, a complete overhaul of the Date/Time API by providing new, more advanced classes for Date processing. Instant is one such class that we will focus on in this article.

2. What is an Instant?

Instant is a class from the java.time package. The class represents a point in time on the time-line in UTC. For example, the value “2024-05-08T13:37:53.267843700Z” can be stored in an Instant.

The main particularity of Instant is that it is immutable and thread-safe.

3. Creating an Instant

There are two main ways of creating an Instant in Java. The first way is by using the Instant.now() methods and the second way is with the Instant.ofXXX() methods.

3.1. Using `Instant.now()` Methods

You can create an Instant object with the current time in this way:

        Instant now = Instant.now();//2024-05-08T13:37:53.267843700Z

This will query the system clock in the default timezone.
Optionally, you can provide a custom Clock to the now() method:

        Clock clock = Clock.systemDefaultZone();
        Instant now = Instant.now(clock);

It is a best practice to pass a Clock into any method that requires the current instant. This has the advantage of making your code more testable.

3.2. Using `Instant.ofXXX()` Methods

You can also create an Instant object by providing the milliseconds from the epoch of 1970-01-01T00:00:00Z:

        Instant now = Instant.ofEpochMilli(1715176763292L);//2024-05-08T13:59:23.292Z

You can also send the epoch value in seconds:

        Instant now = Instant.ofEpochSecond(1715176763L);//2024-05-08T13:59:23Z

Moreover, you can send a nanosecond fraction along with the epoch value in seconds:

        Instant now = Instant.ofEpochSecond(1715176763L,292);//2024-05-08T13:59:23.000000292Z

Note that if the provided value is positive the instant is after the epoch, else it is before the epoch.

You can check that in the example below:

        Instant instant = Instant.ofEpochMilli(-1715176763292L);//1915-08-26T10:00:36.708Z

4. Formatting an Instant object

By default, the Instant is formatted using the ISO-8601 date format. The Instant class does not have fields like year, month, etc. If you need to apply specific formatting, then you should first convert it into a class with formatting options like LocalDateTime or ZonedDateTime:

        Instant now = Instant.ofEpochMilli(1715176763292L);//2024-05-08T13:59:23.292Z
        LocalDateTime dateTime = LocalDateTime.ofInstant(now,ZoneId.of("Europe/Paris"));
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("dd/MM/yyyy hh:mm a");
        String formattedInstant = dateTime.format(formatter);// 08/05/2024 01:59 PM

Refer to the Official DateTimeFormatter Javadoc to find out about the different formatting options.

5. Parsing from String to Instant

Assuming that you have an instant in the ISO-8601 format and want to build an Instant out of it, you can use the parse() method in this way:

        String myInstant = "2024-05-08T13:59:23.292Z";// ISO-8601 format
        Instant instant = Instant.parse(myInstant);// 2024-05-08T13:59:23.292Z

Java will throw a DateTimeParseException if it is not able to parse the String with the given instant format.

6. Operating on an Instant

6.1. Comparing two Instant objects

You can use isAfter(), and isBefore() methods to compare two Instant objects:

        Instant firstInstant = Instant.ofEpochSecond(1715176763L);
        Instant secondInstant = Instant.ofEpochSecond(1715176762L);
        Instant thirdInstant = Instant.ofEpochSecond(1715176764L);
        boolean test1 = firstInstant.isAfter(secondInstant);//true
        boolean test2 = firstInstant.isBefore(thirdInstant);//true

As you can see, a larger epoch-second value is always later on the time-line than a smaller value.

Since the Instant class implements the Comparable<E> interface, you may also use the compareTo() method:

        Instant firstInstant = Instant.ofEpochSecond(1715176763L);
        Instant secondInstant = Instant.ofEpochSecond(1715176762L);
        Instant thirdInstant = Instant.ofEpochSecond(1715176764L);
        int test1 = firstInstant.compareTo(secondInstant);//A positive number
        int test2 = firstInstant.compareTo(thirdInstant);//A negative number

Lastly, you should know that the Instant class also overrides the equals() method and provides a convenient way to check the equality of two instants:

        Instant firstInstant = Instant.ofEpochSecond(1715176763L);
        Instant secondInstant = Instant.ofEpochSecond(1715176762L);
        Instant thirdInstant = Instant.ofEpochSecond(1715176763L);
        boolean test1 = firstInstant.equals(secondInstant);//false
        boolean test2 = firstInstant.equals(thirdInstant);//true

6.2. Temporal Arithmetic with Instant Objects

The Instant class provides plusXXX() and minusXXX() methods to increment and decrement the object field values(epoch-milli, epoch-second, and nanosecond). Since Instant is immutable, all these methods return a copy of the original object with updated fields.

        Instant instant = Instant.ofEpochMilli(1715176763292L);// 2024-05-08T13:59:23.292Z
        Instant nextDay = instant.plus(1, ChronoUnit.DAYS);// 2024-05-09T13:59:23.292Z
        Instant previousDay = instant.minus(1, ChronoUnit.DAYS);// 2024-05-07T13:59:23.292Z
        Instant nextHour = instant.plus(1, ChronoUnit.HOURS);// 2024-05-08T14:59:23.292Z
        Instant previousHour = instant.minus(1, ChronoUnit.HOURS);// 2024-05-08T12:59:23.292Z
        Instant nextMinute = instant.plus(1, ChronoUnit.MINUTES);// 2024-05-08T14:00:23.292Z
        Instant previousMinute = instant.minus(1, ChronoUnit.MINUTES);// 2024-05-08T13:58:23.292Z

Note that the only supported fields from the ChronoUnit Enum are: NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF_DAYS, and DAYS. Any other ChronoUnit instance will throw an UnsupportedTemporalTypeException.

Optionally, you can use the generic plus() and minus() methods to update your Instant object:

        Instant instant = Instant.ofEpochMilli(1715176763292L);// 2024-05-08T13:59:23.292Z
        Instant nextMillis = instant.plusMillis(1);// 2024-05-08T13:59:23.293Z
        Instant previousMillis = instant.minusMillis(1);// 2024-05-08T13:59:23.291Z
        Instant nextSecond = instant.plusSeconds(1);// 2024-05-08T13:59:24.292Z
        Instant previousSecond = instant.minusSeconds(1);// 2024-05-08T13:59:22.292Z
        Instant nextNano = instant.plusNanos(1);// 2024-05-08T13:59:23.292000001Z
        Instant previousNano = instant.minusNanos(1);// 2024-05-08T13:59:23.291999999Z

7. Conclusion

In this tutorial, you learned about the Instant class in Java.

8. References

1) OCP Oracle Certified Professional Java SE 17 by Khalil A. Mughal and Vasily A. Strelnikov
2) Oracle Java Documentation

Noel Kamphoa