XPages 的 database 是現成的,問題在「用誰的權限開」
LotusScript 要 session.GetDatabase 加判斷,Java 還要先生出 Session、再 getDatabase、再查 isOpen。XPages 的 SSJS 省了這一整段——database 直接就在那,一個現成的全域變數,指向當前這個應用的 NSF。你連 getDatabase 都不必呼叫。
正因為「怎麼拿」不是問題,SSJS 的 Database 真正要想清楚的,是另一件 LS 和 Java 很少逼你面對的事:這段 server-side script 是用誰的權限在跑? 是開頁面的那個使用者?還是這張 XPage 的簽署者?答錯,輕則該讀的讀不到,重則讓一般使用者做了他 ACL 上根本沒權限的事。
這篇講三件事:database 全域是什麼、要開別的庫怎麼開、以及 session / sessionAsSigner / sessionAsSignerWithFullAccess 這組權限模型——什麼時候非換權限不可。
重點摘要
database是現成的全域,官方定義:「represents the HCL Domino database currently being used as a data source」——當前應用的資料源,你不用建立、也不用開。- 要開別的庫才呼叫
session.getDatabase(server, file);session.getCurrentDatabase()等同database,session.getDbDirectory()拿目錄。底層就是那套lotus.dominoAPI。 - 真正的重點是權限。
session用當前使用者的憑證;sessionAsSigner用這張 XPage 簽署者的憑證;sessionAsSignerWithFullAccess用簽署者憑證再加完整存取。 database全域跟著session走——用的是當前使用者的權限。使用者 ACL 讀不到的東西,透過database一樣讀不到。- 什麼時候要
sessionAsSigner:應用合法需要碰一個「使用者本人沒權限、但這個功能該做」的庫(中央設定庫、稽核 log、跨庫查表),就用sessionAsSigner.getDatabase(...)以簽署者身分開,而不是放寬那個庫的 ACL 給所有人。
database:現成的,指向當前應用
在 XPages 的 server-side script 裡,database 是一個全域變數,不用宣告、不用建立。官方 Global objects 頁的定義是:「represents the HCL Domino database currently being used as a data source」——它就是當前這個應用的資料庫,型別是 NotesDatabase。
這跟 LotusScript 的 session 全域、或 SSJS 的 session 全域是同一種待遇:框架在每個 request 幫你備好,你直接用。所以最常見的 SSJS 就是這樣起手:
var view:NotesView = database.getView("vwOrders");var doc:NotesDocument = database.getDocumentByUNID(unid);database 底下的方法——getView、getDocumentByUNID、createDocument、FTSearch——跟 LotusScript、Java 是同一套 lotus.domino API,名字只差大小寫慣例。(DQL 是例外:SSJS 的 database 沒有 createDominoQuery,NotesDominoQuery 只在 LotusScript 和 Java;XPages 要跑 DQL 得走 Java,見 DQL 上線實務。)
要開別的庫:走 session
database 只指向當前應用。要碰別的 NSF(跨庫查表、寫 log 到共用庫),就得自己開,入口在 session:
// 開指定伺服器上的某個庫var other:NotesDatabase = session.getDatabase("Mail01/ACME", "shared/config.nsf");
// 當前庫(等同 database 全域)var cur:NotesDatabase = session.getCurrentDatabase();
// 拿資料庫目錄var dir:NotesDbDirectory = session.getDbDirectory("Mail01/ACME");官方 NotesSession (JavaScript) 對 getDatabase 的說明是「Creates a NotesDatabase object that represents the database located at the server and file name you specify」,並且「opens the database, if possible」。注意最後那句——「if possible」。跟 Java 一樣,開不到不一定當場報錯,養成檢查 isOpen() 的習慣;Java 版那個「回了物件卻沒開成」的陷阱,在 Java Database 那篇講得更細,SSJS 走的是同一個後端。
真正的問題:這段 code 用誰的權限?
這才是 SSJS 跟 LS/Java 最不一樣的地方。LotusScript agent 跑在誰身上、通常你很清楚(簽署者或指定執行者);XPages 的 server-side script 預設跑在開頁面的那個使用者身上,而 database 全域、session 全域,用的都是他的憑證。
官方 Server-side scripting 把三種身分講得很清楚:
session——「assigns credentials based on the user」。用當前使用者的憑證,受這個應用的 ACL、以及伺服器 Domino Directory 安全頁設定限制。database全域就是走這個。sessionAsSigner——「assigns credentials based on the signer of the … XPages design element」。改用這張 XPage 的簽署者的憑證(同樣受 ACL 與安全設定限制,只是「人」換成簽署者)。sessionAsSignerWithFullAccess——簽署者憑證再加完整管理存取,「allows full administrative access to the application’s data」。但官方附帶一句硬條件:簽署者本人必須有這個權限,否則「the session is not created」——拿到的會是空的,不是偷渡的後門。
一句話:session(和 database)是使用者視角,sessionAsSigner 是簽署者視角。
什麼時候非用 sessionAsSigner 不可
情境很具體:你的 XPage 要寫一筆稽核 log 到一個共用的 audit.nsf,但一般使用者在那個庫的 ACL 只有 No Access——這是對的,稽核庫本來就不該讓人隨便進。如果你用 database 或 session 去開它,使用者權限不足,寫不進去。
這時不要去放寬 audit.nsf 的 ACL(那等於為了一個功能把整個庫對所有人打開),而是用簽署者的權限開:
var audit:NotesDatabase = sessionAsSigner.getDatabase("", "audit.nsf");if (audit != null && audit.isOpen()) { var log:NotesDocument = audit.createDocument(); log.replaceItemValue("Form", "AuditEntry"); log.replaceItemValue("User", session.getEffectiveUserName()); // 記的是「真正那個使用者」 log.replaceItemValue("Action", "ViewedRecord"); log.save();}重點在於權限的收束:只有這張簽署過的 XPage 能以簽署者身分寫 log,使用者自己拿不到那個權限。簽署者是誰?官方的規則是「XPages are signed with the ID of the current Domino Designer user upon saving the XPage design element」——你存檔那張 XPage 時,它就被你的 ID 簽了。所以部署前務必確認 XPage 是用一個有適當權限的 ID 簽的,不然 sessionAsSigner 拿到的權限會跟你以為的不一樣。
還有一道安全網值得知道:XPages 的 SSJS 直譯器對「受限操作」有把關——它會「Rejects embedded Java statements in JavaScript … if the XPages Signer is not granted permission to perform restricted operations」。也就是說,簽署者沒被授權做受限操作時,連在 SSJS 裡嵌 Java 去繞都會被擋。
recycle 呢?交給框架
Java standalone 要自己數 recycle()、自己收 handle(那套規則見 改寫成 Java 後記憶體爆掉)。SSJS 在 XPages 的 request 生命週期裡,database、session 這些是框架備好的 request-scope 全域,它們的生命週期由 XPages 執行環境管,你不需要、通常也不該去 recycle 它們。你自己 session.getDatabase(...) 開出來的額外物件,在一次 request 內用完即可;真正需要像 Java 那樣逐一手動回收的重迴圈場景,在 XPages 相對少見。少操一份心,是 SSJS 相對 Java 的一個實在好處。
同類別在其他語言
同一個 NotesDatabase,三種語言的「取得」與「權限」差很多:
- LotusScript:
session.GetDatabase(server, file)再db.Open,開不到回Nothing;權限通常就是 agent 的執行身分(簽署者或指定執行者),沒有sessionAsSigner這種「同一段 code 切換身分」的機制。 - Java:要先取得 Session、再
getDatabase,還要顧isOpen陷阱與recycle鏈——細節見 Java 開 Notes Database。 - SSJS 專屬的,正是這篇的重點:
database現成、而且有sessionAsSigner/sessionAsSignerWithFullAccess讓你在同一段 script 裡切換到簽署者權限。至於 SSJS 怎麼碰後端文件(document1vs 後端NotesDocument),見 XPages 裡其實有兩個 document。
參考來源
- Global objects and functions (JavaScript)(database / session / sessionAsSigner / sessionAsSignerWithFullAccess 等全域物件)— HCL Domino Designer(官方)
- Server-side scripting(session vs sessionAsSigner 的憑證與權限模型)— HCL Domino Designer(官方)
- NotesSession (JavaScript)(getDatabase / getCurrentDatabase / getDbDirectory)— HCL Domino Designer(官方)