Duration Class in Java

Post author:Noel Kamphoa
Post published:May 13, 2024
Post category:Core Java Tutorials / Java Entry Level / Text, Date, Time, and Numeric Objects

1. Introduction

Java 8 introduced, through JSR 310, a complete overhaul of the Date/Time API by providing new, more advanced classes for Date processing. Duration is one such class that we will focus on in this article.

2. What is a Duration?

Duration is a class from the java.time package, which models a time-based amount of time, such as ‘2 hours’. The class represents a quantity or amount of time in terms of days, hours, minutes, seconds, or nanoseconds.
The Period class is date-based equivalent to this class.

The main particularity of Duration is that it is immutable and thread-safe.

3. Creating a Duration

3.1. Duration.ofXXX()

You can create a Duration object with any of the Duration.ofXXX() methods.

        Duration ofDays = Duration.ofDays(1);//PT24H
        Duration ofHours = Duration.ofHours(1);//PT1H
        Duration ofMinutes = Duration.ofMinutes(1);//PT1M
        Duration ofSeconds = Duration.ofSeconds(1);//PT1S
        Duration ofMillis = Duration.ofMillis(1);//PT0.001S
        Duration ofNanos = Duration.ofNanos(1);//PT0.000000001S

Additionally, you can use the generic Duration.of() method with a TemporalUnit parameter. The TemporalUnit object must have an exact duration (see Duration.isDurationEstimated()) or be ChronoUnit.DAYS.

        Duration ofDays = Duration.of(1,ChronoUnit.DAYS);//PT24H
        Duration ofHours = Duration.of(1,ChronoUnit.HOURS);//PT1H
        Duration ofMinutes = Duration.of(1,ChronoUnit.MINUTES);//PT1M
        Duration ofSeconds = Duration.of(1,ChronoUnit.SECONDS);//PT1S
        Duration ofMillis = Duration.of(1,ChronoUnit.MILLIS);//PT0.001S
        Duration ofNanos = Duration.of(1,ChronoUnit.NANOS);//PT0.000000001S

If the TemporalUnit you provide does not have an exact duration as described above, an UnsupportedTemporalTypeException is thrown:

        Duration incorrectDuration = Duration.of(1,ChronoUnit.MONTHS);//UnsupportedTemporalTypeException

3.2. Parsing from String to Duration

Assuming that you have a Duration in ISO-8601 format and want to build a Duration out of it, you can use the parse() method in this way:

        String myDuration = "PT24H";// ISO-8601 Duration format
        Duration duration = Duration.parse(myDuration);// PT24H

A Duration can be negative as well:

        String myDuration = "PT-24H";// ISO-8601 Duration format
        Duration duration = Duration.parse(myDuration);// PT-24H

The accepted ISO-8601 duration format is as follows: PnDTnHnMn.nS.
In the above format, “n” is an integer; D, H, M, and S are suffixes. Check out the detailed information about the duration ISO-8601 format here.

Any days input is treated as a duration of exactly 24 hours:

        String myDuration = "P2D";// ISO-8601 Duration format
        Duration duration = Duration.parse(myDuration);// PT48H (not P2D)

Java will throw a DateTimeParseException if it is not able to parse the String with the given time format.

    String myDuration = "PT24n";// Incorrect format
    Duration duration = Duration.parse(myDuration);// DateTimeParseException

3.3. Difference between two Temporal Objects

You can obtain a Duration as the difference between two Temporal objects:

        LocalTime firstTime = LocalTime.of(13,30);//13:30
        LocalTime secondTime = LocalTime.of(14,30);//14:30
        Duration duration = Duration.between(firstTime,secondTime);//PT1H

4. Operating on a Duration

4.1. Comparing two Duration objects

Since the Duration class implements the Comparable<E> interface, you may use the compareTo() method:

        Duration firstDuration = Duration.of(1,ChronoUnit.DAYS);
        Duration secondDuration = Duration.of(1,ChronoUnit.HOURS);
        Duration thirdDuration = Duration.of(2,ChronoUnit.DAYS);
        int test1 = firstDuration.compareTo(secondDuration);// A positive number
        int test2 = firstDuration.compareTo(thirdDuration);// A negative number

Furthermore, you should know that the Duration class also overrides the equals() method and provides a convenient way to check the equality of two Duration objects:

        Duration firstDuration = Duration.of(1,ChronoUnit.DAYS);
        Duration secondDuration = Duration.of(24,ChronoUnit.HOURS);
        Duration thirdDuration = Duration.of(1,ChronoUnit.DAYS);
        boolean test1 = firstDuration.equals(secondDuration);// true
        boolean test2 = firstDuration.equals(thirdDuration);// true

4.2. Temporal Arithmetic with Duration Objects

The Duration class provides plusXXX() and minusXXX() methods to increment and decrement the object field values. Since the Duration is immutable, all these methods return a copy of the original object with the given fields updated.

        Duration duration = Duration.of(1,ChronoUnit.DAYS);//PT24H
        Duration plusDays = duration.plusDays(1);//PT48H
        Duration minusDays = duration.minusDays(1);//PT0S
        Duration plusHours = duration.plusHours(1);//PT25H
        Duration minusHours = duration.minusHours(1);//PT23H
        Duration plusMinutes = duration.plusMinutes(1);//PT24H1M
        Duration minusMinutes = duration.minusMinutes(1);//PT23H59M
        Duration plusSeconds = duration.plusSeconds(1);//PT24H1S
        Duration minusSeconds = duration.minusSeconds(1);//PT23H59M59S

You can also use the plus() and minus() to add and subtract two Duration objects directly:

        Duration duration = Duration.of(1,ChronoUnit.DAYS);//PT24H
        Duration toAdd = Duration.of(1,ChronoUnit.HOURS);//PT1H
        Duration addedDuration = duration.plus(toAdd);//PT25H
        Duration subtractedDuration = duration.minus(toAdd);//PT23H

Lastly, the plus() and minus() methods have overloaded versions that accept a long and a TemporalUnit:

        Duration duration = Duration.of(1,ChronoUnit.DAYS);//PT24H
        Duration addedDuration = duration.plus(1, ChronoUnit.HOURS);//PT25H
        Duration substractedDuration = duration.minus(1, ChronoUnit.HOURS);//PT23H