Java 8 – TemporalAdjusters examples

1. Overview

In this tutorial, We'll learn about the new Java 8 TemporalAdjusters class and its methods along with examples.

This is part of the new java 8 date and time api and in java.time.temporal package and class name TemporalAdjusters. This class now has predefined temporal objects to change the data as we want.

TemporalAdjusters class is a collection of TemporalAdjuster implementations.

First We will see the example programs on TemporalAdjusters class and next take a look at the Temporal interface.

At last, We'll define custom TemporalAdjuster implementation.

2. TemporalAdjusters Methods

All methods of TemporalAdjusters class are a standard set of adjusters and declared as static. So all of them directly called with a class name such as TemporalAdjusters.firstDayOfMonth().

firstDayOfMonth(): finding the first or last day of the month
firstDayOfNextMonth() : finding the first day of next month
firstDayOfYear(): finding the first  day of the year
lastDayOfYear(): finding the last day of the year
firstDayOfNextYear(): finding the first day of next year
dayOfWeekInMonth(int ordinal, DayOfWeek dayOfWeek): finding the first or last day-of-week within a month, such as "first Wednesday in June"
next(DayOfWeek dayOfWeek): finding the next day-of-week, such as "next Thursday"
previous(DayOfWeek dayOfWeek): finding the previous day-of-week, such as "previous Thursday"
previousOrSame(DayOfWeek dayOfWeek): Returns the previous-or-same day-of-week
nextOrSame(DayOfWeek dayOfWeek): Returns the next-or-same day-of-week

3. TemporalAdjusters Examples

Java 8 example program on TemporalAdjusters to get firstDayOfMonth, firstDayOfNextMonth, firstDayOfNextYear, firstDayOfYear, lastDayOfYear, dayOfWeekInMonth, lastDayOfMonth and lastDayOfYear.

package com.java.w3schools.blog.java8.date.time.api;

import java.time.DayOfWeek;
import java.time.LocalDate;
import java.time.temporal.TemporalAdjusters;

/**
 * 
 * 
 * @author Venkatesh
 *
 */
public class TemporalAdjustersExample {

      public static void main(String[] args) {
      
           LocalDate now = LocalDate.now();
           System.out.println("Current date : " + now);
           
           LocalDate output = null; 
           
           output = now.with(TemporalAdjusters.firstDayOfMonth());
           System.out.println("firstDayOfMonth :: " + output);
           
           output = now.with(TemporalAdjusters.firstDayOfNextMonth());
           System.out.println("firstDayOfNextMonth :: " + output);
           
           output = now.with(TemporalAdjusters.firstDayOfNextYear());
           System.out.println("firstDayOfNextYear :: " + output);
           
           output = now.with(TemporalAdjusters.firstDayOfYear());
           System.out.println("firstDayOfYear :: " + output);
           
           output = now.with(TemporalAdjusters.lastDayOfYear());
           System.out.println("lastDayOfYear :: " + output);
           
           output = now.with(TemporalAdjusters.dayOfWeekInMonth(1, DayOfWeek.FRIDAY));
           System.out.println("dayOfWeekInMonth(1, DayOfWeek.FRIDAY) :: " + output);
           
           output = now.with(TemporalAdjusters.lastDayOfMonth());
           System.out.println("lastDayOfMonth :: " + output);
           
           output = now.with(TemporalAdjusters.lastDayOfYear());
           System.out.println("lastDayOfYear :: " + output);
      }
      
}

Output:

Current date : 2019-08-06
firstDayOfMonth :: 2019-08-01
firstDayOfNextMonth :: 2019-09-01
firstDayOfNextYear :: 2020-01-01
firstDayOfYear :: 2019-01-01
lastDayOfYear :: 2019-12-31
dayOfWeekInMonth(1, DayOfWeek.FRIDAY) :: 2019-08-02
lastDayOfMonth :: 2019-08-31
lastDayOfYear :: 2019-12-31

4. Temporal

Temporal is a root interface in java 8 date time api. All date and time classes are implementations of Temporal interface.

