1. Introduction

Java 8 introduced, through JSR 310, a complete overhaul of the Date/Time API by providing new, more advanced classes for Date processing. Period is one such class that we will focus on in this article.

2. What is a Period?

Period is a class from the java.time package, which models a date-based amount of time, such as ‘2 years, and 3 months’. The class represents a quantity or amount of time in terms of years, months, days, seconds, or nanoseconds.
The Period class is the time-based equivalent to this class.

The main particularity of Period is that it is immutable and thread-safe.

3. Creating a Period

3.1. Period.ofXXX()

You can create a Period object with any of the Period.ofXXX() methods.

        Period ofDays = Period.ofDays(1);//P1D
        Period ofMonths = Period.ofMonths(1);//P1M
        Period ofWeeks = Period.ofWeeks(1);//P7D
        Period ofYears = Period.ofYears(1);//P1Y

Additionally, you can use the generic Period.of() method and provide values for years, months, and days fields:

        Period period = Period.of(1, 2, 3);//P1Y2M3D

The values of years, months, and days may be negative:

        Period period = Period.of(1, -2, 3);//P1Y-2M3D

3.2. Parsing from String to Period

Assuming that you have a Period in ISO-8601 format and want to build a Period out of it, you can use the parse() method in this way:

        String myPeriod = "P1Y2M3D";// ISO-8601 Period format
        Period period = Period.parse(myPeriod);// P1Y2M3D

A Period can be negative as well:

        String myPeriod = "P1Y-2M3D";// ISO-8601 Period format
        Period Period = Period.parse(myPeriod);// P1Y-2M3D

The accepted ISO-8601 Period format is as follows: PnYnMnWnD.
In the above format, “n” is an integer; Y, M, W, and D are suffixes. Check out the detailed information about the Period ISO-8601 format here.

Any week input in treated as a period of 7 days.

        String myPeriod = "P2W";// ISO-8601 Period format
        Period period = Period.parse(myPeriod);// P14D (not P2W)

Java will throw a DateTimeParseException if it is not able to parse the String with the given time format.

    String myPeriod = "P2Ws";// Incorrect format
    Period period = Period.parse(myPeriod);// DateTimeParseException

3.3. Difference between two LocalDate Objects

You can obtain a Period as the difference between two LocalDate objects:

        LocalDate firstDate = LocalDate.of(2024,5,1);//2024-05-01
        LocalDate secondDate = LocalDate.of(2024,5,2);//2024-05-02
        Period period = Period.between(firstDate,secondDate);//P1D

4. Operating on a Period

4.1. Comparing two Period objects

Since the Period class overrides the equals() method, you can compare two Period objects in this way:

        Period firstPeriod = Period.ofDays(7);
        Period secondPeriod = Period.ofDays(1);
        Period thirdPeriod = Period.ofWeeks(1);
        boolean test1 = firstPeriod.equals(secondPeriod);// false
        boolean test2 = firstPeriod.equals(thirdPeriod);// true

4.2. Temporal Arithmetic with Period objects

The Period class provides plusXXX() and minusXXX() methods to increment and decrement the object field values. Since the Period is immutable, all these methods return a copy of the original object with updated fields.

        Period period = Period.ofDays(1);
        Period plusDays = period.plusDays(1);// P2D
        Period minusDays = period.minusDays(1);// P0D
        Period plusMonths = period.plusMonths(1);// P1M1D
        Period minusMonths = period.minusMonths(1);// P1D-1M
        Period plusYears = period.plusYears(1);// P1Y1D
        Period minusYears = period.minusYears(1);// P-1Y1D

You can also use the plus() and minus() to add and subtract two Period objects directly:

        Period period = Period.ofDays(1);//P1D
        Period toAdd = Period.ofMonths(1);//P1M
        Period addedPeriod = period.plus(toAdd);//P1M1D
        Period substractedPeriod = period.minus(toAdd);//P-1M1D

5. Conclusion

In this tutorial, you learned about the Period class in Java.

6. References

1) OCP Oracle Certified Professional Java SE 17 by Khalil A. Mughal and Vasily A. Strelnikov
2) Oracle Java Documentation