java.time.Period Class in Java

The Period class in the java.time package, introduced in Java 8, represents a date-based amount of time in terms of years, months, and days. It is commonly used to calculate the difference between two dates or to add and subtract date-based values from a date.

• Represents a period using years, months, and days.
• Immutable and thread-safe.
• Useful for date calculations such as age, subscription duration, and project timelines.

Example: Calculate Difference Between Two Dates

import java.time.LocalDate;
import java.time.Period;

public class Geeks {

    public static void main(String[] args) {

        LocalDate start = LocalDate.of(2022, 1, 1);
        LocalDate end = LocalDate.of(2025, 7, 9);

        Period period = Period.between(start, end);

        System.out.println("Years : " + period.getYears());
        System.out.println("Months: " + period.getMonths());
        System.out.println("Days  : " + period.getDays());
    }
}

Years : 3
Months: 6
Days  : 8

Explanation: The between() method calculates the difference between two dates and returns it as a Period object containing years, months, and days.

Syntax

public final class Period extends Object implements ChronoPeriod, Serializable

The Period class cannot be extended because it is declared as final.

How to Create a Period

A Period object can be created using several factory methods provided by the class.

1. Using Period.of()

The of() method creates a period using years, months, and days.

Period period = Period.of(2, 5, 10);
System.out.println(period);

Output:

P2Y5M10D

Here:

• P indicates a period.
• 2Y means 2 years.
• 5M means 5 months.
• 10D means 10 days.

2. Using Period.ofYears()

The Period.ofYears() method creates a period containing only a specified number of years.

Period period = Period.ofYears(3);
System.out.println(period);

Output:

P3Y

Use: Use Period.ofYears() when the period needs to be represented only in years.

3. Using Period.ofMonths()

The Period.ofMonths() method creates a period containing only a specified number of months.

Period period = Period.ofMonths(6);
System.out.println(period);

Output:

P6M

Use: Use Period.ofMonths() when the date-based duration is expressed only in months.

4. Using Period.ofWeeks()

The Period.ofWeeks() method creates a period by converting the specified number of weeks into days

Period period = Period.ofWeeks(2);
System.out.println(period);

Output:

P14D

Use: Use Period.ofWeeks() when the required period is given in weeks. The weeks are stored internally as days.

Adding and Subtracting Period Values

The Period class provides methods such as plus(), minus(), plusDays(), minusMonths(), and minusYears() to modify date-based values.

Since Period is immutable, these methods return a new Period object instead of modifying the existing one.

import java.time.Period;

public class Geeks {

    public static void main(String[] args) {

        // Create a period of 6 months
        Period p1 = Period.ofMonths(6);

        // Subtract 2 months
        Period p2 = p1.minus(Period.ofMonths(2));

        System.out.println(p2);
    }
}

P4M

Explanation: Period.ofMonths(6) creates a period of 6 months. The minus() method subtracts 2 months and returns a new period of 4 months.

Adding a Period to a Date

A Period can be added to a date using methods such as addTo() or LocalDate.plus().

Example: Using ofDays() and addTo()

import java.time.*;
import java.time.temporal.Temporal;

public class Geeks {

    public static void main(String[] args) {

        // Create a period of 24 days
        Period period = Period.ofDays(24);

        // Add the period to the current date
        Temporal result = period.addTo(LocalDate.now());

        System.out.println(result);
    }
}

2026-08-02

Explanation: The ofDays(24) method creates a period of 24 days. The addTo() method adds this period to the current date and returns the updated date.

Advantages of Period Class

• Represents date-based durations using years, months, and days.
• Simplifies date calculations between two dates.
• Immutable and thread-safe.
• Provides convenient methods for adding and subtracting date-based values.
• Integrates seamlessly with other classes in the java.time API.

Commonly Used Methods of Period