TemporalAdjuster in Java

1. Overview

In this tutorial, we’ll have a quick look at the TemporalAdjuster and use it in a few practical scenarios.

Java 8 introduced a new library for working with dates and times – java.time and TemporalAdjuster is a part of it. If you want to read more about the java.time, check this introductory article.

Simply put, TemporalAdjuster is a strategy for adjusting a Temporal object. Before getting into the usage of TemporalAdjuster, let’s have a look at the Temporal interface itself.

2. Temporal

A Temporal defines a representation of a date, time, or a combination of both, depending on the implementation we’re going to be using.

There are a number of implementations of the Temporal interface, including:

• LocalDate – which represents a date without a timezone
• LocalDateTime – which represents a date and time without a timezone
• HijrahDate – which represents a date in the Hijrah calendar system
• MinguoDate – which represents a date in the Minguo calendar system
• ThaiBuddhistDate – which represents a date in the Thai Buddhist calendar system

3. TemporalAdjuster

One of the interfaces included in this new library is TemporalAdjuster.

TemporalAdjuster is a functional interface which has many predefined implementations in the TemporalAdjusters class. The interface has a single abstract method named adjustInto() which can be called in any of its implementations by passing a Temporal object to it.

TemporalAdjuster allows us to perform complex date manipulations. For example, we can obtain the date of the next Sunday, the last day of the current month or the first day of the next year. We can, of course, do this using the old java.util.Calendar.

However, the new API abstracts away the underlying logic using its predefined implementations. For more information, visit the Javadoc.

4. Predefined TemporalAdjusters

The class TemporalAdjusters has many predefined static methods that return a TemporalAdjuster object to adjust Temporal objects in many different ways no matter what implementation of Temporal they might be.

Here’s a short list of these methods and a quick definition of them:

• dayOfWeekInMonth() – an adjuster for the ordinal day-of-week. For example the date of the second Tuesday in March
• firstDayOfMonth() – an adjuster for the date of the first day of the current month
• firstDayOfNextMonth() – an adjuster for the date of the first day of the next month
• firstDayOfNextYear() – an adjuster for the date of the first day of the next year
• firstDayOfYear() – an adjuster for the date of the first day of the current year
• lastDayOfMonth() – an adjuster for the date of the last day of the current month
• nextOrSame() – an adjuster for the date of the next occurrence of a specific day-of-week or the same day in case today matches the required day-of-week

As we can see, the methods’ names are pretty much self-explanatory. For more TemporalAdjusters, visit the Javadoc.

Let’s start with a simple example – instead of using a specific date as in the examples, we can use LocalDate.now() to get the current date from the system clock.

But, for this tutorial, we’re going to use a fixed date so that the tests won’t fail later when the expected result changes. Let’s see how we can use the TemporalAdjusters class to obtain the date of the Sunday after 2017-07-08:

@Test
public void whenAdjust_thenNextSunday() {
    LocalDate localDate = LocalDate.of(2017, 07, 8);
    LocalDate nextSunday = localDate.with(TemporalAdjusters.next(DayOfWeek.SUNDAY));
    
    String expected = "2017-07-09";
    
    assertEquals(expected, nextSunday.toString());
}

Here’s how we can obtain the last day of the current month:

LocalDate lastDayOfMonth = localDate.with(TemporalAdjusters.lastDayOfMonth());

5. Defining Custom TemporalAdjuster Implementations

We can also define our custom implementations for TemporalAdjuster. There are two different ways of doing this.

5.1. Using Lambda Expressions

Let’s see how we can obtain the date that’s 14 days after 2017-07-08 using the Temporal.with() method:

@Test
public void whenAdjust_thenFourteenDaysAfterDate() {
    LocalDate localDate = LocalDate.of(2017, 07, 8);
    TemporalAdjuster temporalAdjuster = t -> t.plus(Period.ofDays(14));
    LocalDate result = localDate.with(temporalAdjuster);
    
    String fourteenDaysAfterDate = "2017-07-22";
    
    assertEquals(fourteenDaysAfterDate, result.toString());
}

In this example, using a lambda expression, we set the temporalAdjuster object to add 14 days to the localDate object, which holds the date (2017-07-08).

Let’s see how we can obtain the date of the working day right after 2017-07-08 by defining our own TemporalAdjuster implementations using a lambda expression. But, this time, by using the ofDateAdjuster() static factory method:

static TemporalAdjuster NEXT_WORKING_DAY = TemporalAdjusters.ofDateAdjuster(date -> {
    DayOfWeek dayOfWeek = date.getDayOfWeek();
    int daysToAdd;
    if (dayOfWeek == DayOfWeek.FRIDAY)
        daysToAdd = 3;
    else if (dayOfWeek == DayOfWeek.SATURDAY)
        daysToAdd = 2;
    else
        daysToAdd = 1;
    return today.plusDays(daysToAdd);
});

Testing our code:

@Test
public void whenAdjust_thenNextWorkingDay() {
    LocalDate localDate = LocalDate.of(2017, 07, 8);
    TemporalAdjuster temporalAdjuster = NEXT_WORKING_DAY;
    LocalDate result = localDate.with(temporalAdjuster);

    assertEquals("2017-07-10", date.toString());
}

5.2. By Implementing the TemporalAdjuster Interface

Let’s see how we can write a custom TemporalAdjuster that obtains the working day after 2017-07-08 by implementing the TemporalAdjuster interface:

public class CustomTemporalAdjuster implements TemporalAdjuster {

    @Override
    public Temporal adjustInto(Temporal temporal) {
        DayOfWeek dayOfWeek 
          = DayOfWeek.of(temporal.get(ChronoField.DAY_OF_WEEK));
        
        int daysToAdd;
        if (dayOfWeek == DayOfWeek.FRIDAY)
            daysToAdd = 3;
        else if (dayOfWeek == DayOfWeek.SATURDAY)
            daysToAdd = 2;
        else
            daysToAdd = 1;
        return temporal.plus(daysToAdd, ChronoUnit.DAYS);
    }
}

Now, let’s run our test:

@Test
public void whenAdjustAndImplementInterface_thenNextWorkingDay() {
    LocalDate localDate = LocalDate.of(2017, 07, 8);
    CustomTemporalAdjuster temporalAdjuster = new CustomTemporalAdjuster();
    LocalDate nextWorkingDay = localDate.with(temporalAdjuster);
    
    assertEquals("2017-07-10", nextWorkingDay.toString());
}

6. Conclusion

In this tutorial, we’ve shown what TemporalAdjuster is, predefined TemporalAdjusters, how they can be used, and how we can implement our custom TemporalAdjuster implementations in two different ways.