在 IBM Lotus Domino Designer 中用 Java 開發 Agent 完整指南

面向傳統 LotusScript 開發者，本文從 Java 語法對比、Domino 對象模型映射、三大實戰案例（發郵件、遍歷視圖、生成郵件報表）、JVM 版本、recycle 內存管理、安全策略、外部 JAR 引用等全方位講解，助你平滑遷移到 Java Agent 開發。

Java Agent 基礎骨架

import lotus.domino.*;
public class JavaAgent extends AgentBase {
    public void NotesMain() {
        try {
            Session session = getSession();
            AgentContext agentContext = session.getAgentContext();
            // 業務代碼
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

• 繼承 AgentBase，覆寫 NotesMain() 入口。
• 通過 getSession() 獲取會話，getAgentContext() 獲取當前上下文（數據庫、用戶等）。
• 異常必須用 try-catch 捕獲，Domino 方法拋出 NotesException。

LotusScript vs Java 核心差異速查

實戰案例一：發送郵件

關鍵差異：

• Java 用 agentContext.getCurrentDatabase() 而非 session.CurrentDatabase。
• 創建富文本用 doc.createRichTextItem("Body") 而非 New NotesRichTextItem。
• 所有 Domino 對象用完必須 recycle()，防止 C++ 底層句柄洩漏導致服務器崩潰。

實戰案例二：遍歷視圖文檔

View view = db.getView("ViewName");
Document doc = view.getFirstDocument();
Document tmp;
while (doc != null) {
    System.out.println(doc.getCreated());
    tmp = view.getNextDocument(doc);
    doc.recycle();          // 關鍵：釋放當前文檔
    doc = tmp;
}

循環中必須用臨時變量接收下一個文檔，隨即 recycle() 當前文檔，否則內存線性增長。

實戰案例三：掃描郵件庫生成報表

• 打開 names.nsf 的 People 視圖，遍歷人員文檔。
• 用 session.getDatabase(mailServer, mailFile) 打開各郵件庫。
• 捕獲異常處理「無法打開郵件庫」情況，寫入報表 RichTextItem。
• 循環內同樣嚴格 recycle() 每個臨時 Database 與 Document。

進階必知：recycle()、JVM 版本、安全策略、外部 JAR

• recycle()：無條件銷毀底層 C++ 對象並歸還內存，參考 Technote #1097861。所有 Domino 對象（含 Session、AgentContext）均需調用。
• JVM 版本：Domino 6.5→1.3.1, 7.0→1.4.2, 8.0→1.5.0, 8.5→1.6.0。使用新 API 時注意版本對應。
• 安全異常：遇到 AccessControlException 需在 java.policy 授權。
• 外部 JAR：三種方式——附加到 Agent、放入 jvm/lib/ext、配置 JavaUserClasses notes.ini 變量。

遷移建議

1. 先用 Domino Designer 8.5+ 幫助文檔中的 Java 範例練手。
2. 將現有 LotusScript Agent 逐模塊重寫，對照本文差異表修正語法。
3. 嚴格執行「創建即規劃 recycle」的代碼規範，納入 Code Review 清單。
4. 利用 Java 豐富的生態（JSON、HTTP Client、加密庫等）擴展 Agent 能力，超越 LotusScript 限制。