#Java
標記為 #Java · 24 篇文章
- Java 的 ViewEntryCollection:stampAll 一次改,FTSearch 窄化,集合運算組條件
你用 view.getAllEntries() 或 getAllEntriesByKey(key) 拿到一批照 view 排序的文件 entry,接下來要對它們做事:把某個欄位全部改成同一值、把範圍再用全文搜尋縮小、或把「A 查詢的結果」扣掉「B 查詢的結果」。第一反應是迴圈、每筆 getDocument 再 save——但 ViewEntryCollection 本身就有批次與集合運算:stampAll 一次改整批某個欄位、FTSearch 原地把集合窄化成符合的子集、intersect/merge/subtract 做交集聯集差集。這篇講這三招、getNthEntry 依位置取、以及走訪前要把 view 的 autoupdate 關掉(否則會 Entry not found in index)和每個 entry 要 recycle。
2026.11.21 - Java 改 ACL:不呼叫 save(),關庫後全部白改
你在 Java 用程式改一個資料庫的 ACL:把某個人升到 Editor、幫他開一個 role、再加一條新 entry。每一步 API 都成功、沒報錯。結果重開資料庫一看,什麼都沒變。原因是 ACL 的修改不會自動存——官方白紙黑字:不在關庫前呼叫 save,你對 ACL 做的改動就會遺失,而且沒有任何警告。這篇講怎麼拿 ACL、改一條 entry 的 level、roles 的「定義」與「授予」是兩層、最大的那個 save 坑,以及別把 Database 的 grantAccess 跟手上的 ACL 物件混用。
2026.11.19 - Java 的 QueryResultsProcessor:多來源結果跨庫合併排序,輸出 view 或 JSON
你手上有來自三個不同資料庫的文件集合,要合成一份、照同一個欄位排序、算個小計,最後給前端一段 JSON 或存成一個 view。土法是把三批都拉進記憶體、自己 merge、自己 sort——跨庫、資料量一大就撐不住。QueryResultsProcessor(R12 之後)把這件事做在 server 端:官方一句話是「Aggregates, computes, sorts, and formats collections of documents across any set of Domino databases.」。你用 addCollection / addDominoQuery 把多個來源(各給一個唯一名稱)餵進去、用 addColumn 定義要回哪些欄與怎麼排,再 executeToView 存成一個會自動過期的 results view、或 executeToJSON 直接拿 JSON。這篇講這個「多輸入、一輸出」的形狀、兩種輸出的差別與坑,以及建立它的方法名(官方頁自己寫錯的那個)。
2026.11.18 - Java 比對 Notes 使用者名稱:同一個人卻不相等?先正規化再比
你在 Java 比對兩個 Notes 使用者名稱——一個是登入者 session.getUserName()、一個是存在文件裡的簽核人。明明是同一個人,字串 equals 卻回 false。原因是同一個人的名字在不同地方形式不一樣:一邊是 canonical 的 CN=John B Goode/O=Acme/C=US,另一邊是 abbreviated 的 John B Goode/Acme/US,或只是 common 的 John B Goode。直接比字串當然不相等。正解是用 session.createName 把兩邊都正規化成同一形式(例如都 getCanonical)再比。這篇講 Name 的三種形式、怎麼正確比對、怎麼拆出名字的各個部分(OU、O、C)來判斷某人在不在某個組織單位,以及它也能解析 RFC 821/822 的 internet 地址。
2026.11.16 - Java 的 ViewNavigator:讀大 view 要關 autoupdate、設 CacheSize
一個十幾萬筆的 view,你在 Java 要走過每一列做點事。用 getAllDocuments 會先把整批拉進記憶體,大 view 直接撐爆。ViewNavigator 不一樣——它沿著 view 的索引一列一列走,拿到的是 ViewEntry(索引層的 row 資料),不必逐筆開 Document。但要它真的快,有三個旋鈕得自己調:把 IsAutoUpdate 設成 false(背景自動更新會降效、還會讓 navigator 手上的 entry 失效),遠端操作時設 CacheSize 減少 server 往返,還有只需要移動指標、計數時用 goto 系列而不是 get 系列(官方明說 goto 不會建立 ViewEntry 物件)。這篇講怎麼建對走訪範圍、這三個效能旋鈕,以及走訪時每個 entry 要 recycle 的記憶體紀律。
2026.11.14 - Java 讀 MIME:不先 setConvertMIME(false),你讀到的就不是 MIME
現代 Domino 的郵件 Body 多半是 MIME(多段式、帶 headers),不是傳統的 composite rich text。你在 Java 用 getFirstItem("Body") 去讀,Domino 預設會把 MIME 自動轉成 rich text 再給你——結果你拿到的是轉換後的東西,原本的 MIME 結構、headers、編碼都在轉換裡被攤平了。要拿到真正的 MIME,得先呼叫 session.setConvertMIME(false) 關掉這個自動轉換,再 getMIMEEntity。這篇講讀 MIME 的正確順序、怎麼走訪 multipart 的每一段、怎麼讀 headers,以及一個很會咬人的失效規則:MIMEEntity 在你對 Document 做 save / computeWithForm / sign 之後就失效了。
2026.11.13 - Java 的 Stream 讀寫檔案:預設 charset 不是 Unicode,是 System
在 Java 你要把一份文件的文字寫成檔案、或讀一個檔案進來。Domino 的 Stream(session.createStream)是跟 Domino 編碼體系整合的那條路,也是 MIMEEntity、附件底層在用的串流。但它有個會讓中文默默變亂碼的坑:新建的 Stream 回報 Charset 是 Unicode,可是 open(path) 沒帶 charset 參數時,預設卻是 System(伺服器的平台編碼)——不是 Unicode。這篇講怎麼拿到 Stream、open 的 charset 陷阱、writeText 預設不加行尾(EOL_NONE)的小坑、binary 模式與 getContents/setContents 怎麼接 java.io,以及 thread 限定和 recycle 兩個邊界。
2026.11.11 - Java 讀附件:用 getInputStream 不落地,還有兩個會咬你的坑
在 Java 你要一份附件的 bytes——串給瀏覽器、算雜湊、推去物件儲存。直覺是先 extractFile 存成暫存檔、再讀那個檔;但 EmbeddedObject 在 Java 有 getInputStream,直接把附件內容當串流讀出來、一個暫存檔都不用。這篇講 Java 讀附件的串流做法,以及兩個官方文件白紙黑字、但很容易中的坑:extractFile 對「不是附件」的 embedded object / object link 會丟例外;而 Document.getEmbeddedObjects 根本不回傳 file attachment——附件要從 RichTextItem 拿。順帶一個平台現實:UNIX/Mac 的 Domino 只支援 file attachment,沒有 embedded object。
2026.11.10 - Java 讀 rich text:先 cast,再小心 MIME 和被丟掉的附件
在 Java 要碰一個 Body 這種 rich text 欄位,getFirstItem 回給你的是一個 Item,你得先 cast 成 RichTextItem 才能用——而這一步藏了兩個意外:這份 body 現在很可能是 MIME、不是傳統 rich text(那要走 getMIMEEntity);還有,你用 getFormattedText 把內容讀成純文字時,它會「順手」把附件和圖片這些非文字內容丟掉。這篇講 Java 怎麼取到(cast 與 MIME)、怎麼把 rich text 讀成純文字(getFormattedText 的三個參數與它丟掉的東西)、以及怎麼用 createRichTextItem 建立一個。
2026.11.08 - Java 讀 view:別為了一欄去開整份文件
要列出 view 裡每一筆的幾個欄位做報表,直覺會一路 getNextDocument、每份文件 getItemValue——在 Java 這等於把成千上萬份 NotesDocument 從後端拉出來、再一一 recycle。但那些欄位的值,view 的每一列(ViewEntry)本來就帶著:getColumnValues() 一次讀整列、一份文件都不開。這篇講 Java 怎麼取到 view(getView 的 view/folder 與 name/alias 兩個坑)、為什麼讀欄位要用 ViewEntry 而不是 Document、怎麼用 getAllEntriesByKey 依 key 查,以及迭代前為什麼要 setAutoUpdate(false)。
2026.11.07 - Java 開 Notes Database:路有很多條,陷阱只有一個
LotusScript 裡 session.GetDatabase 開不到會回 Nothing,你習慣性 Is Nothing 一擋就沒事。同一行搬到 Java,getDatabase 卻**不會**回 null —— 它照樣給你一個 Database 物件,只是 isOpen 是 false,一個指向不存在的庫的空殼。這篇講 Java 怎麼取得並持有一個 Database handle:它從 Session 來、開庫有哪幾條路(getCurrentDatabase / getDatabase / DbDirectory)、那個「回了物件不代表庫開了」的陷阱怎麼擋,以及 Database 在 recycle 父子鏈的位置 —— recycle 早了,你手上開著的 View 和 Document 會一起死。
2026.11.05 - Java 端的 DXL:DxlExporter/DxlImporter 怎麼把 Domino 資料進出 XML
要把設計元素在資料庫之間搬、或把文件快照成 XML 做 diff/備份,DXL 就是 Domino 的 XML 表示法。在 Java 裡兩個主力是 DxlExporter(Domino→DXL,exportDxl 回一個 String)與 DxlImporter(DXL→Domino,importDxl 寫進目標 DB)。重點是:import 不是「把 XML 灌進去」這麼單純——你要用 setDesignImportOption/setDocumentImportOption/setAclImportOption 告訴它 design、文件、ACL 各自要 create/replace/update 還是 ignore,還有 replica 要不要相符。這篇整理兩個類別的建立與方法、import 的策略選項,以及跟 LotusScript 版的關係。
2026.10.04 - XPages managed bean:給 SSJS 一個真正的 Java 物件,像 database 一樣直接用
SSJS 寫在 script library 裡當膠水很方便,但邏輯一多就難維護——沒有真正的型別、難測試、塞進 scope 還有序列化問題。managed bean 讓你在 faces-config.xml 宣告一個 Java class,它就變成 SSJS 與 EL 裡的一個頂層變數,用起來跟 database、session 一樣——bean.method()、#{bean.prop}。這篇講 managed bean 怎麼宣告(name/class/scope 三元素)、class 的三個要件(no-arg 建構子、get/set、Serializable)、scope 的生命週期,以及邏輯什麼時候該從 SSJS 搬進 bean。
2026.10.03 - NotesThread:在 Domino 開背景執行緒的規矩——每條 thread 要 init、要自己的 session
在 Java 裡想開一條背景執行緒去跑 Domino 的 local 呼叫,直接 new Thread 是不行的——會拿不到 Notes 執行環境。要嘛繼承 NotesThread 覆寫 runNotes()、要嘛實作 Runnable 交給 NotesThread、要嘛自己在頭尾呼叫 sinitThread()/stermThread()。而且每條 thread 要有自己的 Session、自己 recycle,不能跨執行緒共用。這篇整理 NotesThread 的三種寫法、sinitThread/stermThread 的配對規則、每執行緒一個 session 的鐵律,以及背景執行緒裡拿不到 sessionAsSigner 的現實。
2026.09.30 - Domino IQ 逾時的 Java 解法:LLMReq.completionStream,以及 XPages SSJS 怎麼調用它
昨天那篇用 LotusScript 的 CompletionStream 突破了 Domino IQ 的 5 分鐘逾時;如果你的程式是 Java(agent、bean)或 XPages(SSJS),撞到的是同一個逾時。這篇給 Java 版:LLMReq.completionStream 搭配 CompletionStreamCallback 介面(回傳 Continue/Stop 控制串流),以及一個關鍵事實——SSJS 沒有原生的 LLM class,但 SSJS 的 session 就是 lotus.domino.Session,所以你可以直接調用 Java API,或把串流包成 Java class 再從 SSJS 引用。附三種語言一張對照表。
2026.09.06 - Java 的 NotesException:.id、.text 與 try/catch/finally
LotusScript 的錯誤處理是 On Error Goto、Err.Number、Resume 那一套。搬到 Java,幾乎每個 lotus.domino 方法都會丟一個受檢的 NotesException——編譯器逼你處理,而它身上帶著 .id(Notes 錯誤碼)與 .text(錯誤訊息)。這篇講 Java 版的例外處理:NotesException 的欄位、怎麼用 .id 比對 NotesError 常數做針對性處理,以及把這整個 Java 資料層系列收在一起的那條規則——recycle 要放進 finally,這樣連拋例外時也收得乾淨。
2026.08.17 - 在 Java 裡迴圈跑 DocumentCollection:先拿下一份,再 recycle 這一份
LotusScript 裡跑一個 DocumentCollection,你 Set doc = coll.GetNextDocument(doc) 一路跑到底,從不想記憶體的事。搬到 Java,同一個迴圈跑上萬份文件會把 agent 記憶體吃垮——除非你在迴圈裡 recycle 每一份,而且順序不能錯:得先用當前這份拿到下一份、再 recycle 當前這份。這篇講 Java 版的正確迭代寫法:DocumentCollection 的 getFirstDocument/getNextDocument、刪除標記的 isValid、什麼時候該改用更省的 ViewNavigator,以及那個 LotusScript 從不需要煩惱的 recycle 順序。
2026.08.16 - 在 Java 裡處理 Notes 日期,為什麼不能直接用 java.util.Date?
在 Java 裡處理 Notes 的日期,你不能直接用 java.util.Date——中間隔著一個 lotus.domino.DateTime。它是個背後連著 handle 的重量級後端物件,在迴圈裡不 recycle 就漏記憶體;它用字串在存日期、壞值會丟例外;而 toJavaDate() 是你把它換成 Java 自家時間型別、再接上 java.time 的那座橋。這篇講 Java 版 DateTime 怎麼建、怎麼讀寫、怎麼跟 Java 的時間世界互轉,以及那個從 LotusScript 帶不過來的 recycle 負擔。
2026.08.15 - Java 讀寫 Notes item:getItemValue 回的是 Vector,不是你熟的那種陣列
LotusScript 裡 doc.GetItemValue 回一個 Variant 陣列,你 For 一圈就完事。搬到 Java,同一個呼叫回的是 java.util.Vector,元素型別要自己認、缺欄位不丟例外只回空的、裡面若是 DateTime 還會漏記憶體。這篇把 Java 版 Document 的讀寫 item 講清楚:getItemValue 與那幾個型別化 getter 的回傳與缺欄位行為、replaceItemValue 接受哪些 Java 型別又會自動建 item、appendItemValue 為什麼會默默建出重複 item,以及三個 LotusScript 帶不過來的雷。
2026.08.14 - Java agent 的骨架:觸發、權限、輸出、除錯
前三篇都假設「agent 已經在跑」——會 recycle、拿到 Session、跑 DQL。但一個 Java agent 到底怎麼被觸發、用誰的權限執行、System.out 跑去哪、怎麼 debug?這篇補上最前面那一步:AgentBase/NotesMain 骨架、Trigger 與 unprocessedDocuments、agent signer 決定的權限、restricted/unrestricted,以及 System.out 進 log.nsf 的除錯路徑。
2026.08.10 - 在 Java 裡跑 DQL:DominoQuery 與 QueryResultsProcessor
站上的 DQL 三部曲教你寫查詢,但那是從 LotusScript 或 console 跑的。搬到 Java,DQL 走兩個類別:DominoQuery 負責編譯、調校、執行,QueryResultsProcessor 負責排序、彙總、跨庫 join、輸出 JSON。還有一個容易錯的地方——這兩個都從 Database 取得,不是 Session。這篇拆解 Java 端怎麼把 DQL 跑起來。
2026.08.09 - 在 Java 裡拿到 Session:NotesFactory、local 與遠端
LotusScript 的 session 是個你從來不必建立的全域變數;Java 沒有它。碰任何一份文件之前,你得自己先取得一個 Session——而怎麼拿,取決於你的 code 跑在 agent、獨立程式,還是遠端。這篇拆解 NotesFactory 的三條取得路徑、local(JNI) 與遠端(DIIOP) 的差別、誰建誰收的 recycle 規則,以及位元數與每執行緒一個 session 這兩個常見地雷。
2026.08.08 - LotusScript 改寫 Java 後記憶體爆掉?你可能忘了 recycle()
同一段邏輯,LotusScript 跑一輩子都沒事,搬到 Java 版的 lotus.domino 卻會在幾萬份文件的迴圈裡把 agent 記憶體吃垮。原因是每個 Java 物件背後都連著一個垃圾回收看不到的後端 handle。這篇拆解機制、四條官方規則、迴圈洩漏樣式與安全寫法、NotesThread 的角色,以及 local 與遠端 session 的差異。
2026.08.07 - NSF ODP Tooling:不開 Designer,把 NSF 變成可版控的原始碼
NSF ODP Tooling 是 OpenNTF 的專案,把二進位的 NSF 拆成檔案系統上的 On-Disk Project(ODP),讓你能把 Domino 應用放進 Git,再不靠 Domino Designer 就把 ODP 編譯回完整的 NSF —— 為 Domino 帶來真正的版本控制與 CI/CD。本文完整介紹它是什麼、Maven plugin 與容器化編譯怎麼運作,以及 4.1.0 這一版實際改了什麼。
2026.06.27