The Duration class is meant to represent an amount of time using time-based values (hours, minutes, seconds, or nanoseconds). This duration of time can be obtained in different ways. For example, a duration of 10 hours can be obtained as follows:

Duration fromHours = Duration.ofHours(10); // PT10H

Alternatively, a duration of 3 minutes can be obtained via the of() method, as follows:

Duration fromMinutes = Duration.of(3, ChronoUnit.MINUTES); // PT3M

Duration can also be obtained from LocalDateTime:

LocalDateTime localDateTime 
  = LocalDateTime.of(2018, 3, 12, 4, 14, 20, 670);

// PT14M
Duration fromLocalDateTime 
  = Duration.ofMinutes(localDateTime.getMinute());

It can also be obtained from LocalTime:

LocalTime localTime = LocalTime.of(4, 14, 20, 670);

// PT0.00000067S
Duration fromLocalTime = Duration.ofNanos(localTime.getNano());

Finally, Duration can be obtained from a String object that respects the ISO-8601 duration format PnDTnHnMn.nS, with days considered to be exactly 24 hours. For example, the P2DT3H4M string has 2 days, 3 hours, and 4 minutes:

Duration durationFromString = Duration.parse("P2DT3H4M");

But, as in the case of Period, the real power of Duration is revealed when it is used to represent a period of time between two times (for example, Instant). The duration of time between November 3, 2015, 12:11:30, and December 6, 2016, 15:17:10, can be represented as the difference between two Instant classes, as follows:

Instant startInstant = Instant.parse("2015-11-03T12:11:30.00Z");
Instant endInstant = Instant.parse("2016-12-06T15:17:10.00Z");

// PT10059H5M40S
Duration durationBetweenInstant 
  = Duration.between(startInstant, endInstant);

In seconds, this difference can be obtained via the Duration.getSeconds() method:

durationBetweenInstant.getSeconds(); // 36212740 seconds

Or, the duration of time between March 12, 2018, 04:14:20.000000670 and July 20, 2019, 06:10:10.000000720, can be represented as the difference between two LocalDateTime objects, as follows:

LocalDateTime startLocalDateTime 
  = LocalDateTime.of(2018, 3, 12, 4, 14, 20, 670);
LocalDateTime endLocalDateTime 
  = LocalDateTime.of(2019, 7, 20, 6, 10, 10, 720);
// PT11881H55M50.00000005S, or 42774950 seconds
Duration durationBetweenLDT 
  = Duration.between(startLocalDateTime, endLocalDateTime);

Finally, the duration of time between 04:14:20.000000670 and 06:10:10.000000720, can be represented as the difference between two LocalTime objects, as follows:

LocalTime startLocalTime = LocalTime.of(4, 14, 20, 670);
LocalTime endLocalTime = LocalTime.of(6, 10, 10, 720);

// PT1H55M50.00000005S, or 6950 seconds
Duration durationBetweenLT 
  = Duration.between(startLocalTime, endLocalTime);

In the preceding examples, Duration was expressed in seconds via the Duration.getSeconds() method—this is the number of seconds in the Duration class. However, the Duration class contains a set of methods that are dedicated to expressing Duration in other time units—in days via toDays(), in hours via toHours(), in minutes via toMinutes(), in milliseconds via toMillis(), and in nanoseconds via toNanos().

Converting from one unit of time to another unit of time may result in a remnant. For example, converting from seconds to minutes may result in a remnant of seconds (for example, 65 seconds is 1 minute and 5 seconds (5 seconds is the remnant)). The remnant can be obtained via the following set of methods—the remnant in days via toDaysPart(), the remnant in hours via toHoursPart(), the remnant in minutes via toMinutesPart(), and so on.

Let's assume that the difference should be displayed as days:hours:minutes:seconds:nano (for example, 9d:2h:15m:20s:230n). Joining the forces of the toFoo() and toFooPart() methods in a helper method will result in the following code:

public static String durationToDHMSN(Duration duration) {

  StringBuilder sb = new StringBuilder();
  sb.append(duration.toDays())
    .append("d:")
    .append(duration.toHoursPart())
    .append("h:")
    .append(duration.toMinutesPart())
    .append("m:")
    .append(duration.toSecondsPart())
    .append("s:")
    .append(duration.toNanosPart())
    .append("n");

  return sb.toString();
}

Let's call this method durationBetweenLDT (the difference is 495 days, 1 hour, 55 minutes, 50 seconds, and 50 nanoseconds):

// 495d:1h:55m:50s:50n
durationToDHMSN(durationBetweenLDT);

Identical to the Period class, the Duration class has a flag method named isNegative(). This method is useful when determining whether a particular time is earlier than another time. Having duration A and duration B, the result of applying Duration.between(A, B) can be negative if B is before A, or positive if A is before B. Taking the logic further, isNegative()  returns true if B is before A, or false if A is before B, as in the following case:

durationBetweenLT.isNegative(); // false

Finally, Duration can be modified by adding or subtracting a duration of time. There are methods such as plusDays(), plusHours(), plusMinutes(), plusMillis(), plusNanos(), minusDays(), minusHours(), minusMinutes(), minusMillis(), and minusNanos() to perform this. For example, adding 5 hours to durationBetweenLT can be done as follows:

Duration durationBetweenPlus5Hours = durationBetweenLT.plusHours(5);

Adding two Duration classes can be accomplished via the Duration.plus() method, as follows:

Duration d1 = Duration.ofMinutes(20);
Duration d2 = Duration.ofHours(2);

Duration d1d2 = d1.plus(d2);

System.out.println(d1 + "+" + d2 + "=" + d1d2); // PT2H20M