Duration represents a precise, time-based span — so many seconds and nanoseconds — the exact counterpart to Period's calendar-based amounts. It is the class for anything measured in fixed units that never change meaning depending on context: an API's response time, a video's playback length, how long a batch job took to run. Introduced in Java 8 alongside Period, Duration is immutable, and unlike Period, it implements Comparable<Duration> directly — two durations can always be meaningfully compared, because a second is a second no matter where it falls on the calendar.

What Is Duration?

java.time.Duration stores a span of time internally as a whole number of seconds plus a nanosecond adjustment, giving it precision down to a single nanosecond. Unlike Period, it has no concept of years, months, or calendar days at all — Duration.ofDays(1) is defined as exactly 24 hours, which is a genuinely different thing from a calendar day, since a calendar day can be 23 or 25 hours long across a daylight saving transition.

Duration.between() computes the gap between two Temporal values that support time-based measurement — Instant, LocalTime, LocalDateTime, ZonedDateTime. Duration.of(), ofSeconds(), ofMinutes(), ofHours(), and ofDays() construct one directly, with no dates or times involved at all.

One sentence before the diagram: Period and Duration model the same general idea — an amount of time — from two genuinely different angles.

Period                              Duration
-------                             --------
years, months, days                 seconds, nanoseconds
"1 month" varies in real length     "24 hours" is always 24 real hours
applies to LocalDate/LocalDateTime  applies to Instant/LocalTime/
                                     LocalDateTime/ZonedDateTime
not Comparable                      implements Comparable<Duration>

Period.ofDays(1)  != always 24 hours (calendar day can be 23-25h across DST)
Duration.ofDays(1) == always exactly 24 hours, no exceptions

Duration always normalizes into the same internal seconds-plus-nanoseconds representation regardless of which factory method built it, which is exactly why equals() correctly reports two differently-constructed but equal-length durations as equal — unlike Period, whose equals() compares raw stored fields.

Why Duration Was Introduced

Before Java 8, measuring or representing an elapsed span of time usually meant a raw long holding a millisecond count, with nothing in the type system saying what unit that number was actually in.

Java

Try it out

// File: BeforeDuration.java

public class BeforeDuration {
    public static void main(String[] args) {
        long requestStartMillis = 1000L;
        long requestEndMillis = 1450L;

        // Just a raw number - nothing here says "this is milliseconds"
        // to anyone reading the variable at a random point in the codebase
        long elapsedMillis = requestEndMillis - requestStartMillis;

        System.out.println("Elapsed: " + elapsedMillis + " ms");
    }
}

Output:
Elapsed: 450 ms

Duration gives that same 450 milliseconds an actual type, one that carries its own unit and prints in a form that is impossible to misread as the wrong scale.

Java

Try it out

// File: AfterDuration.java
import java.time.*;

public class AfterDuration {
    public static void main(String[] args) {
        Duration elapsed = Duration.ofMillis(450);

        System.out.println("Elapsed: " + elapsed.toMillis() + " ms");
        System.out.println("As a Duration: " + elapsed);
    }
}

Output:
Elapsed: 450 ms
As a Duration: PT0.45S

Both versions represent the same 450-millisecond span. Only the second one can never be silently added to a value measured in a different unit without a compile error somewhere along the way.

Syntax

Duration can be built from an explicit ChronoUnit, or from one of several convenience factory methods, and it breaks back down into hours, minutes, and seconds cleanly.

Java

Try it out

// File: DurationSyntaxForms.java
import java.time.*;
import java.time.temporal.*;

public class DurationSyntaxForms {
    public static void main(String[] args) {
        Duration fromUnit = Duration.of(90, ChronoUnit.MINUTES);
        Duration fromSeconds = Duration.ofSeconds(5400);
        Duration fromHours = Duration.ofHours(2);

        System.out.println("of(90, MINUTES): " + fromUnit);
        System.out.println("ofSeconds(5400): " + fromSeconds);
        System.out.println("ofHours(2): " + fromHours);

        Duration combined = fromUnit.plus(fromHours);
        System.out.println("fromUnit.plus(fromHours): " + combined);

        System.out.println("Hours part: " + combined.toHoursPart());
        System.out.println("Minutes part: " + combined.toMinutesPart());
        System.out.println("Total minutes: " + combined.toMinutes());

        Duration doubled = fromHours.multipliedBy(2);
        System.out.println("fromHours.multipliedBy(2): " + doubled);

        // Duration implements Comparable, unlike Period
        System.out.println("fromUnit.compareTo(fromHours): " + fromUnit.compareTo(fromHours));
    }
}

