Duration and Period

Two kinds of time intervals

The phrase “some time passed between these values” can mean different things. From 10:00 to 12:30, exactly two and a half hours passed. But “one month from now” is a calendar rule: the length of a month depends on the specific date. That is why Java separates these concepts into Duration and Period.

Duration is an exact duration

Duration describes an amount of time in seconds and nanoseconds. It is well suited for hours, minutes, seconds, and measuring the distance between instants.

Instant start = Instant.parse("2026-09-18T09:00:00Z");
Instant end = Instant.parse("2026-09-18T11:30:00Z");

Duration duration = Duration.between(start, end);
System.out.println(duration.toMinutes()); // 150

A duration can also be created explicitly:

Duration timeout = Duration.ofSeconds(30);
Duration cacheTtl = Duration.ofMinutes(10);

Period is a calendar period

Period stores years, months, and days. It is used when calendar logic matters rather than a fixed number of seconds.

LocalDate start = LocalDate.of(2026, 1, 31);
LocalDate next = start.plus(Period.ofMonths(1));

System.out.println(next); // 2026-02-28

Here, “one month” is not converted into an assumed 30 days. The operation follows calendar rules.

Why they should not be substituted for each other blindly

Duration.ofDays(1) means a duration of 24 hours. Period.ofDays(1) means “the next calendar day.” For local values without time-zone transitions, the result often looks the same, but in zones with clock changes the meaning can differ.

Both classes are immutable and can be used with plus() and minus() on compatible temporal types.