Class Almanac

java.lang.Object
io.leandev.appfuse.almanac.Almanac
All Implemented Interfaces:
AutoCloseable
public class Almanac extends Object implements AutoCloseable

almanac 服務入口

統一入口，組裝 AlmanacClient 與檔案型快取，並提供三個與上一代 （appfuse-common）等價的領域服務——只是資料來源由「直接連接各原始資料源」 改為「連接 almanac」：

  • calendar() — 行政機關辦公日曆（工作日 / 假日）
  • location() — 國家 / ISO 代碼與行政區劃轉換
  • address() — 台灣縣市 / 鄉鎮市區 / 村里

快取由消費端注入 CacheManager（必填）：almanac 不代建、也不提供任何預設， 由消費端決定持久化位置與生命週期，避免框架靜默落地到揮發性的系統暫存目錄。各領域 服務在注入的 CacheManager 上建立 Ehcache 磁碟層（檔案）為主、極小 heap（byte 計， 相容記憶體預算管制）為輔的快取：字典資料總量大、存取零散，放磁碟可避免記憶體配置過大 或 hit rate 過低；almanac 視為可靠來源，故不啟用雙層快取的 fallback 機制。

快取的記憶體治理（governed / ungoverned）由消費端注入的 CacheManager 決定，almanac 本身保持治理無關。建議為 almanac 注入專屬、ungoverned 的磁碟 CacheManager，與其他 受記憶體預算管制的快取隔離（字典資料以磁碟為主，不宜佔用 heap/offheap 預算）。

使用範例

```java try (CacheManager cacheManager = CacheManagerBuilder.newCacheManager() .ungoverned() .withPersistence(Path.of("/var/cache/almanac")) .build(); Almanac almanac = Almanac.builder() .apiKey("your-almanac-api-key") .cacheManager(cacheManager) .build()) { boolean holiday = almanac.calendar().isHoliday(LocalDate.of(2026, 1, 1)); String iso3 = almanac.location().convertISO2CountryToISO3("TW"); var cities = almanac.address().findAllCities(); } ```
Since:
4.0

  • Field Details

    • DEFAULT_TTL

      public static final Duration DEFAULT_TTL
      預設快取存活時間（almanac 資料更新頻率低，預設一天）

  • Method Details

    • calendar

      public CalendarService calendar()
      行政機關辦公日曆服務
      Returns:
      CalendarService（lazy 建立、單例）

    • location

      public LocationService location()
      國家 / 行政區劃代碼服務
      Returns:
      LocationService（lazy 建立、單例）

    • address

      public AddressService address()
      台灣地址（縣市 / 鄉鎮市區 / 村里）服務
      Returns:
      AddressService（lazy 建立、單例）

    • client

      public AlmanacClient client()
      取得底層 HTTP 客戶端（進階使用）
      Returns:
      AlmanacClient

    • close

      public void close() throws Exception
      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception

    • builder

      public static Almanac.Builder builder()
      建立建構器
      Returns:
      Builder