Changing the ACL in Java: Without save(), Your Changes Vanish When the Database Closes
In Java you change a database’s ACL programmatically: bump someone to Editor, enable a role for them, add a new entry. Every API call returns success, nothing throws. Then you reopen the database and — nothing changed.
The reason is that ACL edits don’t persist automatically. You’re editing the in-memory ACL object, and to land it in the database you must explicitly call save(). The ACL class page is blunt: “If you don’t call save before closing a database, the changes you’ve made to its ACL are lost.” — no save, and the changes are gone when the database closes, with no warning.
This covers getting the ACL, changing an entry, the two-layer structure of roles, the big save trap, and a mixing bug that produces inconsistent results.
Getting the ACL and changing an entry
The ACL comes from the database — the docs: “To get it, use getACL in Database.” Then getEntry(name) finds one, or createACLEntry(name, level) adds one:
ACL acl = db.getACL();ACLEntry e = acl.getEntry("CN=John B Goode/O=Acme");if (e != null) { e.setLevel(ACLEntry.LEVEL_EDITOR); // bump to Editor}acl.createACLEntry("CN=New Hire/O=Acme", ACLEntry.LEVEL_AUTHOR); // add oneacl.save(); // the point: without this line, all the above is lostLevels use ACLEntry constants: LEVEL_NOACCESS / LEVEL_DEPOSITOR / LEVEL_READER / LEVEL_AUTHOR / LEVEL_EDITOR / LEVEL_DESIGNER / LEVEL_MANAGER — the seven levels. An entry stands for a person, a group, or a server (the docs: “An entry may be for a person, a group, or a server.”).
Roles are two layers: define, then enable
Notes roles (the [Finance] kind in an ACL) trip people up because they’re two layers:
- Define the role on the ACL:
acl.addRole("Finance")— this only makes the database “have” the role. - Enable it on an entry:
entry.enableRole("Finance")— this actually grants a person/group the role. Check withisRoleEnabled("Finance"), remove withdisableRole.
So “give someone the Finance role” is really: make sure the ACL has the role (addRole), then enableRole on that entry. And deleteRole is sweeping — the docs: “Deletes a role and removes it from any entries that have it.” — deleting a role pulls it from every entry that had it, so think before you do.
The big trap: save, and don’t mix with grantAccess
The save trap was the opening, and two extensions deserve stressing:
First, always acl.save() after changing. Not just adding entries — changing a level, enableRole, addRole: any change needs save to land. The ACLEntry page repeats it: “After modifying an entry, call save on the ACL, or the changes are lost when the database closes.”
Second, don’t mix db.grantAccess(...) with an ACL object you’re holding. Database has the grantAccess / queryAccess / revokeAccess shortcuts that change access without an ACL object; but the docs warn that calling those while an ACL object is in use “may produce inconsistent results.” Either go all-in on the ACL object + save, or use the shortcuts — don’t cross the two.
Consistency across replicas
An often-overlooked property: UniformAccess (IsUniformAccess), which the docs describe as “whether a consistent access control list is enforced across all replicas of a database.” Turn it on and the ACL is enforced identically across all replicas — important in a multi-server setup, or permissions can drift between replicas. There’s also InternetLevel, “The maximum Internet access level for this database,” which caps web access.
What about LotusScript and SSJS?
The same ACL / ACLEntry:
- LotusScript:
NotesACL/NotesACLEntry, withGetEntry/CreateACLEntry/EnableRole/Save— and the same need toSave; the full usage is in the NotesACLEntry piece. - SSJS / XPages:
NotesACL/NotesACLEntry, same API and same save rule; comes up building an admin UI in XPages. - The Java-specific part isn’t the API (the methods are shared) — it’s that ACL automation is a natural fit to wrap as a Java deployment tool (set permissions at database creation, batch-add roles), but strong typing won’t remind you that you forgot save — it compiles, it runs, nothing throws, and the permissions don’t budge.
Sources
- ACL class (Java) (getACL, createACLEntry/getEntry, addRole, save, UniformAccess) — HCL Domino 14.5 Designer Help (official)
- ACLEntry class (Java) (Level, enableRole/isRoleEnabled, UserType, Name) — HCL Domino 14.5 Designer Help (official)
- Database class (Java) (getACL plus the grantAccess/queryAccess shortcuts) — HCL Domino 14.5 Designer Help (official)