Java Instant Examples

1. Overview

In this tutorial, you'll learn what is instance class in java and how to create an object for Instant class.

This class models a single instantaneous point on the time-line. This might be used to record event time-stamps in the application.

Instant class holds the date time value with nano seconds so it requires the storage of a number larger than a long. To achieve this, the class stores a long representing epoch-seconds and an int representing nanosecond-of-second, which will always be between 0 and 999,999,999.

 

The epoch seconds are measured from the standard Java epoch of 1970-01-01T00:00:00Z value where instants after the epoch have positive values, and earlier instants have negative values.

This class has three constants fields such as EPOCH, MIN, MAX.

2. Instant Class Methods

public static Instant now(): it is used to get the current date and time in Instance object. This value is optained from system clock.

Temporal adjustInto(Temporal temporal): It is used to adjust the specified temporal object to have this instant.

int get(TemporalField field): It is used to get the value of the specified field from this instant as an int.

boolean isSupported(TemporalField field): It is used to check if the specified field is supported.

Instant minus(TemporalAmount amountToSubtract): It is used to return a copy of this instant with the 

specified amount subtracted.

static Instant parse(CharSequence text): It is used to obtain an instance of Instant from a text string such as 2007-12-03T10:15:30.00Z.

Instant plus(TemporalAmount amountToAdd): It is used to return a copy of this instant with the specified amount added.

Instant with(TemporalAdjuster adjuster): It is used to return an adjusted copy of this instant.

3. Java Instant Examples

3.1 Instant Object Creation

Use now() method to get the object for Instant class from current system time.

package com.javaprogramto.java8.dates.instant;

import java.time.Instant;

public class InstantCreationExample {

	public static void main(String[] args) {

		// Creating instant object from now()
		Instant instant1 = Instant.now();
		System.out.println("Instant 1 value from now() - " + instant1);

		Instant instant2 = Instant.now();
		System.out.println("Instant 2 value from now() - " + instant2);
	}
}
 

Output:

Instant 1 value from now() - 2020-11-29T13:35:31.836392Z
Instant 2 value from now() - 2020-11-29T13:35:31.849851Z
 

3.2 Creating Instant From String - parse()

We can convert a String value to Instant object using Instant.parse() method. This parse() method takes string argument.

package com.javaprogramto.java8.dates.instant;

import java.time.Instant;

public class InstantParseExample {
	public static void main(String[] args) {

		// Creating instant object from parse()
		Instant instantFromStr1 = Instant.parse("2020-11-29T13:35:30.01Z");
		System.out.println("Instant 1 from string using parse() : " + instantFromStr1);

		Instant instantFromStr2 = Instant.parse("2020-12-29T13:35:31.00Z");
		System.out.println("Instant 2 from string using parse() : " + instantFromStr2);
	}
}
 

Output:

Instant 1 from string using parse() : 2020-11-29T13:35:30.010Z
Instant 2 from string using parse() : 2020-12-29T13:35:31Z
 

3.3 Create Instant from Epoch Second Value

Use ofEpochMilli() method to convert long epoch second value to Instant object.

package com.javaprogramto.java8.dates.instant;

import java.time.Instant;

public class InstantEpochSecondExample {
	public static void main(String[] args) {

		// Creating instant object from ofEpochMilli()
		Instant instantFromEpochSecond1 = Instant.ofEpochMilli(1606657474l);
		System.out.println("Instant 1 from Epoch Second value using  ofEpochMilli() : " + instantFromEpochSecond1);

		Instant instantFromEpochSecond2 = Instant.ofEpochMilli(1667137474l);
		System.out.println("Instant 2 from Epoch Second value using  ofEpochMilli() : " + instantFromEpochSecond2);
	}
}
 

Output:

Instant 1 from Epoch Second value using  ofEpochMilli() : 1970-01-19T14:17:37.474Z
Instant 2 from Epoch Second value using  ofEpochMilli() : 1970-01-20T07:05:37.474Z
 

3.4 Convert Instant to Long value

Use getEpochSecond() method to get the epoch second value from the existing instant object.

package com.javaprogramto.java8.dates.instant;

import java.time.Instant;

