Java Instant Class

Last modified: April 16, 2025

The java.time.Instant class represents a point on the time-line in UTC. It measures time from the epoch of 1970-01-01T00:00:00Z. Instant provides nanosecond precision for representing timestamps.

Instant is immutable and thread-safe. It is commonly used for logging events, storing timestamps in databases, and measuring time intervals. The class works with machine time rather than human time concepts like days.

Instant Class Overview

Instant provides methods to get current time, parse strings, and perform calculations. Key operations include comparing instants, adding durations, and converting to other time types. The class handles time in seconds and nanoseconds.

public final class Instant implements Temporal, TemporalAdjuster, Comparable<Instant>, Serializable { public static Instant now(); public static Instant ofEpochSecond(long epochSecond); public static Instant ofEpochMilli(long epochMilli); public static Instant parse(CharSequence text); public long getEpochSecond(); public int getNano(); public boolean isAfter(Instant otherInstant); public boolean isBefore(Instant otherInstant); public Instant plus(long amountToAdd, TemporalUnit unit); public Instant minus(long amountToSubtract, TemporalUnit unit); }

The code above shows key methods provided by Instant. These methods allow creating, comparing, and manipulating instants. The class provides precision up to nanoseconds while maintaining compatibility with older APIs.

Creating Instant Objects

Instant objects can be created in several ways. The most common methods are now for current time and factory methods for specific points in time. Parsing from strings is also supported.

Main.java

package com.zetcode;

import java.time.Instant;

public class Main {

public static void main(String[] args) {
    
    // Current instant
    Instant now = Instant.now();
    System.out.println("Current instant: " + now);
    
    // From epoch seconds
    Instant epochSec = Instant.ofEpochSecond(1_000_000);
    System.out.println("From epoch seconds: " + epochSec);
    
    // From epoch milliseconds
    Instant epochMilli = Instant.ofEpochMilli(1_000_000_000L);
    System.out.println("From epoch milliseconds: " + epochMilli);
    
    // From string
    Instant parsed = Instant.parse("2025-01-01T00:00:00Z");
    System.out.println("Parsed from string: " + parsed);
}

}

This example demonstrates different ways to create Instant objects. The output shows timestamps in ISO-8601 format. The now method captures the current moment with nanosecond precision where available.

Getting Instant Components

An Instant can be decomposed into its epoch seconds and nanoseconds components. These values represent time since 1970-01-01T00:00:00Z. The methods are useful for interoperability with older APIs.

Main.java

package com.zetcode;

import java.time.Instant;

public class Main {

public static void main(String[] args) {

    Instant instant = Instant.now();
    
    // Get epoch seconds
    long seconds = instant.getEpochSecond();
    System.out.println("Epoch seconds: " + seconds);
    
    // Get nanoseconds fraction
    int nanos = instant.getNano();
    System.out.println("Nanoseconds: " + nanos);
    
    // Convert to milliseconds (losing nanos precision)
    long millis = instant.toEpochMilli();
    System.out.println("Epoch milliseconds: " + millis);
}

}

This example shows how to extract components from an Instant. Note that toEpochMilli loses nanosecond precision as it converts to milliseconds. The epoch second and nanosecond together provide full precision.

Comparing Instants

Instants can be compared to determine chronological order. The class provides isBefore, isAfter, and compareTo methods. These comparisons are essential for time-based logic in applications.

Main.java

package com.zetcode;

import java.time.Instant; import java.time.temporal.ChronoUnit;

public class Main {

public static void main(String[] args) {

    Instant now = Instant.now();
    Instant later = now.plus(1, ChronoUnit.HOURS);
    Instant earlier = now.minus(30, ChronoUnit.MINUTES);
    
    System.out.println("Now is before later: " + now.isBefore(later));
    System.out.println("Now is after earlier: " + now.isAfter(earlier));
    System.out.println("Comparison result: " + now.compareTo(later));
    
    // Equality check
    Instant copy = Instant.ofEpochSecond(now.getEpochSecond(), now.getNano());
    System.out.println("Now equals copy: " + now.equals(copy));
}

}