Many common methods are placed in this interface as default methods.

default Temporal minus(long amountToSubtract, TemporalUnit unit)
default Temporal minus(TemporalAmount amount)
default Temporal plus(TemporalAmount amount)
default Temporal with(TemporalAdjuster adjuster)

The following are the implementation classes of Temporal.

HijrahDate
Instant
JapaneseDate
LocalDate
LocalDateTime
LocalTime
MinguoDate
OffsetDateTime
OffsetTime
ThaiBuddhistDate
Year
YearMonth
ZonedDateTime

Note: As well as, all the above classes implements TemporalAdjuster Functional Interface which has only one method. The functional method is adjustInto(Temporal temporal) and takes Temporal as an argument.

Whenever a method is called from TemporalAdjusters class, all methods return TemporalAdjuster object. Let us have a look at its internal code for a few methods.

 public static TemporalAdjuster lastDayOfYear() {
        return (temporal) -> temporal.with(DAY_OF_YEAR, temporal.range(DAY_OF_YEAR).getMaximum());
    }

 public static TemporalAdjuster firstDayOfNextYear() {
        return (temporal) -> temporal.with(DAY_OF_YEAR, 1).plus(1, YEARS);
    }


 public static TemporalAdjuster firstInMonth(DayOfWeek dayOfWeek) {
        return TemporalAdjusters.dayOfWeekInMonth(1, dayOfWeek);
    }

 public static TemporalAdjuster lastInMonth(DayOfWeek dayOfWeek) {
        return TemporalAdjusters.dayOfWeekInMonth(-1, dayOfWeek);
    }


 public static TemporalAdjuster next(DayOfWeek dayOfWeek) {
        int dowValue = dayOfWeek.getValue();
        return (temporal) -> {
            int calDow = temporal.get(DAY_OF_WEEK);
            int daysDiff = calDow - dowValue;
            return temporal.plus(daysDiff >= 0 ? 7 - daysDiff : -daysDiff, DAYS);
        };
    }

All are returning TemporalAdjuster implementation using Lambda Expression.

5. Custom TemporalAdjuster Implementation

As of now, We've seen examples using predefined TemporalAdjuster's. Now, we'll write our own implementation.

In this custom code, We add 10 days to the actual date.

5.1 Using Lambda

Creating a custom TemporalAdjuster using Lambda Expression.

Creating a custom TemporalAdjuster to increment 10 days.

// Creating a custom TemporalAdjuster to increment 10 days.

TemporalAdjuster customAdjuster = (temporal) -> temporal.plus(Period.ofDays(10));

LocalDate localDate = LocalDate.now();
System.out.println("Date Before applying custom TemporalAdjuster : "+localDate);
localDate = localDate.with(customAdjuster);
System.out.println("Date After applying custom TemporalAdjuster : "+localDate);

Output:

Date Before applying custom TemporalAdjuster : 2019-08-06
Date After applying custom TemporalAdjuster : 2019-08-16

5.2 Implementing TemporalAdjuster interface

Before java 8, it is done by implementing interface as below.

class CustomTemporalAdjuster implements TemporalAdjuster {
 
 @Override
 public Temporal adjustInto(Temporal temporal) {
  return temporal.plus(Period.ofDays(10));
 }

}

If you create the object for this and pass it to the with() function that produces the same result as using Lambda.

6. Conclusion

In this article, We've covered what is TemporalAdjusters class introduced in Java 8.

Introduction to Temporal interface and TemporalAdjuster Functional Interface.

Described all Temporal and TemporalAdjuster implementations classes list.

Examples programs on TemporalAdjusters to get the firstDayOfMonth, firstDayOfNextMonth, firstDayOfNextYear and etc using predefined TemporalAdjuster mehtods.

Finally, Implemented custom TemporalAdjuster behavior using Lambda and older passion by implementing the TemporalAdjuster interface.

All the code shown in this article is over GitHub.
Temporal API
TemporalAdjusters API Ref