Java Period Class Methods with Examples

📘 Premium Read: Access my best content on Medium member-only articles — deep dives into Java, Spring Boot, Microservices, backend architecture, interview preparation, career advice, and industry-standard best practices.

✅ Some premium posts are free to read — no account needed. Follow me on Medium to stay updated and support my writing.

🎓 Top 10 Udemy Courses (Huge Discount): Explore My Udemy Courses — Learn through real-time, project-based development.

▶️ Subscribe to My YouTube Channel (172K+ subscribers): Java Guides on YouTube

This article is the series of Java Date Time API Tutorial. In this article, we will discuss important methods or APIs of the Java Period class from the java.time package.

The Period class represents a quantity of time in terms of years, months and days. A Period uses date-based values (years, months, days). This class is immutable and thread-safe.

Java Period Class Diagram

The below class diagram shows a list of methods/APIs that the Period class provides.

Java Period Class Methods/APIs with Examples

Let's demonstrates the usage of a few important and commonly used Period class methods with examples. In below PeriodMethodsExample class, each method name describes the Period class method and its usage. Refer https://docs.oracle.com/javase/8/docs/api/java/time/Period.html Java doc for more details.

package net.javaguides.date;

import java.time.LocalDateTime;
import java.time.Period;

/**
 * Class demonstrates the usage of Period class methods with examples
 * 
 * @author Ramesh Fadatare
 *
 */
public class PeriodMethodsExample {

    public static void main(String[] args) {
        PeriodMethodsExample example = new PeriodMethodsExample();
        example.withYearsMethodExample();

        example.withMonthsMethodExample();

        example.withDaysMethodExample();

        example.toTotalMonthsMethodExample();

        example.subtractFromMethodExample();

        example.plusYearsMethodExample();

        example.plusMonthsMethodExample();

        example.plusDaysMethodExample();

        example.plusMethodExample();

        example.parseMethodExample();

        example.ofYearsMethodExample();

        example.ofWeeksMethodExample();

        example.ofMonthsMethodExample();

        example.ofDaysMethodExample();

        example.ofMethodExample();

        example.minusYearsMethodExample();

        example.minusMonthsMethodExample();

        example.minusDaysMethodExample();
    }

    public void withYearsMethodExample() {
        Period period = Period.ofYears(2);
        System.out.println(period.toString());
        period = period.withYears(5);
        System.out.println(period.toString());
    }

    public void withMonthsMethodExample() {
        Period period = Period.ofMonths(2);
        System.out.println(period.toString());
        period = period.withMonths(5);
        System.out.println(period.toString());
    }

    public void withDaysMethodExample() {
        Period period = Period.ofDays(2);
        System.out.println(period.toString());
        period = period.withDays(5);
        System.out.println(period.toString());
    }

    public void toTotalMonthsMethodExample() {
        Period period = Period.ofYears(2);
        System.out.println(period.toTotalMonths());
    }

    public void subtractFromMethodExample() {
        Period period = Period.ofYears(2);

        LocalDateTime date = LocalDateTime.now();
        System.out.println(date);

        date = (LocalDateTime) period.subtractFrom(date);
        System.out.println(date);
    }

    public void plusYearsMethodExample() {
        Period period = Period.ofYears(2);
        Period period1 = period.plusYears(1);
        System.out.println(period1.getYears());
    }

    public void plusMonthsMethodExample() {
        Period period = Period.ofMonths(2);
        Period period1 = period.plusMonths(1);
        System.out.println(period1.getMonths());
    }

    public void plusDaysMethodExample() {
        Period period = Period.ofDays(2);
        Period period1 = period.plusDays(1);
        System.out.println(period1.getDays());
    }

    public void plusMethodExample() {
        Period period = Period.of(1, 5, 2);
        System.out.println(
            "Years: " + period.getYears() + ", Months: " + period.getMonths() + ", Days: " + period.getDays());
        Period period1 = period.plus(Period.ofDays(5));
        System.out.println(
            "Years: " + period1.getYears() + ", Months: " + period1.getMonths() + ", Days: " + period1.getDays());
    }

    public void parseMethodExample() {
        Period period = Period.parse("P1Y2M3D");
        System.out.println(
            "Years: " + period.getYears() + ", Months: " + period.getMonths() + ", Days: " + period.getDays());
    }

    public void ofYearsMethodExample() {
        Period period = Period.ofYears(2);
        System.out.println(period.getYears());
    }

    public void ofWeeksMethodExample() {
        Period period = Period.ofWeeks(2);
        System.out.println(period.getDays());
    }

    public void ofMonthsMethodExample() {
        Period period = Period.ofMonths(2);
        System.out.println(period.getMonths());
    }

    public void ofDaysMethodExample() {
        Period period = Period.ofDays(2);
        System.out.println(period.getDays());
    }

    public void ofMethodExample() {
        Period period = Period.of(1, 5, 2);
        System.out.println(
            "Years: " + period.getYears() + ", Months: " + period.getMonths() + ", Days: " + period.getDays());
    }

    public void minusYearsMethodExample() {
        Period period = Period.ofYears(5);
        System.out.println(period.getYears());
        Period period1 = period.minusYears(3);
        System.out.println(period1.getYears());
    }

    public void minusMonthsMethodExample() {
        Period period = Period.ofMonths(5);
        System.out.println(period.getMonths());
        Period period1 = period.minusMonths(3);
        System.out.println(period1.getMonths());
    }

    public void minusDaysMethodExample() {
        Period period = Period.ofDays(5);
        System.out.println(period.getDays());
        Period period1 = period.minusDays(3);
        System.out.println(period1.getDays());
    }
}

Output:

P2Y
P5Y
P2M
P5M
P2D
P5D
24
2018-12-22T13:27:23.928
2016-12-22T13:27:23.928
3
3
3
Years: 1, Months: 5, Days: 2
Years: 1, Months: 5, Days: 7
Years: 1, Months: 2, Days: 3
2
14
2
2
Years: 1, Months: 5, Days: 2
5
2
5
2
5
2

Java Guides

Search This Blog