Instant in Java With Examples

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

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

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.