This example demonstrates various ways to compare Instant objects. The comparison methods consider both seconds and nanoseconds components. Note that equality requires both components to match exactly.

Adding and Subtracting Time

Instant supports temporal arithmetic through plus and minus methods. These operations are useful for calculating future or past points in time. The class handles overflow and underflow automatically.

Main.java

package com.zetcode;

import java.time.Instant; import java.time.Duration; import java.time.temporal.ChronoUnit;

public class Main {

public static void main(String[] args) {

    Instant now = Instant.now();
    
    // Add using ChronoUnit
    Instant inOneHour = now.plus(1, ChronoUnit.HOURS);
    System.out.println("In one hour: " + inOneHour);
    
    // Subtract using Duration
    Instant thirtyMinsAgo = now.minus(Duration.ofMinutes(30));
    System.out.println("Thirty minutes ago: " + thirtyMinsAgo);
    
    // Add days (converted to seconds)
    Instant tomorrow = now.plus(1, ChronoUnit.DAYS);
    System.out.println("Tomorrow: " + tomorrow);
    
    // Mixed operations
    Instant complex = now.plus(2, ChronoUnit.HOURS)
                       .minus(15, ChronoUnit.MINUTES);
    System.out.println("Complex operation result: " + complex);
}

}

This example shows various ways to perform temporal arithmetic with Instant. Operations can use ChronoUnit constants or Duration objects. All calculations are precise to nanoseconds and handle unit conversions automatically.

Converting Between Time Types

Instant can be converted to and from other temporal types like ZonedDateTime. These conversions are essential when working with time zones or human-readable date representations.

Main.java

package com.zetcode;

import java.time.Instant; import java.time.LocalDateTime; import java.time.ZoneId; import java.time.ZonedDateTime;

public class Main {

public static void main(String[] args) {

    Instant now = Instant.now();
    
    // Convert to ZonedDateTime
    ZonedDateTime zoned = now.atZone(ZoneId.of("America/New_York"));
    System.out.println("In New York: " + zoned);
    
    // Convert to LocalDateTime (loses timezone info)
    LocalDateTime local = LocalDateTime.ofInstant(now, ZoneId.systemDefault());
    System.out.println("Local date-time: " + local);
    
    // Convert back to Instant
    Instant back = zoned.toInstant();
    System.out.println("Back to instant: " + back);
    
    // Convert from LocalDateTime
    Instant fromLocal = LocalDateTime.now().atZone(ZoneId.systemDefault()).toInstant();
    System.out.println("From local date-time: " + fromLocal);
}

}

This example demonstrates conversions between Instant and other temporal types. Note that LocalDateTime lacks timezone information, so system default is used. All conversions preserve the exact moment in time being represented.

Measuring Time Intervals

Instant is often used to measure time intervals between events. The Duration class works with Instant to provide precise time measurements with various units.

Main.java

package com.zetcode;

import java.time.Instant; import java.time.Duration;

public class Main {

public static void main(String[] args) throws InterruptedException {

    Instant start = Instant.now();
    
    // Simulate work
    Thread.sleep(1500);
    
    Instant end = Instant.now();
    
    // Calculate duration
    Duration duration = Duration.between(start, end);
    System.out.println("Elapsed time: " + duration.toMillis() + " ms");
    System.out.println("In seconds: " + duration.getSeconds() + "." + 
        duration.getNano() / 1_000_000 + " seconds");
    
    // Create duration and add to instant
    Duration twoHours = Duration.ofHours(2);
    Instant future = start.plus(twoHours);
    System.out.println("Two hours later: " + future);
}

}

This example shows how to measure time intervals using Instant and Duration. The Duration.between method calculates precise time differences. Durations can also be used to perform temporal arithmetic with Instants.

Source

Java Instant Class Documentation

In this article, we’ve covered the essential methods and features of the Java Instant class. Understanding these concepts is crucial for accurate time handling in modern Java applications.

Author

My name is Jan Bodnar, and I am a dedicated programmer with many years of experience in the field. I began writing programming articles in 2007 and have since authored over 1,400 articles and eight e-books. With more than eight years of teaching experience, I am committed to sharing my knowledge and helping others master programming concepts.

List all Java tutorials.