Output:
of(90, MINUTES): PT1H30M
ofSeconds(5400): PT1H30M
ofHours(2): PT2H
fromUnit.plus(fromHours): PT3H30M
Hours part: 3
Minutes part: 30
Total minutes: 210
fromHours.multipliedBy(2): PT4H
fromUnit.compareTo(fromHours): -1

fromUnit and fromSeconds were constructed two completely different ways, yet both print identically — Duration always normalizes into the same internal seconds-and-nanoseconds representation, regardless of how it was built.

Common Use Cases

Comparing a Measured Duration Against a Threshold

compareTo() lets a Duration be checked directly against a configured limit, with no manual unit conversion needed on either side.

Java

Try it out

// File: DurationComparisonExample.java
import java.time.*;

public class DurationComparisonExample {
    public static void main(String[] args) {
        Duration sla = Duration.ofMillis(500);
        Duration actualResponseTime = Duration.ofMillis(320);

        boolean withinSla = actualResponseTime.compareTo(sla) <= 0;

        System.out.println("Within SLA: " + withinSla);
    }
}

Output:
Within SLA: true

Formatting a Duration for Display

toHours(), toMinutesPart(), and toSecondsPart() combine into a readable "Xh Ym Zs" style breakdown that a stopwatch or video player would actually show.

Java

Try it out

// File: DurationFormattingExample.java
import java.time.*;

public class DurationFormattingExample {
    public static void main(String[] args) {
        Duration videoLength = Duration.ofSeconds(5025);

        String formatted = videoLength.toHours() + "h "
            + videoLength.toMinutesPart() + "m "
            + videoLength.toSecondsPart() + "s";

        System.out.println(formatted);
    }
}

Output:
1h 23m 45s

Computing a Deadline From a Timeout

Instant.plus(Duration) is the standard way to compute a precise deadline moment from a fixed timeout span, distinct from applying a Period to a LocalDate.

Java

Try it out

// File: TimeoutDeadlineExample.java
import java.time.*;

public class TimeoutDeadlineExample {
    public static void main(String[] args) {
        Instant requestReceivedAt = Instant.parse("2026-08-25T09:00:00Z");
        Duration timeout = Duration.ofSeconds(30);

        Instant deadline = requestReceivedAt.plus(timeout);

        System.out.println("Deadline: " + deadline);
    }
}

Output:
Deadline: 2026-08-25T09:00:30Z

Validating a Measured Duration Before Trusting It

isNegative() and isZero() catch an invalid measurement immediately, before a negative or empty span causes confusing downstream behavior.

Java

Try it out

// File: DurationZeroValidationExample.java
import java.time.*;

public class DurationZeroValidationExample {
    public static void main(String[] args) {
        Instant start = Instant.parse("2026-08-25T09:00:10Z");
        Instant end = Instant.parse("2026-08-25T09:00:05Z");

        Duration measured = Duration.between(start, end);

        if (measured.isNegative()) {
            System.out.println("Invalid measurement: end occurred before start");
        } else if (measured.isZero()) {
            System.out.println("No time elapsed");
        } else {
            System.out.println("Elapsed: " + measured);
        }
    }
}

Output:
Invalid measurement: end occurred before start

Real-World Example

A backend monitoring service tracks how long each API endpoint takes to respond and flags any request that exceeds that endpoint's configured SLA threshold. Comparing a measured response time against a threshold is exactly the kind of check Duration's Comparable implementation was built for — no manual unit conversion, no risk of comparing milliseconds against a threshold configured in a different unit.

Java

Try it out

// File: EndpointSla.java
import java.time.*;

public record EndpointSla(String endpointName, Duration maxAllowedDuration) {}

Java

Try it out

// File: SlaCheckResult.java
import java.time.*;

