Java8 - Java.time.Period Class example

In this tutorial, You are about java.time.Period example and how-to examples using this class in java 8.

What is Period in java?

When working with Date and Time API in java8, There is a requirement to find out the amount of time between two dates.

The period is measured in years, months, days, and time duration is measured in. It is a value-based class. So, two objects of the Period equality check might produce unpredictable results.

Following is a Signature

public final class Period extends Object implements ChronoPeriod,

What is the Difference between Java.time.Period and Java.time.Duration?

The period is Date based measurement of time and measured in Years, Months and Days. Whereas, Duration is Time based measurement and measured in hours, minutes, seconds and nanoseconds.

Period is used for humanly readable date measurement like years/months.Duration is more suitable for machine-based timing measurement for nanoseconds calculations. Finding the age of a person is an example of Period.

Java.time.Period class Example

There are various examples of the usage of Period.

How to create a Period object?

The period object can be created using the following creational methods.

of(), ofMonths(), ofDays(),ofYears() methods are used to create a instance of period.

import java.time.Instant;
import java.time.Period;

public class PeriodObjectCreateExample {
    public static void main(String[] args) {
        Period ofYears = Period.ofYears(5);
        Period ofMonths = Period.ofMonths(11);
        Period ofDays = Period.ofDays(20);
        Period ofWeeks = Period.ofWeeks(6);
        Period periodInYearMonthsTDays = Period.of(5, 11, 25);
        System.out.println("Total Period: " + periodInYearMonthsTDays);


Total Period: P5Y11M25D

How to add/subtract many days to the current date?

minus() minusDays() minusMonths() minusYears() are subtract specific units to current date. plus() plusDays() plusMonths() plusYears() are adding specific units to current date.

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

public class AddSubtractPeriodExample {
    public static void main(String[] args) {
        LocalDate localDate =;
        LocalDate add5Days =;
        System.out.println("Add 5 days"+add5Days);
        // date before one week
        LocalDate oneweekbefore = localDate.minus(Period.ofWeeks(1));
        System.out.println("subtract one week "+oneweekbefore);
        // Number of dates between two dates
        Period period = Period.between(oneweekbefore, add5Days);
        System.out.println("difference in days"+period.getDays());
        System.out.println("difference in months "+period.getMonths());


Add 5 days2018-09-02
subtract one week 2018-08-21
difference in days12
difference in months 0

How to calculate age in years/months/days using Period class?

The period class provides various following methods

  • getYears(): return the number of years of this period
  • getMonths(): return number of months of this period
  • getDays(): return number of days of this period
import java.time.LocalDate;
import java.time.Month;
import java.time.Period;

public class CalculateAge {
    public static void main(String[] args) {
        LocalDate currentDate =;
        LocalDate birthday = LocalDate.of(1995, Month.JANUARY, 1);
        Period period = Period.between(birthday, currentDate);
        System.out.println("Age is " + period.getYears() + " years, " + period.getMonths() +
                " months, and " +period.getDays() +
                " days old");



Age is 23 years, 7 months, and 27 days old


Finally, In this tutorial, You learned java.time.Duration class in java8 and multiple examples using this class