public class InstantGetEpochExample {
	public static void main(String[] args) {

		// Creating instant object from now()
		Instant instant1 = Instant.now();
		
		// Getting long value in epoch style from instant object
		long epoch1 = instant1.getEpochSecond();
		System.out.println("Instant 1 "+instant1);
		System.out.println("epoch 1 "+epoch1);

		// Another example to get the epoch value
		Instant instant2 = Instant.now();
		long epoch2 = instant2.getEpochSecond();
		System.out.println("Instant 2 "+instant2);
		System.out.println("epoch 2 "+epoch2);
	}
}
 

Output:

Instant 1 2020-11-29T13:56:40.849772Z
epoch 1 1606658200
Instant 2 2020-11-29T13:56:40.862042Z
epoch 2 1606658200
 

3.5 Adding n Time Units to Instant

Use plus() method to add a specific amount of time unit to the existing instant object.

package com.javaprogramto.java8.dates.instant;

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

public class InstantPlusExample {
	public static void main(String[] args) {

		// Creating instant object from string using parse()
		Instant instant1 = Instant.parse("2020-11-29T13:56:40.11Z");

		// Adding 60 seconds
		Instant addedSeconds = instant1.plus(60l, ChronoUnit.SECONDS);
		System.out.println("Added 60 seconds : " + addedSeconds);

		// Another example to add 60 minutes
		Instant instant2 = Instant.parse("2020-11-29T13:56:40.11Z");

		// Adding 60 minutes
		Instant addedMinutes = instant2.plus(60l, ChronoUnit.MINUTES);
		System.out.println("Added 60 Minutues : " + addedMinutes);
	}
}
 

Output:

Added 60 seconds : 2020-11-29T13:57:40.110Z
Added 60 Minutues : 2020-11-29T14:56:40.110Z
 

3.6 Subtracting n Time Units from Instant

Use minus() method to subtract n number of a specific time units.

package com.javaprogramto.java8.dates.instant;

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

public class InstantMinusExample {
	public static void main(String[] args) {

		// Creating instant object from string using parse()
		Instant instant1 = Instant.parse("2020-11-29T13:56:40.11Z");

		// Removing 60 seconds
		Instant addedSeconds = instant1.minus(60l, ChronoUnit.SECONDS);
		System.out.println("Minus 60 seconds : " + addedSeconds);

		// Another example to add 60 minutes
		Instant instant2 = Instant.parse("2020-11-29T13:56:40.11Z");

		// Subtracting 60 minutes
		Instant addedMinutes = instant2.minus(60l, ChronoUnit.MINUTES);
		System.out.println("Minus 60 Minutues : " + addedMinutes);
	}
}
 

Output:

Minus 60 seconds : 2020-11-29T13:55:40.110Z
Minus 60 Minutues : 2020-11-29T12:56:40.110Z
 

3.7 Comparing Instant Objects

Use equals() method to compare two Instance objects. And also we can use isAfter() and isBefore() methods to check if the instance 1 is before or after another Instance 2.

package com.javaprogramto.java8.dates.instant;

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

public class ComoareInstancesExample {
	public static void main(String[] args) {

		// Creating instant object 1
		Instant instant1 = Instant.parse("2020-11-29T13:56:40.11Z");

		// Creating instant object 2
		Instant instant2 = Instant.parse("2022-11-30T13:56:40.11Z");

		// comparing two instants using equals() method
		boolean isEquals = instant1.equals(instant2);
		
		if(isEquals) {
			System.out.println("instant1 & instant2 are same");
		} else {
			System.out.println("instant1 & instant2 are not same");
		}
		
		// comparing Instants using isAfter()
		boolean isAfter = instant1.isAfter(instant2);
		
		if(isAfter) {
			System.out.println("instant1 is after instant2");
		} else {
			System.out.println("instant1 is not after instant2");
		}
		
		// comparing Instants using isBefore()
		boolean isBefore = instant1.isBefore(instant2);
		
		if(isBefore) {
			System.out.println("instant1 is before instant2");
		} else {
			System.out.println("instant1 is not before instant2");
		}
	}
}
 

Output:

instant1 & instant2 are not same
instant1 is not after instant2
instant1 is before instant2
 

4. Conclusion

In this article, You've seen how to use Instant class to work with the precise time lines and what are the methods needed to work with Instance objects.

GitHub

Instant API

Java 8 - How to convert Date to String? (LocalDateTime, LocalDate, LocalTime)