XPages 的 ViewEntry:用 getColumnValues 讀 view,不開每份文件
在 XPages 你要列一批資料——一個 typeahead 清單、一段要回給前端的 JSON、一個自訂樣式的 repeat。要顯示的欄位,其實某個 view 裡都排好了。直覺的寫法是走訪那個 view、每一列 getDocument() 再 getItemValueString(...)。
問題是那樣等於把每份文件都開一次。一個欄位要顯示的清單有幾千列,你就開幾千份文件——大 view 會明顯慢。而這些值其實在 view 的索引裡就有了,根本不必開文件。
讀索引層欄值的那個東西,就是 NotesViewEntry。官方定義「A view entry describes a row in a view.」——它代表 view 裡的一列,getColumnValues 直接給你這一列每一欄的值。這篇講在 XPages 怎麼拿 ViewEntry、欄值怎麼讀、一個容易混淆的集合差別,以及 recycle 的事。
拿 entry 與讀欄值
在 XPages 後端,最常見的取法是從 view 拿一整個集合 getAllEntries,再一列一列走:
var view = database.getView("byCustomer");var col = view.getAllEntries(); // NotesViewEntryCollectionvar entry = col.getFirstEntry();var out = [];while (entry != null) { var vals = entry.getColumnValues(); // 這一列每一欄的值(索引層,不開文件) out.push({ name: vals[0], total: vals[2] }); var next = col.getNextEntry(entry); entry = next;}getColumnValues 回的是官方說的「The value of each column in the view entry.」——照 view 欄位的順序排好的一個陣列,vals[0] 是第一欄、vals[2] 是第三欄。要顯示的東西如果 view 欄位裡都有,整趟走訪一份文件都不用開。真的需要背後的文件(例如要讀 view 沒放的欄位)才 entry.getDocument(),那時才付開文件的成本。
一個容易混淆的點:集合只含 document 列
這裡有個很多人被咬過的細節。getAllEntries 回的 NotesViewEntryCollection,官方定義是「Represents a collection of view entries of type document sorted in view order.」——它只含 document 列。
但一個 view 的列其實有三種:document、category、total。如果你的 view 是分類式的、你想連 category 列(分類標題)一起處理——getAllEntries 給不了你,它把 category 和 total 都濾掉了。要走到 category 列,得改用 ViewNavigator,它會給你全部三種;那時用 isCategory() / isDocument() 判斷每一列是哪種。ViewNavigator 的走訪與效能,見 Java 的 ViewNavigator 那篇(SSJS 的 NotesViewNavigator 建立與走訪方式一樣)。
一句話記法:要清單(只要文件列)用 getAllEntries;要連分類標題一起處理,用 ViewNavigator。
XPages 不用自己 recycle
如果你讀過 Java 版的走訪,會記得每個 ViewEntry 用完都要 recycle(),否則 C 層 handle 爆掉。在 XPages 的 SSJS 裡不用——這些物件的生命週期由 XPages request 管,request 結束時一起收。你專心把走訪寫對就好。
但有一點仍要注意:大 view 的整趟走訪是個重操作,別把它掛在每次 partial refresh 都會重跑的路徑上。放進明確的事件、或把結果快取起來,跟所有貴的後端操作一樣。
同類別在其他語言
同一個 ViewEntry:
- LotusScript:
NotesViewEntry,ColumnValues、GetDocument、IsCategory都在,行為一致。 - Java:
ViewEntry,API 相同,但每個 entry 用完要手動recycle();走大 view 的效能細節(gotovsget、CacheSize)見 Java 的 ViewNavigator 那篇。 - SSJS 專屬的不是 API(方法共用),而是在 XPages 怎麼用:直接讀
getColumnValues組 typeahead / JSON 不開文件、生命週期由 request 管不用 recycle,還有別把大 view 走訪掛在 partial refresh 的路徑上。
參考來源
- NotesViewEntry (JavaScript)(ColumnValues、document/category/total 三型別、Document/IsCategory)— HCL Domino 14.5 Designer Help(官方)
- NotesViewEntryCollection (JavaScript)(getAllEntries;只含 document 列;Count/getFirstEntry)— HCL Domino 14.5 Designer Help(官方)
- NotesView (JavaScript)(getAllEntries / getEntryByKey 等取得 entry 的方法)— HCL Domino 14.5 Designer Help(官方)