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.
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.
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.
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.
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.
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.
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
List all Java tutorials.