Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Date and Time

The Duration class

Reference for java.time.Duration: amounts of time in seconds and nanoseconds, creating, adding, converting to hours and minutes, parsing ISO text and negative values.

java.time.Duration is an amount of time measured in seconds and nanoseconds, such as "1 hour and 30 minutes" or "250 milliseconds". It does not know about calendars: a day is exactly 24 hours and a duration is not tied to a start date. Use it for timeouts, elapsed time, delays and time-based differences between times or instants.

Its text form follows ISO-8601, PT1H30M (P for period, T for time part). The class is immutable. A duration can be negative; Duration.between(a, b) is negative when b is before a. For amounts in years, months and days, use Period.

Java
Duration d = Duration.ofMinutes(90);
long hours = d.toHours(); // 1

Try it

Java Creating and breaking down a duration

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Arithmetic, comparison and negatives

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public final class Duration implements TemporalAmount, Comparable<Duration>, Serializable
Member Description
ofDays(long), ofHours(long), ofMinutes(long), ofSeconds(long), ofMillis(long), ofNanos(long) Factory methods; ofSeconds(long, long) adds a nanosecond adjustment.
of(long, TemporalUnit) Amount in a unit with an exact duration (not months or years).
between(Temporal, Temporal) Elapsed time from start to end.
parse(CharSequence) ISO text such as PT20.345S, PT15M, P2DT3H4M.
plus(Duration), minus(Duration), plusHours(long), ... Arithmetic.
multipliedBy(long), dividedBy(long), dividedBy(Duration) Scaling; the last returns a long ratio.
negated(), abs(), isNegative(), isZero() Sign handling.
getSeconds(), getNano() The stored values.
toDays(), toHours(), toMinutes(), toSeconds(), toMillis(), toNanos() Total amount in a unit (truncated).
toDaysPart(), toHoursPart(), toMinutesPart(), toSecondsPart(), toMillisPart() The component (since Java 9).
truncatedTo(TemporalUnit) Drops smaller units.

Throws: DateTimeParseException for bad text, ArithmeticException on overflow, UnsupportedTemporalTypeException for units of variable length.

Usage notes

  • Exact lengths only. A day counts as 24 hours. For "the same time on the next calendar day" use plusDays on a zoned date-time or a Period.
  • toHours() vs toHoursPart(). toHours() is the total number of whole hours; toHoursPart() is the hours component of the day (0 to 23), as on a clock display.
  • toString() of negative durations can look odd, such as PT-8H-30M, because each component carries its own sign. The text is valid ISO-8601 and parses back.
  • Measuring code: use System.nanoTime() or Instant pairs with Duration.between; do not print the result in tests since it varies.
  • Overnight spans: Duration.between(LocalTime, LocalTime) does not wrap past midnight; it returns a negative duration.
  • Timeouts: many APIs (CompletableFuture.orTimeout, HttpClient, Thread.sleep(Duration)) accept a Duration.
  • Fractional seconds are stored in nanoseconds; toMillis() truncates.
  • Mixing types: adding a Duration to a LocalDate throws UnsupportedTemporalTypeException; use Period.