o7planning

Java TemporalAdjusters Tutorial with Examples

  1. TemporalAdjusters
  2. TemporalAdjusters Methods
  3. ofDateAdjuster(UnaryOperator<LocalDate>)
  4. firstDayOfMonth()
  5. lastDayOfMonth()
  6. firstDayOfNextMonth()
  7. firstDayOfYear()
  8. lastDayOfYear()
  9. firstDayOfNextYear()
  10. firstInMonth(DayOfWeek)
  11. lastInMonth(DayOfWeek)
  12. dayOfWeekInMonth(int, DayOfWeek)
  13. next(DayOfWeek)
  14. nextOrSame(DayOfWeek)
  15. previous(DayOfWeek)
  16. previousOrSame(DayOfWeek)

1. TemporalAdjusters

The TemporalAdjusters class provides static methods to obtain useful and common TemporalAdjuster objects, such as:
  • Finding the first or last day of the month.
  • Finding the first day of next month.
  • Finding the first or last day of the year.
  • Finding the first day of next year.
  • Finding the first or last "day-of-week" within a month, such as "first Wednesday in June".
  • Finding the next or previous "day-of-week", such as "next Thursday".
See also article about the TemporalAdjuster interface with basic examples and custom TemporalAdjuster:

2. TemporalAdjusters Methods

All methods provided by TemporalAdjusters are static and return a TemporalAdjuster object.
public static TemporalAdjuster ofDateAdjuster(UnaryOperator<LocalDate> dateBasedAdjuster)

public static TemporalAdjuster firstDayOfMonth()  
public static TemporalAdjuster lastDayOfMonth()  

public static TemporalAdjuster firstDayOfNextMonth()  

public static TemporalAdjuster firstDayOfYear()  
public static TemporalAdjuster lastDayOfYear()  

public static TemporalAdjuster firstDayOfNextYear()

public static TemporalAdjuster firstInMonth(DayOfWeek dayOfWeek)  
public static TemporalAdjuster lastInMonth(DayOfWeek dayOfWeek)  

public static TemporalAdjuster dayOfWeekInMonth(int ordinal, DayOfWeek dayOfWeek)

public static TemporalAdjuster next(DayOfWeek dayOfWeek)   
public static TemporalAdjuster nextOrSame(DayOfWeek dayOfWeek)  

public static TemporalAdjuster previous(DayOfWeek dayOfWeek)   
public static TemporalAdjuster previousOrSame(DayOfWeek dayOfWeek)

3. ofDateAdjuster(UnaryOperator<LocalDate>)

This method returns a TemporalAdjuster object to adjust the LocalDate part of a Temporal object. Other parts of the Temporal object remain unchanged.
public static TemporalAdjuster ofDateAdjuster(UnaryOperator<LocalDate> dateBasedAdjuster) {
    Objects.requireNonNull(dateBasedAdjuster, "dateBasedAdjuster");
    return (temporal) -> {
        LocalDate input = LocalDate.from(temporal);
        LocalDate output = dateBasedAdjuster.apply(input);
        return temporal.with(output);
    };
}
For example, adding 2 days to a Temporal object:
Temporal
Example
After 2 days
ZonedDateTime
2020-05-25T13:30:59+6[Asia/Bishkek]
2020-05-27T13:30:59+6[Asia/Bishkek]
OffsetDateTime
2020-05-25T13:30:59+6
2020-05-27T13:30:59+6
LocalDateTime
2020-05-25T13:30:59
2020-05-27T13:30:59
Example: A TemporalAdjuster to add 2 days.
TemporalAdjusters_ofDateAdjuster_ex1.java
package org.o7planning.temporaladjusters.ex;

import java.time.ZonedDateTime;
import java.time.temporal.TemporalAdjuster;
import java.time.temporal.TemporalAdjusters;

public class TemporalAdjusters_ofDateAdjuster_ex1 {
    public static void main(String[] args) {
        TemporalAdjuster add2DaysAdjuster = TemporalAdjusters.ofDateAdjuster(localDate -> localDate.plusDays(2));
        
        ZonedDateTime zonedDateTime = ZonedDateTime.now();
        ZonedDateTime after2Days = zonedDateTime.with(add2DaysAdjuster);
        
        System.out.println("zonedDateTime: " + zonedDateTime);
        System.out.println("after2Days: " + after2Days);
    }
}
Output:
zonedDateTime: 2021-07-05T18:53:19.138987+06:00[Asia/Bishkek]
after2Days: 2021-07-07T18:53:19.138987+06:00[Asia/Bishkek]
  • Java UnaryOperator

