Java 的 ViewEntryCollection:stampAll 一次改,FTSearch 窄化,集合運算組條件

Java 的 ViewEntryCollection:stampAll 一次改,FTSearch 窄化,集合運算組條件

2026.11.21 約 757 字

你用 view.getAllEntries() 或 getAllEntriesByKey(key) 拿到一批照 view 排序的文件 entry,接下來要對它們做事:把某個欄位全部改成同一個值、把範圍再用全文搜尋縮小、或把「A 查詢的結果」扣掉「B 查詢的結果」。

第一反應是走迴圈,每筆 getDocument() 再 replaceItemValue 再 save。可以,但 ViewEntryCollection 本身就有批次與集合運算,很多情況一行就夠。官方定義它是「Represents a collection of view entries of type document sorted in view order.」——注意「of type document」:它只含文件列,沒有 category 或 total 列。

這篇講 stampAll、FTSearch、集合運算三招,以及走訪的兩個邊界。


stampAll:一次改整批的某個欄位

要把一批 entry 背後的文件某個欄位全部設成同一值,不用自己迴圈 save——stampAll 一行搞定。官方「Replaces the value of a specified item in the documents of all the entries in a view entry collection.」:

view.setAutoUpdate(false);
ViewEntryCollection vec = view.getAllEntriesByKey("Pending");
vec.stampAll("Status", "Processed"); // 整批 Status 設成 Processed

跟 NotesDocumentCollection 的 stampAll 是同一招,只是來源是 view entry 的集合。要把一批照某個 key 選出來的文件統一改狀態、蓋處理時間,這比迴圈乾淨得多。

FTSearch:把集合原地窄化

拿到一個 collection 之後,還能再用全文搜尋把它縮小。FTSearch 官方「Conducts a full-text search on all entries in a view entry collection and filters the collection.」——它是原地的:搜完之後,這個 collection 就只剩符合查詢的那些 entry(前提是資料庫有全文索引)。搜完的查詢字串會留在 Query 屬性裡。

ViewEntryCollection vec = view.getAllEntries();
vec.FTSearch("urgent"); // vec 現在只剩內文含 urgent 的

集合運算:組合兩個查詢

這是 ViewEntryCollection 比 DocumentCollection 更順手的地方——intersect / merge / subtract 讓你把兩批結果組起來:

  • intersect——交集,只留同時也在另一批的。
  • merge——聯集,把另一批併進來。
  • subtract——差集,把另一批移除。

要「今年的訂單裡,排除已經歸檔的」這種組合條件,先各自選出兩批、再 a.subtract(b),比寫一條複雜 key 或公式乾淨。要依位置取第幾筆用 getNthEntry(n)(在 view 排序下),要數量用 Count(屬性,不是方法)。每個 entry 裡的欄值怎麼讀(不開文件),見 ViewEntry 的說明。

兩個邊界:autoupdate 與 recycle

走訪或批次操作一個 collection 前,先把 view 的 setAutoUpdate(false)。官方警告自動更新會降效、還會讓你手上的 entry 失效,報「Entry not found in index」——你一邊處理、別人一邊改 view,就中這個。需要最新資料自己 refresh。

另外在 Java 裡,collection 走訪出來的每個 ViewEntry 用完都要 recycle(),否則大集合會把 C 層 handle 累爆;紀律見 改寫成 Java 後記憶體爆掉。要懶走訪一個超大 view(含 category 列、要效能旋鈕),那是 ViewNavigator 的場,見 Java 的 ViewNavigator 那篇。

同類別在其他語言

同一個 ViewEntryCollection:

  • LotusScript:NotesViewEntryCollection,StampAll / FTSearch / Intersect / GetNthEntry 都在,行為一致但不用 recycle;見 NotesViewEntry 那篇。
  • SSJS / XPages:NotesViewEntryCollection,同樣的 stampAll / 集合運算;生命週期由 request 管不用 recycle。DocumentCollection 版的批次操作見 SSJS 的 DocumentCollection 那篇。
  • Java 專屬的不是 API(方法共用),而是記憶體紀律:stampAll / 集合運算雖然是一行,但如果你改走逐筆迴圈,每個 entry 都要自己 recycle——強型別不會提醒你這件事。

參考來源

← 回到文章列表