Comparing Notes User Names in Java: Same Person, Not Equal? Normalize First
In Java you compare two Notes user names: the logged-in user from session.getUserName(), and the approver field stored in a document. Same person, yet equals returns false.
The reason is that the same person’s name takes different forms in different places. One side might be the canonical CN=John B Goode/O=Acme/C=US, the other the abbreviated John B Goode/Acme/US, or just the common John B Goode. Those three strings look nothing alike, so comparing them directly fails — even though they’re the same person.
What handles this is the Name class, which the docs define as “Represents a user or server name.” The fix: use it to normalize both sides to the same form before comparing. This covers the three forms, comparing correctly, pulling a name apart, and parsing internet addresses.
The three forms
Wrap a name string in a Name object with session.createName(...) and you can ask for its various forms. The official Representing a name using Java lists three:
- Canonical (
getCanonical) — “A hierarchical name in canonical form.” Each component carries a keyword and equals sign:CN=John B Goode/OU=Sales/O=Acme/C=US. This is the fullest, least ambiguous form. - Abbreviated (
getAbbreviated) — “A hierarchical name in abbreviated form.” Keywords dropped, identified by position:John B Goode/Sales/Acme/US. - Common (
getCommon) — only the CN= part:John B Goode.
One wrinkle about abbreviating: the class page states “The class won’t abbreviate a name when the result would be ambiguous.” — if abbreviating would be ambiguous, it doesn’t, and returns canonical instead. For example CN=John B Goode/OU=East abbreviated to John B Goode/East would read East as the organization (O=), so it leaves it canonical.
Comparing correctly: normalize both sides
The fix is simple — convert both sides to the same form and compare that, usually canonical (the fullest):
Name a = session.createName(session.getUserName()); // the logged-in userName b = session.createName(doc.getItemValueString("Approver")); // from the documentboolean same = a.getCanonical().equalsIgnoreCase(b.getCanonical());a.recycle(); b.recycle();Both sides getCanonical(), and whatever the original form — abbreviated or common — they compare after normalizing. If you only care about the common name (for display), compare getCommon() on both — but know that common names can collide (two different orgs each with a John B Goode), so use canonical whenever access decisions are involved.
Pulling a name apart
Name can also break a hierarchical name into components, which is useful for “is this person in a given org unit.” Each component is a read-only getter: getOrganization (O=), getOrgUnit1 through getOrgUnit4 (OU=, up to four), getCountry (C=), getCommon (CN=), and so on.
To decide whether someone is in Sales, don’t use contains("Sales") — that also catches people whose name happens to include “Sales.” Compare the specific component with getOrgUnit1():
Name n = session.createName(userName);boolean inSales = "Sales".equalsIgnoreCase(n.getOrgUnit1());It also parses internet addresses
A little-known ability: if what you pass in conforms to RFC 821/822, Name interprets it as an internet address. The class page says “A name that conforms to RFC 821 or RFC 822 is interpreted as an Internet address.” Pass "John B Goode" <jbg@us.acme.com> and you can pull it apart with getAddr821 (the bare address), getAddr822LocalPart (before the @), and getAddr822Phrase (the display name in quotes) — no email regex of your own.
What about LotusScript and SSJS?
The same Name:
- LotusScript:
NotesName, withCanonical/Abbreviated/Commonand the name-part properties; the full account of name formats is in the NotesName formats piece. - SSJS / XPages:
NotesName, samesession.createName; comes up when deciding which OU the logged-in user is in, or showing the common name in XPages. - The Java-specific part isn’t the API (the methods are shared) — it’s that this “comparison fails” bug shows up most in Java agents and managed beans: strong typing won’t remind you that two strings are the same person in different forms, so you have to remember to
createNameand normalize before comparing.
Sources
- Name class (Java) (Canonical/Abbreviated/Common, name-part getters, RFC 821/822, createName) — HCL Domino 14.5 Designer Help (official)
- Representing a name using Java (the createName and three-forms how-to) — HCL Domino 14.5 Designer Help (official)
- Session class (Java) (createName builds a Name object) — HCL Domino 14.5 Designer Help (official)