Module org.holiday.calendar.core
Package org.holiday.calendar

Class HolidayCalendar

java.lang.Object
org.holiday.calendar.HolidayCalendar
public class HolidayCalendar extends Object
A named collection of holidays observed within a single calendar year. An instance of this class defines the days on which activities may not occur.
Author:
Dave Joyce

  • Field Details

    • NO_ROLL

      public static final DateRoll NO_ROLL
      Default 'empty' date rolling behavior.

    • STANDARD_WEEKEND

      public static final Set<DayOfWeek> STANDARD_WEEKEND
      Default days of week that constitute the 'standard' weekend worldwide.

  • Constructor Details

    • HolidayCalendar

      public HolidayCalendar(String code, String name, DateRoll dateRoll, Set<DayOfWeek> weekendDays, Set<Holiday> holidays)
      Construct a new holiday calendar object.
      Parameters:
      code - short text code symbol by which this calendar may be located
      name - name of this holiday calendar object
      dateRoll - date rolling behavior to be employed by this holiday calendar
      weekendDays - days of the week to be treated as the weekend
      holidays - set of Holiday objects to be observed

  • Method Details

    • builder

      public static HolidayCalendar.HolidayCalendarBuilder builder()

    • getCode

      public String getCode()

    • getName

      public String getName()

    • getDateRoll

      public DateRoll getDateRoll()

    • getHolidays

      public Set<Holiday> getHolidays()
      Get holidays observed on this calendar.
      Returns:
      unmodifiable set of Holiday objects

    • getWeekendDays

      public Set<DayOfWeek> getWeekendDays()
      Get weekend days recognized by this calendar.
      Returns:
      unmodifiable set of weekend days

    • isWeekend

      public boolean isWeekend(Instant instant, ZoneId zoneId)
      Determine if the given instant, in the specified time zone, falls on the weekend as defined by this holiday calendar.

    • isWeekendUTC

      public boolean isWeekendUTC(Instant instant)
      Determine if the given instant, in UTC standard time, falls on the weekend as defined by this holiday calendar.

    • isWeekend

      public boolean isWeekend(Date date, TimeZone timeZone)
      Determine if the given date, in the specified time zone, falls on the weekend as defined by this holiday calendar.

    • isWeekendUTC

      public boolean isWeekendUTC(Date date)
      Determine if the given date, in UTC standard time, falls on the weekend as defined by this holiday calendar.

    • calculate

      public List<HolidayDate> calculate(int year)
      Calculate the dates of the holidays on this calendar for the specified year. The dates returned by this method are adjusted according to the date rolling behavior of this calendar.

      Breaking change (since 2.0.0): this method excludes EarlyCloseHoliday entries. In 1.x, early-close (half-day) holidays were returned alongside full closures; callers upgrading from 1.x that relied on seeing early closes here must additionally call calculateEarlyCloses(int). For example, to retrieve both regular and early-close holidays for a year: 

      
 List<HolidayDate> fullClosures = calendar.calculate(2026);
 List<HolidayDate> earlyCloses = calendar.calculateEarlyCloses(2026);
      Parameters:
      year - Common Era (CE) year for which to obtain holiday dates
      Returns:
      chronologically-sorted list of observed holiday dates, excluding EarlyCloseHoliday entries
      See Also:

    • calculateEarlyCloses

      public List<HolidayDate> calculateEarlyCloses(int year)
      Calculate the dates of the early-close (partial trading day) holidays on this calendar for the specified year. Only EarlyCloseHoliday instances are considered; these are inherently non-rollable, so no date rolling is applied.

      Early closes are deliberately excluded from calculate(int) and are reported exclusively by this method. Each returned HolidayDate wraps an EarlyCloseHoliday, whose EarlyCloseHoliday.getCloseTime() and EarlyCloseHoliday.getZoneId() give the local trading-halt time — for example, the ASX (Australia) calendar reports a 14:10 Australia/Sydney close on Christmas Eve, while NYSE reports a 13:00 America/New_York close on the day after Thanksgiving: 

      
 for (HolidayDate hd : calendar.calculateEarlyCloses(2026)) {
     EarlyCloseHoliday h = (EarlyCloseHoliday) hd.holiday();
     System.out.printf("%s: %s closes at %s %s%n",
         hd.getDate(), h.getName(), h.getCloseTime(), h.getZoneId());
 }
      Parameters:
      year - Common Era (CE) year for which to obtain early-close dates
      Returns:
      chronologically-sorted list of early-close holiday dates
      See Also:

    • hasEarlyCloses

      public boolean hasEarlyCloses()
      Determine whether this calendar has any EarlyCloseHoliday entries configured. This is a cheap, year-independent check that lets callers branch without invoking calculateEarlyCloses(int).
      Returns:
      true if this calendar has at least one early-close holiday
      See Also:

    • calculate

      public List<HolidayDate> calculate(int fromYear, int toYear)
      Calculate the dates of the holidays on this calendar for each year in the specified range, returning all results as a single chronologically- sorted list.

      The dates returned are adjusted according to the date rolling behavior of this calendar. Note that a rolled date may fall outside the nominal year range (e.g. a Dec 31 holiday rolled forward to Jan 1 of the following year).

      Passing fromYear == toYear is legal and returns the same result as calculate(int).

      Parameters:
      fromYear - first Common Era (CE) year in the range (inclusive)
      toYear - last Common Era (CE) year in the range (inclusive)
      Returns:
      chronologically-sorted list of observed holiday dates across all years in [fromYear, toYear]
      Throws:
      IllegalArgumentException - if fromYear > toYear
      See Also:

    • calculateByYear

      public Map<Integer,List<HolidayDate>> calculateByYear(int fromYear, int toYear)
      Calculate the dates of the holidays on this calendar for each year in the specified range, returning results grouped by year.

      The map contains an entry for every year in [fromYear, toYear] inclusive — years with no holidays map to an empty list (dense representation). Each list is chronologically sorted. The map itself is ordered by ascending year.

      Note: the year key is the nominal year used for calculation. A rolled date may have a HolidayDate.getDate() whose year differs from the map key.

      Passing fromYear == toYear is legal.

      Parameters:
      fromYear - first Common Era (CE) year in the range (inclusive)
      toYear - last Common Era (CE) year in the range (inclusive)
      Returns:
      map of nominal year to chronologically-sorted observed holiday dates, ordered by ascending year; all years in the range are present as keys
      Throws:
      IllegalArgumentException - if fromYear > toYear
      See Also:

    • merge

      public HolidayCalendar merge(HolidayCalendar other)
      Merge the given HolidayCalendar object with this one.
      Parameters:
      other - holiday calendar to be merged
      Returns:
      union of this holiday calendar and the specified calendar

    • toString

      public String toString()
      Overrides:
      toString in class Object