The java.time.Instant class is part of new date and time API added in Java 8 that represents a single instantaneous point on the time-line.
Instant is stored in two fields, it 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 where instants after the epoch have positive values, and earlier instants have negative values. To initialize these two field there is a private constructor in the Java Instant class-
/**
* @param epochSecond the number of seconds from 1970-01-01T00:00:00Z
* @param nanos the nanoseconds within the second, must be positive
*/
private Instant(long epochSecond, int nanos) {
super();
this.seconds = epochSecond;
this.nanos = nanos;
}
Instant class is immutable thus thread-safe. Since it is marked as final so can’t be extended.
Creating instances of Instant
Instant class doesn’t have any public constructors to obtain an instance, you will use a factory method to get an instance.
1. now()– Obtains the current instant from the system clock.
Instant instant = Instant.now(); System.out.println(instant); //2019-11-07T05:21:04.464715600Z
2. now(Clock clock)– Obtains the current instant from the specified clock.
Instant instant = Instant.now(Clock.systemDefaultZone()); System.out.println(instant); //2019-11-07T05:36:01.210573Z
3. ofEpochMilli(long epochMilli)– Obtains an instance of Instant using milliseconds from the epoch of 1970-01-01T00:00:00Z.
Instant instant = Instant.ofEpochMilli(System.currentTimeMillis()); System.out.println(instant); //2019-11-07T05:39:27.853Z
4. ofEpochSecond(long epochSecond)– Obtains an instance of Instant using seconds from the epoch of 1970-01-01T00:00:00Z.
Instant instant = Instant.ofEpochSecond(System.currentTimeMillis()/1000); System.out.println(instant); //2019-11-07T05:39:27.853Z
5. ofEpochSecond(long epochSecond, long nanoAdjustment)– Obtains an instance of Instant using seconds from the epoch of 1970-01-01T00:00:00Z and nanosecond fraction of second.
Instant instant = Instant.ofEpochSecond(System.currentTimeMillis()/1000, 235); System.out.println(instant); //2019-11-07T05:40:55.000000235Z
6. parse(CharSequence text)- Obtains an instance of Instant from a text string such as 2007-12-03T10:15:30.00Z. Using parse method you can convert String to an Instant.
Instant instant = Instant.parse("2019-10-28T11:35:15Z");
System.out.println(instant); //2019-10-28T11:35:15Z
Getting epoch seconds and nano second values from Instant
Since Instant instance is stored in two fields; epochSecond and nanos so there are methods to extract these two fields from a java.time.Instant instance.
public class InsantExample {
public static void main(String[] args) {
Instant instant = Instant.parse("2019-10-28T11:35:15.245Z");
// epoch seconds
System.out.println(instant.getEpochSecond());
// Nanos
System.out.println(instant.getNano());
}
}
Output
1572262515 245000000
Time calculations using Instant
There are methods to add or subtract date and time values from an Instant.
Minus methods
- minus(long amountToSubtract, TemporalUnit unit)– Returns a copy of this instant with the specified amount subtracted.
- minus(TemporalAmount amountToSubtract)– Returns a copy of this instant with the specified amount subtracted.
- minusMillis(long millisToSubtract)– Returns a copy of this instant with the specified duration in milliseconds subtracted.
- minusNanos(long nanosToSubtract)– Returns a copy of this instant with the specified duration in nanoseconds subtracted.
- minusSeconds(long secondsToSubtract)– Returns a copy of this instant with the specified duration in seconds subtracted.
public class InsantExample {
public static void main(String[] args) {
Instant instant = Instant.parse("2019-10-28T11:35:15.245Z");
System.out.println("Instant- " + instant);
System.out.println("Instant second subtraction- " + instant.minusSeconds(15));
System.out.println("Instant millis subtraction- " + instant.minusMillis(2000));
System.out.println("Instant nanos subtraction- " + instant.minusNanos(45));
// Uses minus(long amountToSubtract, TemporalUnit unit)
System.out.println("Instant days subtraction- " + instant.minus(10, ChronoUnit.DAYS));
// Uses minus(TemporalAmount amountToSubtract)
System.out.println("Instant days subtraction- " + instant.minus(Period.ofDays(10)));
System.out.println("Instant Hours subtraction- " + instant.minus(Duration.ofHours(3)));
}
}
Output
Instant- 2019-10-28T11:35:15.245Z Instant second subtraction- 2019-10-28T11:35:00.245Z Instant millis subtraction- 2019-10-28T11:35:13.245Z Instant nanos subtraction- 2019-10-28T11:35:15.244999955Z Instant days subtraction- 2019-10-18T11:35:15.245Z Instant days subtraction- 2019-10-18T11:35:15.245Z Instant days subtraction- 2019-10-28T08:35:15.245Z
Plus methods
- plus(long amountToAdd, TemporalUnit unit)– Returns a copy of this instant with the specified amount added.
- plus(TemporalAmount amountToAdd)– Returns a copy of this instant with the specified amount added.
- plusMillis(long millisToAdd)– Returns a copy of this instant with the specified duration in milliseconds added.
- plusNanos(long nanosToAdd)– Returns a copy of this instant with the specified duration in nanoseconds added.
- plusSeconds(long secondsToAdd)– Returns a copy of this instant with the specified duration in seconds added.
public class InsantExample {
public static void main(String[] args) {
Instant instant = Instant.parse("2019-10-28T11:35:15.245Z");
System.out.println("Instant- " + instant);
System.out.println("Instant second addition- " + instant.plusSeconds(15));
System.out.println("Instant millis addition- " + instant.plusMillis(2000));
System.out.println("Instant nanos addition- " + instant.plusNanos(45));
// Uses plus(long amountToAdd, TemporalUnit unit)
System.out.println("Instant days addition- " + instant.plus(10, ChronoUnit.DAYS));
// Uses plus(TemporalAmount amountToAdd)
System.out.println("Instant days addition- " + instant.plus(Period.ofDays(10)));
System.out.println("Instant Hours addition- " + instant.plus(Duration.ofHours(3)));
}
}
Output
Instant- 2019-10-28T11:35:15.245Z Instant second addition- 2019-10-28T11:35:30.245Z Instant millis addition- 2019-10-28T11:35:17.245Z Instant nanos addition- 2019-10-28T11:35:15.245000045Z Instant days addition- 2019-11-07T11:35:15.245Z Instant days addition- 2019-11-07T11:35:15.245Z Instant Hours addition- 2019-10-28T14:35:15.245Z
Comparing two Instant Instances in Java
- compareTo(Instant otherInstant)– Compares this instant to the specified instant. Returns negative if less than the passes Instant instance, positive otherwise.
- equals(Object otherInstant)– Checks if this instant is equal to the specified instant. Returns true if the other instant is equal to this one.
- isAfter(Instant otherInstant)– Checks if this instant is after the specified instant.
- isBefore(Instant otherInstant)– Checks if this instant is before the specified instant.
public class InsantExample {
public static void main(String[] args) {
Instant instant1 = Instant.parse("2019-10-28T11:35:15.245Z");
System.out.println("Instant1- " + instant1);
Instant instant2 = Instant.parse("2019-09-22T16:25:10.245Z");
System.out.println("Instant2- " + instant2);
// Should return + value
System.out.println("Instant comparison- " + instant1.compareTo(instant2));
System.out.println("Instanct Instances equal- " + instant1.equals(instant2));
System.out.println("Instant After- " + instant1.isAfter(instant2));
System.out.println("Instant Before- " + instant1.isBefore(instant2));
}
}
Output
Instant1- 2019-10-28T11:35:15.245Z Instant2- 2019-09-22T16:25:10.245Z Instant comparison- 1 Instanct Instances equal- false Instant After- true Instant Before- false
Related Posts
- ZonedDateTime in Java With Examples
- java.time.Duration Class With Examples
- TemporalAdjusters Class in Java
- Java SimpleDateFormat Class
- Create a Date Object With Values in Java
- Java Program to Convert Date to LocalDate, LocalDateTime
- Java Program to Convert Between Time Zones
- Convert LocalDate to Date in Java
That’s all for the topic Instant in Java With Examples. If something is missing or you have something to share about the topic please write a comment.
You may also like
