Comparing Notes User Names in Java: Same Person, Not Equal? Normalize First

Comparing Notes User Names in Java: Same Person, Not Equal? Normalize First

Nov 16, 2026 531 words

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 user
Name b = session.createName(doc.getItemValueString("Approver")); // from the document
boolean 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, with Canonical / Abbreviated / Common and the name-part properties; the full account of name formats is in the NotesName formats piece.
  • SSJS / XPages: NotesName, same session.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 createName and normalize before comparing.

Sources

← Back to all posts