4. firstDayOfMonth()

Return a TemporalAdjuster - "first day-of-month".
public static TemporalAdjuster firstDayOfMonth()
Example:
TemporalAdjusters_firstDayOfMonth_ex1.java
LocalDate localDate = LocalDate.now();
System.out.println("today is: " + localDate);

LocalDate firstDayOfMonth = (LocalDate) TemporalAdjusters.firstDayOfMonth().adjustInto(localDate);
System.out.println("firstDayOfMonth: " + firstDayOfMonth);

DayOfWeek dayOfWeek = firstDayOfMonth.getDayOfWeek();
System.out.println(" > day of week: " + dayOfWeek);
Output:
today is: 2021-07-05
firstDayOfMonth: 2021-07-01
 > day of week: THURSDAY
  • Java DayOfWeek

5. lastDayOfMonth()

Return a TemporalAdjuster - "last day-of-month".
public static TemporalAdjuster lastDayOfMonth()
Example:
TemporalAdjusters_lastDayOfMonth_ex1.java
LocalDate localDate = LocalDate.now();
System.out.println("today is: " + localDate);

LocalDate lastDayOfMonth = (LocalDate) TemporalAdjusters.lastDayOfMonth().adjustInto(localDate);
System.out.println("lastDayOfMonth: " + lastDayOfMonth);

DayOfWeek dayOfWeek = lastDayOfMonth.getDayOfWeek();
System.out.println(" > day of week: " + dayOfWeek);
Output:
today is: 2021-07-05
lastDayOfMonth: 2021-07-31
 > day of week: SATURDAY
  • Java DayOfWeek

6. firstDayOfNextMonth()

Return a TemporalAdjuster - "first day of next month".
public static TemporalAdjuster firstDayOfNextMonth()
Example:
TemporalAdjusters_firstDayOfNextMonth_ex1.java
LocalDate localDate = LocalDate.now();
System.out.println("today is: " + localDate);

LocalDate firstDayOfNextMonth = (LocalDate) localDate.with(TemporalAdjusters.firstDayOfNextMonth());
System.out.println("firstDayOfNextMonth: " + firstDayOfNextMonth);

DayOfWeek dayOfWeek = firstDayOfNextMonth.getDayOfWeek();
System.out.println(" > day of week: " + dayOfWeek);

int dayOfMonth = firstDayOfNextMonth.getDayOfMonth();
System.out.println(" > day of month: " + dayOfMonth);
Output:
today is: 2021-07-05
firstDayOfNextMonth: 2021-08-01
 > day of week: SUNDAY
 > day of month: 1

7. firstDayOfYear()

Return a TemporalAdjuster - "first day-of-year".
public static TemporalAdjuster firstDayOfYear()
Example:
TemporalAdjusters_firstDayOfYear_ex1.java
LocalDate localDate = LocalDate.now();
System.out.println("today is: " + localDate);

LocalDate firstDayOfYear = (LocalDate) localDate.with(TemporalAdjusters.firstDayOfYear());
System.out.println("firstDayOfYear: " + firstDayOfYear);

DayOfWeek dayOfWeek = firstDayOfYear.getDayOfWeek();
System.out.println(" > day of week: " + dayOfWeek);
Output:
today is: 2021-07-05
firstDayOfYear: 2021-01-01
 > day of week: FRIDAY

8. lastDayOfYear()

Return a TemporalAdjuster - "last day-of-year".
public static TemporalAdjuster lastDayOfYear()
Example:
TemporalAdjusters_lastDayOfYear_ex1.java
LocalDate localDate = LocalDate.now();
System.out.println("today is: " + localDate);

LocalDate lastDayOfYear = (LocalDate) localDate.with(TemporalAdjusters.lastDayOfYear());
System.out.println("lastDayOfYear: " + lastDayOfYear);

