Bird
Raised Fist0
JavaHow-ToBeginner · 4 min read

How to Use Duration and Period in Java: Simple Guide

In Java, Duration measures time-based amounts like seconds and nanoseconds, while Period measures date-based amounts like years, months, and days. Use Duration for time intervals and Period for calendar date differences.
📐

Syntax

Duration is used to represent time-based amounts, such as seconds or nanoseconds. You create it using methods like Duration.ofSeconds() or by calculating between two Instant or LocalTime objects.

Period represents date-based amounts, such as years, months, and days. You create it using Period.ofYears(), Period.ofMonths(), or by calculating between two LocalDate objects.

java
import java.time.Duration;
import java.time.Period;
import java.time.LocalDate;
import java.time.LocalTime;
import java.time.Instant;

// Duration syntax examples
Duration duration1 = Duration.ofSeconds(60); // 60 seconds
Duration duration2 = Duration.between(Instant.now(), Instant.now().plusSeconds(120));

// Period syntax examples
Period period1 = Period.ofDays(10); // 10 days
Period period2 = Period.between(LocalDate.of(2023, 1, 1), LocalDate.of(2023, 12, 31));
💻

Example

This example shows how to create and use Duration to measure time between two instants and Period to find the difference between two dates.

java
import java.time.Duration;
import java.time.Period;
import java.time.LocalDate;
import java.time.Instant;

public class DurationPeriodExample {
    public static void main(String[] args) {
        Instant start = Instant.now();
        Instant end = start.plusSeconds(3600); // 1 hour later

        Duration duration = Duration.between(start, end);
        System.out.println("Duration in seconds: " + duration.getSeconds());

        LocalDate startDate = LocalDate.of(2020, 1, 1);
        LocalDate endDate = LocalDate.of(2023, 6, 15);

        Period period = Period.between(startDate, endDate);
        System.out.println("Period: " + period.getYears() + " years, " + period.getMonths() + " months, " + period.getDays() + " days");
    }
}
Output
Duration in seconds: 3600 Period: 3 years, 5 months, 14 days
⚠️

Common Pitfalls

  • Using Duration to measure date differences can give unexpected results because it counts exact seconds, ignoring calendar changes.
  • Using Period for time differences (hours, minutes) is incorrect; it only works with dates.
  • Beware of time zones when using Instant and LocalDate to avoid wrong calculations.
java
import java.time.Duration;
import java.time.Period;
import java.time.LocalDate;
import java.time.LocalTime;

public class PitfallExample {
    public static void main(String[] args) {
        // Wrong: Using Period for time difference
        LocalTime time1 = LocalTime.of(10, 0);
        LocalTime time2 = LocalTime.of(12, 0);
        // Period period = Period.between(time1, time2); // Compile error

        // Correct: Use Duration for time
        Duration duration = Duration.between(time1, time2);
        System.out.println("Duration in hours: " + duration.toHours());

        // Wrong: Using Duration for date difference
        LocalDate date1 = LocalDate.of(2023, 1, 1);
        LocalDate date2 = LocalDate.of(2023, 1, 31);
        Duration wrongDuration = Duration.between(date1.atStartOfDay(), date2.atStartOfDay());
        System.out.println("Duration in days (wrong for dates): " + wrongDuration.toDays());

        // Correct: Use Period for date
        Period period = Period.between(date1, date2);
        System.out.println("Period in days: " + period.getDays());
    }
}
Output
Duration in hours: 2 Duration in days (wrong for dates): 30 Period in days: 30
📊

Quick Reference

ClassMeasuresCreation MethodsTypical Use Case
DurationTime-based (seconds, nanoseconds)ofSeconds(), ofMinutes(), between(Instant, Instant)Measure elapsed time or time intervals
PeriodDate-based (years, months, days)ofYears(), ofMonths(), between(LocalDate, LocalDate)Calculate difference between dates
✅

Key Takeaways

Use Duration to measure time intervals like seconds and nanoseconds.
Use Period to measure date differences like years, months, and days.
Duration works with Instant and LocalTime; Period works with LocalDate.
Avoid mixing Duration and Period for incompatible types to prevent errors.
Always consider time zones when working with Instants and dates.