Interface FileJournal

All Known Implementing Classes:
AzureFileJournal, LocalFileJournal, NoOpFileJournal, S3FileJournal, SftpFileJournal
public interface FileJournal

檔案交易日誌 SPI（append-only，best-effort）

記錄所有會改變永久區的檔案操作及其相對於資料庫交易的生命週期，用途有二：

  1. 孤兒對帳來源：日誌存於與檔案相同的介質（Local→本地 FS、S3→S3…），脫離業務交易而存活， 讓 sweep（下一階段）能在進程崩潰後仍判定哪些實體檔案是孤兒。
  2. 稽核與除錯：可查詢的檔案生命週期軌跡，取代脆弱的純文字 log 解析。

實作慣例

  • 每個非交易對齊的儲存後端（Local / S3 / Azure / SFTP）提供一個對應介質的實作。
  • 交易對齊的後端（Database：persist/delete 為交易內 JPA 操作、隨 rollback 復原）不需要日誌， 注入 NoOpFileJournal 即可。
  • record(JournalEntry) 失敗不得中斷業務流程（best-effort WAL）；最壞情況退回 sweep 的 grace-period 與報告。

此 SPI 與 TransactionAwareFileStorage 搭配：裝飾器負責「何時記哪個狀態」（後端無關）， 本介面負責「記在哪個介質」（後端相關）。

  • Method Details

    • record

      void record(JournalEntry entry)
      記錄一筆檔案交易事件（append-only，不得拋出例外中斷業務流程）
      Parameters:
      entry - 事件

    • readEntries

      List<JournalEntry> readEntries(String partition)
      讀取指定 partition 的所有事件，供 FileOrphanSweepTask 對帳使用
      Parameters:
      partition - 儲存分區鍵
      Returns:
      事件清單（依時間排序；無資料時回傳空清單）

    • partitions

      List<String> partitions()
      列出所有有日誌的 partition，供 FileOrphanSweepTask 逐區對帳
      Returns:
      partition 清單（無資料時回傳空清單）