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

Class	Measures	Creation Methods	Typical Use Case
Duration	Time-based (seconds, nanoseconds)	ofSeconds(), ofMinutes(), between(Instant, Instant)	Measure elapsed time or time intervals
Period	Date-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.