The java.time API provides excellent tools for basic date manipulation—adding days, subtracting months, etc. However, real-world business logic often involves complex, rule-based date calculations. Calculating the next working day, the last business day of the month, or the next company payday requires more than simple arithmetic. This is where TemporalAdjuster becomes an indispensable tool, allowing you to encapsulate complex date-shifting logic into reusable, expressive components.
What is a TemporalAdjuster?
A TemporalAdjuster is a functional interface in the java.time package with a single method: Temporal adjustInto(Temporal temporal). Its purpose is to adjust a temporal object, such as LocalDate, LocalDateTime, or ZonedDateTime, according to a specific strategy.
Think of it as a smart, reusable function that answers questions like:
- "What's the next Tuesday?"
- "What is the last day of the current quarter?"
- "What is the third Friday of next month?"
The power of TemporalAdjuster lies in its ability to be passed around and combined, making date-centric business logic clean and declarative.
The Built-in Adjusters: A Powerful Starter Kit
The TemporalAdjusters utility class provides a rich set of common adjusters. You can use these directly or as building blocks.
LocalDate today = LocalDate.now();
// Common built-in adjusters
LocalDate firstDayOfMonth = today.with(TemporalAdjusters.firstDayOfMonth());
LocalDate lastDayOfYear = today.with(TemporalAdjusters.lastDayOfYear());
LocalDate nextMonday = today.with(TemporalAdjusters.next(DayOfWeek.MONDAY));
LocalDate firstFridayInMonth = today.with(TemporalAdjusters.firstInMonth(DayOfWeek.FRIDAY));
LocalDate lastBusinessDayOfMonth = today.with(TemporalAdjusters.lastInMonth(DayOfWeek.FRIDAY));
System.out.println("Today: " + today);
System.out.println("First day of month: " + firstDayOfMonth);
System.out.println("Next Monday: " + nextMonday);
Creating Custom Temporal Adjusters for Business Logic
The true power is unlocked when you create your own adjusters to encapsulate domain-specific rules. There are three primary ways to do this.
1. Inline with Lambda Expressions (Simple Rules)
For straightforward, single-purpose logic, a lambda is perfect.
// Adjuster to get the next working day (skip weekends)
TemporalAdjuster nextWorkingDay = temporal -> {
DayOfWeek dayOfWeek = DayOfWeek.from(temporal);
int daysToAdd = 1;
if (dayOfWeek == DayOfWeek.FRIDAY) daysToAdd = 3; // Friday -> Monday
else if (dayOfWeek == DayOfWeek.SATURDAY) daysToAdd = 2; // Saturday -> Monday
return temporal.plus(daysToAdd, ChronoUnit.DAYS);
};
LocalDate friday = LocalDate.of(2023, 10, 13);
LocalDate nextWorking = friday.with(nextWorkingDay);
System.out.println(friday + " is a " + friday.getDayOfWeek()); // 2023-10-13 is a FRIDAY
System.out.println("Next working day is " + nextWorking); // Next working day is 2023-10-16
2. As a static final Field (Reusable Rules)
For important business rules, define them as reusable constants.
public class BusinessDateAdjusters {
// US Market Holidays (simplified example for 2023)
private static final Set<LocalDate> HOLIDAYS = Set.of(
LocalDate.of(2023, 1, 1), // New Year's
LocalDate.of(2023, 12, 25) // Christmas
);
// Adjuster to get the next business day (skips weekends & holidays)
public static final TemporalAdjuster NEXT_BUSINESS_DAY = temporal -> {
LocalDate date = LocalDate.from(temporal);
do {
date = date.with(NEXT_WORKING_DAY); // Reuse the simple weekend rule
} while (HOLIDAYS.contains(date)); // Also skip holidays
return temporal.with(date);
};
// The simple weekend rule from above, also made reusable
public static final TemporalAdjuster NEXT_WORKING_DAY = temporal -> {
DayOfWeek dayOfWeek = DayOfWeek.from(temporal);
int daysToAdd = 1;
if (dayOfWeek == DayOfWeek.FRIDAY) daysToAdd = 3;
else if (dayOfWeek == DayOfWeek.SATURDAY) daysToAdd = 2;
return temporal.plus(daysToAdd, ChronoUnit.DAYS);
};
// Adjuster for "Last Business Day of Month"
public static final TemporalAdjuster LAST_BUSINESS_DAY_OF_MONTH = temporal -> {
LocalDate date = LocalDate.from(temporal);
// Start from the last day of the month and work backwards
date = date.with(TemporalAdjusters.lastDayOfMonth());
while (date.getDayOfWeek() == DayOfWeek.SATURDAY ||
date.getDayOfWeek() == DayOfWeek.SUNDAY ||
HOLIDAYS.contains(date)) {
date = date.minusDays(1);
}
return temporal.with(date);
};
}
// Usage
LocalDate christmasEve = LocalDate.of(2023, 12, 24); // A Sunday
LocalDate nextBizDay = christmasEve.with(BusinessDateAdjusters.NEXT_BUSINESS_DAY);
System.out.println("After Christmas Eve, next biz day is: " + nextBizDay); // 2023-12-26
LocalDate lastBizDayOct = LocalDate.of(2023, 10, 1)
.with(BusinessDateAdjusters.LAST_BUSINESS_DAY_OF_MONTH);
System.out.println("Last business day of Oct 2023: " + lastBizDayOct); // 2023-10-31 (a Tuesday)
3. As a Full Class (Complex Rules with State)
For highly complex rules that require configuration or internal state, implement the interface with a full class.
public class NthBusinessDayAdjuster implements TemporalAdjuster {
private final int n; // 1 for first, 2 for second, -1 for last, etc.
public NthBusinessDayAdjuster(int n) {
this.n = n;
}
@Override
public Temporal adjustInto(Temporal temporal) {
LocalDate date = LocalDate.from(temporal).withDayOfMonth(1);
if (n > 0) {
// Find the nth business day
int businessDaysFound = 0;
while (businessDaysFound < n) {
if (isBusinessDay(date)) {
businessDaysFound++;
if (businessDaysFound == n) break;
}
date = date.plusDays(1);
}
} else {
// Find the nth business day from the end (e.g., -1 for last)
date = date.with(TemporalAdjusters.lastDayOfMonth());
int businessDaysFound = 0;
int target = Math.abs(n);
while (businessDaysFound < target) {
if (isBusinessDay(date)) {
businessDaysFound++;
if (businessDaysFound == target) break;
}
date = date.minusDays(1);
}
}
return temporal.with(date);
}
private boolean isBusinessDay(LocalDate date) {
return date.getDayOfWeek() != DayOfWeek.SATURDAY &&
date.getDayOfWeek() != DayOfWeek.SUNDAY &&
!BusinessDateAdjusters.HOLIDAYS.contains(date);
}
}
// Usage: Get the 3rd business day of November 2023
TemporalAdjuster thirdBusinessDay = new NthBusinessDayAdjuster(3);
LocalDate thirdBizDay = LocalDate.of(2023, 11, 1).with(thirdBusinessDay);
System.out.println("3rd business day of Nov 2023: " + thirdBizDay);
Real-World Business Use Cases
1. Financial Reporting: End-of-Quarter Processing
public static final TemporalAdjuster LAST_BUSINESS_DAY_OF_QUARTER = temporal -> {
LocalDate date = LocalDate.from(temporal);
int currentQuarter = (date.getMonthValue() - 1) / 3 + 1;
Month lastMonthOfQuarter = Month.of(currentQuarter * 3); // March, June, September, December
// Find the last business day of the quarter's final month
date = date.withMonth(lastMonthOfQuarter.getValue())
.with(TemporalAdjusters.lastDayOfMonth());
return temporal.with(BusinessDateAdjusters.LAST_BUSINESS_DAY_OF_MONTH.adjustInto(date));
};
2. HR & Payroll: Bi-weekly Pay Schedule
public static final TemporalAdjuster NEXT_PAYDAY = temporal -> {
LocalDate date = LocalDate.from(temporal);
// Assuming paydays are every other Friday
LocalDate nextFriday = date.with(TemporalAdjusters.nextOrSame(DayOfWeek.FRIDAY));
if (nextFriday.isEqual(date)) {
// If today is payday, get the next one
nextFriday = nextFriday.with(TemporalAdjusters.next(DayOfWeek.FRIDAY));
}
// Add 2 weeks to get to the bi-weekly schedule
return nextFriday.plusWeeks(2);
};
Best Practices and Considerations
- Immutability: Always return a new adjusted object. The original temporal object must remain unchanged.
- Type Safety: Check the type of the
Temporalparameter if your adjuster only works with specific types (e.g., onlyLocalDate). - Performance: For frequently used adjusters, consider caching results or optimizing the logic, especially if it involves loops or expensive calculations.
- Testing: Thoroughly test your custom adjusters with edge cases: month boundaries, leap years, holiday collisions, etc.
- Composition: You can chain adjusters using
temporal.with(adjuster1).with(adjuster2)to build complex behavior from simple ones.
Conclusion
TemporalAdjuster transforms date manipulation from imperative, procedural code into a declarative, business-focused specification. By encapsulating complex date rules into reusable components, you make your code:
- More Readable:
invoiceDate.with(NEXT_BUSINESS_DAY)is self-documenting. - More Maintainable: Holiday logic exists in one place, not scattered throughout the codebase.
- More Testable: Each adjuster can be unit tested in isolation.
- More Domain-Aligned: The code speaks the language of the business, not just the language of calendar arithmetic.
By mastering built-in adjusters and creating your own domain-specific ones, you elevate date handling from a mundane utility task to a clear expression of business policy, making your Java applications more robust and maintainable.