Java 改 ACL:不呼叫 save(),關庫後全部白改
你在 Java 用程式改一個資料庫的 ACL:把某個人升到 Editor、幫他開一個 role、再加一條新 entry。每一步 API 都回成功、沒丟例外。結果你重開資料庫一看——什麼都沒變。
原因是 ACL 的修改不會自動存。你改的是記憶體裡那個 ACL 物件,要讓它落到資料庫,得明確呼叫 save()。ACL class 頁講得很直白:「If you don’t call save before closing a database, the changes you’ve made to its ACL are lost.」——沒 save 就關庫,改動遺失,而且沒有任何警告。
這篇講怎麼拿 ACL、改一條 entry、roles 的兩層結構、那個最大的 save 坑,以及一個混用造成不一致的雷。
拿 ACL 與改一條 entry
ACL 從 database 拿,官方「To get it, use getACL in Database.」。拿到之後用 getEntry(name) 找某一條、或 createACLEntry(name, level) 加一條:
ACL acl = db.getACL();ACLEntry e = acl.getEntry("CN=John B Goode/O=Acme");if (e != null) { e.setLevel(ACLEntry.LEVEL_EDITOR); // 升到 Editor}acl.createACLEntry("CN=New Hire/O=Acme", ACLEntry.LEVEL_AUTHOR); // 加一條acl.save(); // 關鍵:沒這行前面全白做level 用 ACLEntry 的常數:LEVEL_NOACCESS / LEVEL_DEPOSITOR / LEVEL_READER / LEVEL_AUTHOR / LEVEL_EDITOR / LEVEL_DESIGNER / LEVEL_MANAGER 這七級。一條 entry 代表一個人、一個群組、或一台 server(官方「An entry may be for a person, a group, or a server.」)。
roles 是兩層:先定義,再授予
Notes 的 role(ACL 裡的 [Finance] 那種)很多人搞混,因為它是兩層的:
- 在 ACL 定義這個 role:
acl.addRole("Finance")——這只是讓這個資料庫「有」這個角色。 - 在某一條 entry 授予:
entry.enableRole("Finance")——這才是真的給某個人/群組這個角色。查用isRoleEnabled("Finance")、拿掉用disableRole。
所以「幫某人開 Finance 角色」其實是:確定 ACL 有這個 role(addRole),再對那條 entry enableRole。而 deleteRole 很乾脆,官方「Deletes a role and removes it from any entries that have it.」——刪一個 role 會從所有擁有它的 entry 一併移除,動它前先想清楚。
最大的坑:save,以及別跟 grantAccess 混用
save 的坑前面講了,這裡強調兩個延伸:
第一,改完一定 acl.save()。不只是加 entry,改 level、enableRole、addRole——任何改動都要 save 才落地。ACLEntry 頁也再說一次:「After modifying an entry, call save on the ACL, or the changes are lost when the database closes.」
第二,別把 db.grantAccess(...) 跟手上的 ACL 物件混用。Database 有 grantAccess / queryAccess / revokeAccess 這組捷徑,不經 ACL 物件就能改權限;但官方警告,當你已經有一個 ACL 物件在用時再去呼叫這些,「may produce inconsistent results」。要嘛全程用 ACL 物件 + save,要嘛用捷徑,別兩套交叉著改。
跨 replica 的一致性
一個常被忽略的屬性:UniformAccess(IsUniformAccess),官方「whether a consistent access control list is enforced across all replicas of a database.」。開了它,ACL 在所有 replica 強制一致——這在多台 server 的環境很重要,否則不同 replica 的權限可能漂掉。還有 InternetLevel 管「The maximum Internet access level for this database.」,網頁存取的權限上限由它定。
同類別在其他語言
同一組 ACL / ACLEntry:
- LotusScript:
NotesACL/NotesACLEntry,GetEntry/CreateACLEntry/EnableRole/Save都在,一樣要Save;完整用法見 NotesACLEntry 那篇。 - SSJS / XPages:
NotesACL/NotesACLEntry,同樣的 API 與 save 規則;XPages 裡做管理介面時會用到。 - Java 專屬的不是 API(方法共用),而是:ACL 自動化很適合包成 Java 的佈署工具(建庫時一次設好權限、批次加角色),但強型別不會提醒你「你忘了 save」——編譯過、跑過、沒報錯,權限卻一點沒變。
參考來源
- ACL class (Java)(getACL、createACLEntry/getEntry、addRole、save、UniformAccess)— HCL Domino 14.5 Designer Help(官方)
- ACLEntry class (Java)(Level、enableRole/isRoleEnabled、UserType、Name)— HCL Domino 14.5 Designer Help(官方)
- Database class (Java)(getACL 以及 grantAccess/queryAccess 捷徑)— HCL Domino 14.5 Designer Help(官方)