public record SlaCheckResult(String endpointName, Duration actualDuration, boolean withinSla) {}

Java

Try it out

// File: ResponseTimeMonitor.java
import java.time.*;

public class ResponseTimeMonitor {

    public SlaCheckResult checkResponse(EndpointSla sla, Instant requestStart, Instant requestEnd) {
        Duration actualDuration = Duration.between(requestStart, requestEnd);
        boolean withinSla = actualDuration.compareTo(sla.maxAllowedDuration()) <= 0;

        return new SlaCheckResult(sla.endpointName(), actualDuration, withinSla);
    }
}

Java

Try it out

// File: SlaMonitorDemo.java
import java.time.*;

public class SlaMonitorDemo {
    public static void main(String[] args) {
        EndpointSla checkoutSla = new EndpointSla("/api/checkout", Duration.ofMillis(500));

        ResponseTimeMonitor monitor = new ResponseTimeMonitor();

        Instant fastRequestStart = Instant.parse("2026-08-25T09:00:00.000Z");
        Instant fastRequestEnd = Instant.parse("2026-08-25T09:00:00.320Z");

        Instant slowRequestStart = Instant.parse("2026-08-25T09:05:00.000Z");
        Instant slowRequestEnd = Instant.parse("2026-08-25T09:05:00.780Z");

        SlaCheckResult fastResult = monitor.checkResponse(checkoutSla, fastRequestStart, fastRequestEnd);
        SlaCheckResult slowResult = monitor.checkResponse(checkoutSla, slowRequestStart, slowRequestEnd);

        System.out.println(fastResult.endpointName() + " took " + fastResult.actualDuration().toMillis()
            + "ms, within SLA: " + fastResult.withinSla());
        System.out.println(slowResult.endpointName() + " took " + slowResult.actualDuration().toMillis()
            + "ms, within SLA: " + slowResult.withinSla());
    }
}

Output:
/api/checkout took 320ms, within SLA: true
/api/checkout took 780ms, within SLA: false

A mistake that appears often in fresher pull requests is comparing response times as raw long millisecond values pulled from timestamp differences, which compiles and runs fine right up until someone on the team accidentally compares a value measured in milliseconds against a threshold configured in seconds. Duration.compareTo() against a Duration-typed SLA threshold makes that entire category of unit-mismatch bug impossible to introduce in the first place.

Combining Duration With Other Features

Duration.between() works with any Temporal that supports time-based measurement — Instant, LocalTime, LocalDateTime, ZonedDateTime — each covered elsewhere in this series. Unlike Period, Duration implements Comparable<Duration> directly, which is exactly what makes SLA-style threshold checks possible with a single compareTo() call instead of an awkward workaround. Instant.plus(Duration) and Instant.minus(Duration) are the standard way to compute a deadline or an expiry moment from a fixed, precise span, distinct from LocalDate.plus(Period), which computes a calendar-relative one instead.

Best Practices

Use Duration for anything measured or configured in fixed units — timeouts, SLA thresholds, retry delays, cache expiry windows — and reach for Period only when the amount is genuinely calendar-relative.

Compare Duration values with compareTo(), isZero(), or isNegative() rather than converting both sides to a raw long and comparing manually, since that reintroduces exactly the unit-mismatch risk Duration exists to eliminate.

Store Duration as configuration wherever an application needs a tunable timeout or threshold, rather than a raw number whose unit lives only in a comment or a variable name that someone eventually stops trusting.

Reach for toMillis() or toNanos() only at the boundary where an older API genuinely requires a raw long, and keep every internal representation as a real Duration otherwise.

Common Mistakes

Assuming Duration.ofDays(1) behaves like a calendar day overlooks that it is defined as exactly 24 hours, while a calendar day can be 23 or 25 hours long across a daylight saving transition.

Java

Try it out

// File: DurationVsPeriodDstMistake.java
import java.time.*;

