Java 101: Catching up with the Java Date and Time API

Get to know the java.time classes you're most likely to use in Java 8

Page 4 of 7

Getter methods for Instant and Duration

Instant and Duration declare several getter methods for reading their component fields and obtaining additional information. Instant's getter methods include the following:

  • long getEpochSecond() returns the number of seconds relative to the epoch.
  • int getNano() returns the number of nanoseconds past the last second.
  • boolean isAfter(Instant otherInstant) returns true when this Instant comes after the specified Instant.
  • boolean isBefore(Instant otherInstant) returns true when this Instant comes before the specified Instant.

Duration's getter methods include the following:

  • int getNano() returns the number of nanoseconds past the duration's last second.
  • long getSeconds() returns the number of seconds in the duration.
  • boolean isNegative() returns true when this Duration is negative.
  • boolean isZero() returns true when this Duration has zero length.

Listing 2. MachineTimeDemo.java (version 2)

import java.time.Duration;
import java.time.Instant;

public class MachineTimeDemo
{
   public static void main(String[] args)
   {
      Instant now = Instant.now();
      System.out.printf("Now = %s%n", now);
      System.out.printf("Epoch second = %d%n", now.getEpochSecond());
      System.out.printf("Nano = %d%n", now.getNano());
      System.out.printf("After epoch = %b%n", now.isAfter(Instant.EPOCH));
      System.out.printf("Before epoch = %b%n", now.isBefore(Instant.EPOCH));

      Duration dur = Duration.ofSeconds(49L-(long) (Math.random()*80));
      System.out.printf("Nano = %d%n", dur.getNano());
      System.out.printf("Seconds = %d%n", dur.getSeconds());
      System.out.printf("Is negative = %b%n", dur.isNegative());
      System.out.printf("Is zero = %b%n", dur.isZero());
   }
}

Compile Listing 2 and run it. Your output should be similar to the following:

Now = 2013-03-24T00:34:04.811Z
Epoch second = 1364085244
Nano = 811000000
After epoch = true
Before epoch = false
Nano = 0
Seconds = -18
Is negative = true
Is zero = false

Manipulating instant and duration instances

There are several methods for manipulating instances of Instant and Duration. Because these classes are immutable, the instances are not affected by these methods. Instead, copies of the instances with manipulated values will be returned.

Instant declares the following methods, which can be used to manipulate its instances:

  • Instant minusSeconds(long secondsToSubtract) returns a copy of the given Instant decreased by the specified number of seconds, which might be negative.
  • Instant plusNanos(long nanosToAdd) returns a copy of the given Instant increased by the specified number of nanoseconds, which might be negative.

Similar methods for Duration include the following:

  • Duration dividedBy(long divisor) returns a copy of the given Duration divided by the specified value.
  • Duration minusDays(long daysToSubtract) returns a copy of the given Duration decreased by the specified number of days, which might be negative.
  • Duration multipliedBy(long multiplicand) returns a copy of the given Duration multiplied by the specified value.
  • Duration plusHours(long hoursToAdd) returns a copy of the given Duration increased by the specified number of hours, which might be negative.
  • Duration withNanos(int nanoOfSecond) returns a copy of the given Duration with the specified number of nanoseconds. The number of seconds isn't affected.
  • Duration withSeconds(long seconds) returns a copy of the given Duration with the specified number of seconds. The number of nanoseconds isn't affected.

Listing 3 demonstrates these manipulation methods at work in MachineTimeDemo.java.

Listing 3. MachineTimeDemo.java (version 3)

import java.time.Duration;
import java.time.Instant;

public class MachineTimeDemo
{
   public static void main(String[] args)
   {
      Instant now = Instant.now();
      System.out.printf("Now = %s%n", now);
      System.out.printf("Now-20 seconds = %s%n", now.minusSeconds(20));
      System.out.printf("Now+500,000,000 nanoseconds = %s%n", now.plusNanos(500000000));

      Duration dur = Duration.ofDays(10);
      System.out.printf("Dur = %s%n", dur);
      System.out.printf("Dur/2 = %s%n", dur.dividedBy(2));
      System.out.printf("Dur-3 days = %s%n", dur.minusDays(3));
      System.out.printf("Dur*2 = %s%n", dur.multipliedBy(2));
      System.out.printf("Dur+12 hours = %s%n", dur.plusHours(12));
      System.out.printf("Dur nanos set to 500,000,000 = %s%n", dur.withNanos(500000000));
      System.out.printf("Dur seconds set to 3600 = %s%n", dur.withSeconds(3600));
   }
}

Compile Listing 3 and run the application. Your output should be similar to what's below:

Now = 2013-03-24T00:34:38.788Z
Now-20 seconds = 2013-03-24T00:34:18.788Z
Now+500,000,000 nanoseconds = 2013-03-24T00:34:39.288Z
Dur = PT240H
Dur/2 = PT120H
Dur-3 days = PT168H
Dur*2 = PT480H
Dur+12 hours = PT252H
Dur nanos set to 500,000,000 = PT240H0.5S
Dur seconds set to 3600 = PT1H
| 1 2 3 4 5 6 7 Page 4