The Period class is meant to represent an amount of time using date-based values (years, months, weeks, and days). This period of time can be obtained in different ways. For example, a period of 120 days can be obtained as follows:

Period fromDays = Period.ofDays(120); // P120D

Or, a period of 2,000 years, 11 months and 24 days can be obtained via the of() method, as follows:

Period periodFromUnits = Period.of(2000, 11, 24); // P2000Y11M24D

Period can also be obtained from LocalDate:

LocalDate localDate = LocalDate.now();
Period periodFromLocalDate = Period.of(localDate.getYear(),
  localDate.getMonthValue(), localDate.getDayOfMonth());

Finally, Period can be obtained from a String object that respects the ISO-8601 period formats PnYnMnD and PnW. For example, the P2019Y2M25D string represents 2019 years, 2 months, and 25 days:

Period periodFromString = Period.parse("P2019Y2M25D");

But, the real power of Period is revealed when it is used to represent a period of time between two dates (for example, LocalDate). The period of time between March 12, 2018 and July 20, 2019 can be represented as follows:

LocalDate startLocalDate = LocalDate.of(2018, 3, 12);
LocalDate endLocalDate = LocalDate.of(2019, 7, 20);
Period periodBetween = Period.between(startLocalDate, endLocalDate);

The amount of time in years, months, and days can be obtained via Period.getYears(), Period.getMonths(), and Period.getDays(). For example, the following helper method uses these methods to output the amount of time as a string:

public static String periodToYMD(Period period) {

  StringBuilder sb = new StringBuilder();
  
  sb.append(period.getYears())
   .append("y:")
   .append(period.getMonths())
   .append("m:")
   .append(period.getDays())
   .append("d");

 return sb.toString();
}

Let's call this method periodBetween (the difference is 1 year, 4 months, and 8 days):

periodToYMD(periodBetween); // 1y:4m:8d

The Period class is also useful when determining whether a particular date is earlier than another date. There is a flag method, named isNegative(). Having an  A period and a B period, the result of applying Period.between(A, B) can be negative if B is before A, or positive if A is before B. Taking this logic further, isNegative()  returns true if B is before A or false if A is before B, as in our case that follows (basically, this method returns false if years, months, or days is negative):

// returns false, since 12 March 2018 is earlier than 20 July 2019
periodBetween.isNegative();

Finally, Period can be modified by adding or subtracting a period of time. There are methods such as plusYears(), plusMonths(), plusDays(), minusYears(), minusMonths(), and minusDays(). For example, adding 1 year to periodBetween can be done as follows:

Period periodBetweenPlus1Year = periodBetween.plusYears(1L);

Adding two Period classes can be accomplished via the Period.plus() method, as follows:

Period p1 = Period.ofDays(5);
Period p2 = Period.ofDays(20);
Period p1p2 = p1.plus(p2); // P25D