public class DurationVsPeriodDstMistake {
    public static void main(String[] args) {
        // March 8, 2026 is the day US clocks spring forward for daylight
        // saving time - that specific calendar day only has 23 real hours
        ZonedDateTime start = ZonedDateTime.of(2026, 3, 8, 0, 0, 0, 0, ZoneId.of("America/New_York"));

        ZonedDateTime plusOneCalendarDay = start.plus(Period.ofDays(1));
        ZonedDateTime plusOneExactDuration = start.plus(Duration.ofDays(1));

        System.out.println("Start: " + start);
        System.out.println("Plus Period.ofDays(1): " + plusOneCalendarDay);
        System.out.println("Plus Duration.ofDays(1): " + plusOneExactDuration);
    }
}

Output:
Start: 2026-03-08T00:00-05:00[America/New_York]
Plus Period.ofDays(1): 2026-03-09T00:00-04:00[America/New_York]
Plus Duration.ofDays(1): 2026-03-09T01:00-04:00[America/New_York]

Period.ofDays(1) lands on midnight the next calendar day, exactly matching the wall clock. Duration.ofDays(1) adds a genuine 24 hours to the underlying instant, and because March 8th only had 23 real hours that year, the result lands a full hour later — 1:00 AM instead of midnight.

Assuming Duration behaves like Period, where two values with the same total length can still be unequal, is a natural but incorrect over-generalization once you already know Period's surprising equals() behavior.

Java

Try it out

// File: DurationNormalizationContrastMistake.java
import java.time.*;
import java.time.temporal.*;

public class DurationNormalizationContrastMistake {
    public static void main(String[] args) {
        Duration fromMinutes = Duration.ofMinutes(90);
        Duration fromSeconds = Duration.ofSeconds(5400);
        Duration fromUnit = Duration.of(90, ChronoUnit.MINUTES);

        // Unlike Period, Duration always normalizes to a single internal
        // seconds-plus-nanos representation, so equals() correctly reports
        // true for any two Durations covering the same total span
        System.out.println("fromMinutes.equals(fromSeconds): " + fromMinutes.equals(fromSeconds));
        System.out.println("fromMinutes.equals(fromUnit): " + fromMinutes.equals(fromUnit));
    }
}

Output:
fromMinutes.equals(fromSeconds): true
fromMinutes.equals(fromUnit): true

Trying to measure a gap between two LocalDate values with Duration.between() compiles fine, since LocalDate implements Temporal, but fails at runtime because LocalDate has no time-based unit for Duration to measure.

Java

Try it out

// File: DurationBetweenLocalDatesMistake.java
import java.time.*;
import java.time.temporal.*;

public class DurationBetweenLocalDatesMistake {
    public static void main(String[] args) {
        LocalDate start = LocalDate.of(2026, 1, 1);
        LocalDate end = LocalDate.of(2026, 6, 1);

        try {
            Duration.between(start, end);
        } catch (UnsupportedTemporalTypeException e) {
            System.out.println("UnsupportedTemporalTypeException - LocalDate has no time component for Duration to measure");
        }

        // Period.between() is the correct choice for two LocalDate values
        Period gap = Period.between(start, end);
        System.out.println("Period.between() works correctly: " + gap);
    }
}

Output:
UnsupportedTemporalTypeException - LocalDate has no time component for Duration to measure
Period.between() works correctly: P5M

Interview Questions

Q1. What is Duration, and how is it different from Period?

Duration represents a precise, time-based span measured in seconds and nanoseconds, with no concept of calendar units at all. Period represents a calendar-relative amount measured in years, months, and days, where the actual elapsed time varies depending on which dates it gets applied to. Duration.ofDays(1) is always exactly 24 hours; Period.ofDays(1) applied to a date lands on the same wall-clock time the next calendar day, which can occasionally be a different number of real hours away.

Q2. Does Duration implement Comparable? Why does that matter compared to Period?

Yes, Duration implements Comparable<Duration>, because a second has a fixed, unambiguous length regardless of context, making any two durations directly comparable. Period does not implement Comparable, because a month can be anywhere from 28 to 31 days, so "which is longer, one month or 31 days" has no single correct answer without applying both to an actual date. This distinction is a common follow-up once a candidate demonstrates knowing both classes exist.

Q3. Is Duration.ofDays(1) always exactly the same as a calendar day?

No. Duration.ofDays(1) is always exactly 24 hours, full stop. A calendar day can be 23 or 25 hours long on the specific day daylight saving time starts or ends in a zone that observes it, which is exactly why adding a Duration of one day to a ZonedDateTime can land at a different wall-clock time than adding a Period of one day would, as shown by the DST transition example in this article.

