How to Use Instant in Java: Simple Guide with Examples

In Java, Instant represents a point in time in UTC and is part of the java.time package. You can create an Instant using methods like Instant.now() for the current time or Instant.parse() to convert a string to an instant.

Syntax

The Instant class is used to represent a moment on the timeline in UTC. Here are common ways to create an Instant:

• Instant.now(): Gets the current timestamp.
• Instant.parse(CharSequence): Parses a string in ISO-8601 format to an Instant.
• Instant.ofEpochMilli(long): Creates an Instant from milliseconds since the Unix epoch.

You can also add or subtract time using methods like plusSeconds() or minusMillis().

java

import java.time.Instant;

public class InstantSyntax {
    public static void main(String[] args) {
        Instant now = Instant.now();
        Instant parsed = Instant.parse("2024-06-01T10:15:30.00Z");
        Instant fromEpoch = Instant.ofEpochMilli(1685600000000L);

        Instant plusSeconds = now.plusSeconds(60);
        Instant minusMillis = now.minusMillis(500);

        System.out.println("Now: " + now);
        System.out.println("Parsed: " + parsed);
        System.out.println("From Epoch Millis: " + fromEpoch);
        System.out.println("Plus 60 seconds: " + plusSeconds);
        System.out.println("Minus 500 milliseconds: " + minusMillis);
    }
}

Example

This example shows how to get the current time, parse a timestamp string, and calculate a time 10 minutes later.

java

import java.time.Instant;

public class InstantExample {
    public static void main(String[] args) {
        // Get current timestamp
        Instant now = Instant.now();

        // Parse a specific timestamp string
        Instant specificTime = Instant.parse("2024-06-01T12:00:00Z");

        // Add 10 minutes (600 seconds) to the current time
        Instant later = now.plusSeconds(600);

        System.out.println("Current time: " + now);
        System.out.println("Specific time: " + specificTime);
        System.out.println("10 minutes later: " + later);
    }
}

Output

Current time: 2024-06-01T12:34:56.789Z
Specific time: 2024-06-01T12:00:00Z
10 minutes later: 2024-06-01T12:44:56.789Z

Common Pitfalls

Common mistakes when using Instant include:

• Trying to use Instant for local time zones instead of UTC. Instant always uses UTC.
• Parsing strings not in ISO-8601 format will cause exceptions.
• Confusing Instant with LocalDateTime which does not have timezone info.

Always handle exceptions when parsing and convert Instant to local time if needed using ZonedDateTime.

java

import java.time.Instant;
import java.time.format.DateTimeParseException;

public class InstantPitfall {
    public static void main(String[] args) {
        try {
            // Wrong format string causes exception
            Instant wrong = Instant.parse("06/01/2024 12:00");
        } catch (DateTimeParseException e) {
            System.out.println("Parsing failed: " + e.getMessage());
        }

        // Correct parsing
        Instant correct = Instant.parse("2024-06-01T12:00:00Z");
        System.out.println("Parsed correctly: " + correct);
    }
}

Output

Parsing failed: Text '06/01/2024 12:00' could not be parsed at index 0
Parsed correctly: 2024-06-01T12:00:00Z

Quick Reference

Method	Description
Instant.now()	Gets the current timestamp in UTC
Instant.parse(String)	Parses ISO-8601 string to Instant
Instant.ofEpochMilli(long)	Creates Instant from milliseconds since epoch
plusSeconds(long)	Adds seconds to the Instant
minusMillis(long)	Subtracts milliseconds from the Instant
toEpochMilli()	Converts Instant to milliseconds since epoch

Key Takeaways

Instant represents a point in time in UTC and is part of java.time package.

Use Instant.now() to get the current timestamp and Instant.parse() to convert ISO-8601 strings.

Instant always uses UTC; convert to local time with ZonedDateTime if needed.

Parsing non-ISO-8601 strings causes exceptions; handle them properly.

You can add or subtract time from an Instant using plusSeconds() or minusMillis().