DayOfWeek dayOfWeek = lastDayOfYear.getDayOfWeek();
System.out.println(" > day of week: " + dayOfWeek);
Output:
today is: 2021-07-05
lastDayOfYear: 2021-12-31
 > day of week: FRIDAY

9. firstDayOfNextYear()

Return a TemporalAdjuster - "first day of next year".
public static TemporalAdjuster firstDayOfNextYear()
Example:
TemporalAdjusters_firstDayOfNextYear_ex1.java
LocalDate localDate = LocalDate.now();
System.out.println("today is: " + localDate);

LocalDate firstDayOfNextYear = (LocalDate) localDate.with(TemporalAdjusters.firstDayOfNextYear());
System.out.println("firstDayOfNextYear: " + firstDayOfNextYear);

DayOfWeek dayOfWeek = firstDayOfNextYear.getDayOfWeek();
System.out.println(" > day of week: " + dayOfWeek);

int dayOfYear = firstDayOfNextYear.getDayOfYear();
System.out.println(" > day of year: " + dayOfYear);
Output:
today is: 2021-07-05
firstDayOfNextYear: 2022-01-01
> day of week: SATURDAY
> day of year: 1

10. firstInMonth(DayOfWeek)

Return a TemporalAdjuster - "First day-of-week of the month". For example, find the first MONDAY of the month.
public static TemporalAdjuster firstInMonth(DayOfWeek dayOfWeek)
Currently in the US, the start date of DST is the second Sunday of March and the end is the first Sunday of November. The question is when is the start date of DST 2025 in the US?
TemporalAdjusters_firstInMonth_ex1.java
// Find the first SUNDAY in month.
TemporalAdjuster adjuster1 = TemporalAdjusters.firstInMonth(DayOfWeek.SUNDAY);
// Find the next SUNDAY
TemporalAdjuster adjuster2 = TemporalAdjusters.next(DayOfWeek.SUNDAY);

LocalDate localDate = LocalDate.of(2025, 3, 1); // 2025-03-01

LocalDate firstSundayInMonth = (LocalDate) localDate.with(adjuster1);
LocalDate secondSundayInMonth = (LocalDate) firstSundayInMonth.with(adjuster2);

System.out.println("firstSaturdayInMonth: " + firstSundayInMonth); // 2025-03-02
System.out.println("secondSundayInMonth: " + secondSundayInMonth);  // 2025-03-09

11. lastInMonth(DayOfWeek)

Return a TemporalAdjuster - "Last day-of-week of the month". For example, find the last MONDAY of the month.
public static TemporalAdjuster lastInMonth(DayOfWeek dayOfWeek)
Example: Find the last Sunday of the current month:
TemporalAdjusters_lastInMonth_ex1.java
// Find the last SUNDAY in month.
TemporalAdjuster adjuster = TemporalAdjusters.lastInMonth(DayOfWeek.SUNDAY);  

LocalDate localDate = LocalDate.now();
System.out.println("Today is: " + localDate);

LocalDate lastSundayInMonth = (LocalDate) localDate.with(adjuster);  
System.out.println("lastSundayInMonth: " + lastSundayInMonth);
Output:
Today is: 2021-07-05
lastSundayInMonth: 2021-07-25

12. dayOfWeekInMonth(int, DayOfWeek)

Return a TemporalAdjuster - "the ordinal(th) day-of-week of the month". For example, find the 3rd MONDAY of the month.
public static TemporalAdjuster dayOfWeekInMonth(int ordinal, DayOfWeek dayOfWeek)
Example: Find the second SUNDAY of March 2025 (DST start date 2025 in the US).
TemporalAdjusters_dayOfWeekInMonth_ex1.java
// Find the second SUNDAY in month.
TemporalAdjuster adjuster = TemporalAdjusters.dayOfWeekInMonth(2, DayOfWeek.SUNDAY);  

LocalDate localDate = LocalDate.of(2025, 3, 1); // 2025-03-01
 
LocalDate secondSundayInMonth = (LocalDate) localDate.with(adjuster);   
System.out.println("secondSundayInMonth: " + secondSundayInMonth);  // 2025-03-09

13. next(DayOfWeek)