Q4. Why does Duration.between() throw an exception when called with two LocalDate values?

The call compiles because LocalDate implements the Temporal interface Duration.between() accepts, but it fails at runtime with UnsupportedTemporalTypeException, because LocalDate has no time-based unit like seconds for Duration to measure against — it is a date-only type. Period.between() is the correct method for measuring a gap between two LocalDate values.

Q5. Are two Duration objects built from different units, like ofMinutes(90) and ofSeconds(5400), considered equal?

Yes. Duration always normalizes into the same internal representation — total seconds plus a nanosecond adjustment — regardless of which factory method or unit was used to construct it, so equals() correctly reports true for any two Duration values covering the same total span. This is a deliberate contrast with Period, whose equals() compares raw stored fields and can report false for two periods with the same total length.

Q6. How would you compare a measured elapsed time against a configured SLA threshold?

Represent both the measurement and the threshold as Duration values, then call actualDuration.compareTo(thresholdDuration) <= 0 to check whether the measurement stayed within the limit. Keeping both sides as Duration rather than raw numbers eliminates the risk of comparing values measured in different units by mistake, exactly the pattern the SLA monitoring example in this article demonstrates.

FAQs

Can Duration represent a negative span of time?

Yes. Duration.between(start, end) returns a negative duration whenever end occurs before start, and isNegative() checks for exactly this case.

What is the difference between Duration.ofDays(1) applied to a ZonedDateTime and Period.ofDays(1) applied to the same value?

Duration.ofDays(1) adds exactly 24 real hours to the underlying instant, which can land at a different wall-clock time when the span crosses a daylight saving transition. Period.ofDays(1) advances the calendar date by one day and keeps the same wall-clock time, resolving to whatever offset applies on the new date. The two agree on ordinary days and differ specifically on the days daylight saving time starts or ends.

Does Duration support nanosecond precision?

Yes. Duration stores a nanosecond adjustment alongside its whole-second count, giving it precision down to a single nanosecond, though most everyday use only ever works with seconds or milliseconds.

Can Duration be added to a LocalDate?

No. LocalDate has no time-based fields for a Duration to apply to, so LocalDate.plus(Duration) does not exist as a method at all — Period is the correct type to add to a LocalDate.

What is Duration.ZERO?

A public static constant representing a duration of exactly zero seconds and zero nanoseconds, useful as a default value or a sentinel, and Duration.ZERO.isZero() always returns true.

How do I convert a Duration into a raw number of milliseconds for an older API?

Call toMillis(), which returns the total duration as a long number of milliseconds, or toNanos() for nanosecond precision. Both exist specifically as a bridge to older APIs that still expect a raw numeric time span rather than a Duration object.

Is Duration thread-safe?

Yes. Like every class in java.time, Duration is immutable, so a single instance can be shared freely across threads with no synchronization required, since nothing about it can ever change after it is created.

Summary

Duration gives a precise, fixed span of time its own type — seconds and nanoseconds, nothing calendar-relative about it — and because that span never changes meaning depending on context, Duration is the one java.time class among Period and its siblings that can be meaningfully compared directly with compareTo(). of() and its variants build one; plus(), minus(), and multipliedBy() combine them; and toHoursPart(), toMinutesPart(), and toSecondsPart() break one back down for display.

The habit worth carrying forward is reaching for Duration the moment a rule is genuinely fixed — a timeout, an SLA, a retry delay — and remembering that Duration.ofDays(1) is always 24 real hours, which is not always the same thing as "the next calendar day" once daylight saving time enters the picture. That single distinction, demonstrated concretely in this article's DST example, is exactly what separates Duration from Period in practice.

What to Read Next

Continue Learning Date & Time API

Next Step

DateTimeFormatter

Learn how to format dates and times for display.

→

LocalDateTime

Learn how to work with a date and time together.

→

Virtual Threads (Java 21)

Learn Java's lightweight threads built for massive concurrency.

→

LocalDate

Learn how to work with a calendar date, with no time or time zone.

→

←

PreviousPeriod

NextDateTimeFormatter

→