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

Interface HolidayCalendarService

All Known Implementing Classes:
AbstractHolidayCalendarService
public interface HolidayCalendarService
Required behavior of a service which provides the HolidayCalendar object assigned to a unique code identifier.
Author:
Dave Joyce

  • Method Summary

    Modifier and Type
    Method
    Description
    default OptionalInt
    dataValidThrough()
    Returns the latest year for which this service provides authoritative holiday data for all lookup-table-backed holidays in this calendar.
    default String
    getCode()
    Get the short code identifier for the holiday calendar provided by this service.
    HolidayCalendar
    getHolidayCalendar()
    Get the holiday calendar object provided by this service.
    default String
    getRegion()
    Get the human-readable name of the region for this holiday calendar.
    boolean
    isProvided(String code)
    Determine if this service provides the HolidayCalendar for the specified code.

  • Method Details

    • isProvided

      boolean isProvided(String code)
      Determine if this service provides the HolidayCalendar for the specified code.
      Parameters:
      code - short code identifier of desired holiday calendar
      Returns:
      true if this service provides the holiday calendar for the given code, false otherwise

    • getHolidayCalendar

      HolidayCalendar getHolidayCalendar()
      Get the holiday calendar object provided by this service.
      Returns:
      holiday calendar object

    • getCode

      default String getCode()
      Get the short code identifier for the holiday calendar provided by this service. Returns null if not implemented.
      Returns:
      short code identifier, e.g. "US", "UK"

    • getRegion

      default String getRegion()
      Get the human-readable name of the region for this holiday calendar. Returns null if not implemented.
      Returns:
      region name, e.g. "United States National Holidays"

    • dataValidThrough

      default OptionalInt dataValidThrough()
      Returns the latest year for which this service provides authoritative holiday data for all lookup-table-backed holidays in this calendar.

      An empty result indicates that every holiday in this calendar is computed algorithmically and therefore has no known upper bound — all years are equally authoritative (e.g. Easter-based or nth-weekday rules).

      A non-empty result indicates that one or more holidays are backed by a finite, officially-gazetted lookup table. The returned value is the last year for which all such tables have been populated. For years beyond this value, HolidayCalendar.calculate(int) will silently omit those holidays without throwing an exception. This method is an advisory signal only — it does not alter calculate() behaviour. Callers that require complete data should verify that the requested year does not exceed this bound before invoking calculate().

      Implementations backed by lookup tables must override this method and return OptionalInt.of(lastTableYear), where lastTableYear is the minimum of the last year covered by each individual lookup table in the calendar. Subclasses of AbstractHolidayCalendarService that use lookup tables should override this method accordingly.

      Returns:
      the last year for which data is fully authoritative, or OptionalInt.empty() if the calendar is fully algorithmic with no known upper bound