Return a TemporalAdjuster - "next day-of-week". For example, find the next MONDAY.
public static TemporalAdjuster next(DayOfWeek dayOfWeek)
Example: Find the next MONDAY.
TemporalAdjusters_next_ex1.java
// Find the next MONDAY
TemporalAdjuster adjuster = TemporalAdjusters.next(DayOfWeek.MONDAY);  

LocalDate localDate = LocalDate.of(2021, 7, 5); // 2021-07-05
System.out.println("localDate: " + localDate);  // 2021-07-05
System.out.println("localDate.getDayOfWeek(): " + localDate.getDayOfWeek());  // MONDAY
 
// Next MONDAY.
LocalDate nextMonday = localDate.with(adjuster);
 
System.out.println("nextMonday: " + nextMonday);  // 2021-07-12
System.out.println("nextMonday.getDayOfWeek(): " + nextMonday.getDayOfWeek());  // MONDAY
Output:
localDate: 2021-07-05
localDate.getDayOfWeek(): MONDAY
nextMonday: 2021-07-12
nextMonday.getDayOfWeek(): MONDAY

14. nextOrSame(DayOfWeek)

Return a TemporalAdjuster - "same or next day-of-week".
public static TemporalAdjuster nextOrSame(DayOfWeek dayOfWeek)
Example: Return this date if it is Monday, otherwise return the next Monday.
TemporalAdjusters_nextOrSame_ex1.java
// Find the next or same MONDAY
TemporalAdjuster adjuster = TemporalAdjusters.nextOrSame(DayOfWeek.MONDAY);  

LocalDate localDate = LocalDate.of(2021, 7, 5); // 2021-07-05
System.out.println("localDate: " + localDate);  // 2021-07-05
System.out.println("localDate.getDayOfWeek(): " + localDate.getDayOfWeek());  // MONDAY
 
// Next or same MONDAY.
LocalDate nextOrSameMonday = localDate.with(adjuster);
 
System.out.println("nextOrSameMonday: " + nextOrSameMonday);  // 2021-07-05
System.out.println("nextOrSameMonday.getDayOfWeek(): " + nextOrSameMonday.getDayOfWeek());  // MONDAY

15. previous(DayOfWeek)

Return a TemporalAdjuster - "previous day-of-week". For example, find the previous MONDAY.
public static TemporalAdjuster previous(DayOfWeek dayOfWeek)
Example: Find the previous MONDAY.
TemporalAdjusters_previous_ex1.java
// Find the previous MONDAY
TemporalAdjuster adjuster = TemporalAdjusters.previous(DayOfWeek.MONDAY);  

LocalDate localDate = LocalDate.of(2021, 7, 5); // 2021-07-05
System.out.println("localDate: " + localDate);  // 2021-07-05
System.out.println("localDate.getDayOfWeek(): " + localDate.getDayOfWeek());  // MONDAY
 
// Previous MONDAY.
LocalDate previousMonday = localDate.with(adjuster);
 
System.out.println("previousMonday: " + previousMonday);  // 2021-06-28
System.out.println("previousMonday.getDayOfWeek(): " + previousMonday.getDayOfWeek());  // MONDAY
Output:
localDate: 2021-07-05
localDate.getDayOfWeek(): MONDAY
previousMonday: 2021-06-28
previousMonday.getDayOfWeek(): MONDAY

16. previousOrSame(DayOfWeek)

Return a TemporalAdjuster - "same or previous day-of-week".
public static TemporalAdjuster previousOrSame(DayOfWeek dayOfWeek)
Example: Returns this date if it is Monday, otherwise return the previous Monday.
TemporalAdjusters_previousOrSame_ex1.java
// Find the previous or same MONDAY
TemporalAdjuster adjuster = TemporalAdjusters.previousOrSame(DayOfWeek.MONDAY);  

LocalDate localDate = LocalDate.of(2021, 7, 5); // 2021-07-05
System.out.println("localDate: " + localDate);  // 2021-07-05
System.out.println("localDate.getDayOfWeek(): " + localDate.getDayOfWeek());  // MONDAY
 
// Previous or same MONDAY.
LocalDate previousOrSameMonday = localDate.with(adjuster);
 
System.out.println("previousOrSameMonday: " + previousOrSameMonday);  // 2021-07-05
System.out.println("previousOrSameMonday.getDayOfWeek(): " + previousOrSameMonday.getDayOfWeek());  // MONDAY