The Java Tutorials have been written for JDK 8. Examples and practices described in this page don't take advantage of improvements introduced in later releases and might use technology no longer available.
See Java Language Changes for a summary of updated language features in Java SE 9 and subsequent releases.
See JDK Release Notes for information about new features, enhancements, and removed or deprecated options for all JDK releases.
The Distinguished Name (DN) is used by LDAP in its string representation. The string format used to represent a DN is specified in RFC 2253. The DN is made up of components called the Relative Distinguished Names (RDN). Below is an example of a DN:
"CN=John Smith, O=Isode Limited, C=GB"
It consist of the following RDNs:
The classes below represent the DN and RDN respectively.
The LdapName class implements the javax.naming.Name interface similar to the javax.naming.CompoundName and javax.naming.CompositeName classes.
LdapName and Rdn classes allow easy manipulation of DNs and RDNs. Using these APIs it's easy to construct an RDN by pairing up names and values. A DN can be constructed with a list of RDNs. Similarly the individual components of DN and RDN can be retrieved from their string representation.
An LdapName can be created with its string representation as defined in RFC 2253 or with a list of Rdns. When the former way is used, the specified string is parsed as per the rules defined in RFC2253. An InvalidNameException is thrown if the string is not a valid DN. Here's an example that uses the constructor to parse an LDAP name and print its components.
String name = "cn=Mango,ou=Fruits,o=Food"; try { LdapName dn = new LdapName(name); System.out.println(dn + " has " + dn.size() + " RDNs: "); for (int i = 0; i < dn.size(); i++) { System.out.println(dn.get(i)); } } catch (InvalidNameException e) { System.out.println("Cannot parse name: " + name); }
Running this example with an input of "cn=Mango,ou=Fruits,o=Food" produces the following results:
cn=Mango,ou=Fruits,o=Food has 3 RDNs: o=Food ou=Fruits cn=Mango
The LdapName class contains methods to access its components as RDNs and strings, to modify an LdapName, to compare two LdapNames for equality, and to get a string representation of the name.
Here are the methods that you can use to access the name components as RDNs and strings:
getRdn(int posn)
get(int posn)
getRdns()
getAll()
getPrefix(int posn)
getSuffix(int posn)
clone()
To retrieve the component at a particular position within an LdapName, you use getRdn() or get(). The previous constructor example shows an example of its use. getRdns() returns a list of all the RDNs and getAll() returns all of the components of an LdapName as an enumeration.
The right most RDN is at index 0, and the left most RDN is at index n-1. For example, the distinguished name: "cn=Mango, ou=Fruits, o=Food" is numbered in the following sequence ranging from 0 to 2: {o=Food, ou=Fruits, cn=Mango}
You can also get a LdapNames's suffix or prefix as a LdapName instance. Here's an
example
that gets the suffix and prefix of an LDAP name.
LdapName dn = new LdapName("cn=Mango, ou=Fruits, o=Food"); Name suffix = dn.getSuffix(1); // 1 <= index < cn.size() Name prefix = dn.getPrefix(1); // 0 <= index < 1
When you run this program, it generates the following output:
cn=Mango ou=Fruits o=Food
To make a copy of an LdapName, you use clone().
Following are the methods that you can use to modify an LDAP name:
add(Rdn rdn)
add(String comp)
add(int posn, String comp)
addAll(List suffixRdns)
addAll(Name suffix)
addAll(int posn, List suffixRdns)
addAll(int posn, Name suffix)
remove(int posn)
After creating an LdapName instance, you can add and remove components from it. Here's an
example
that appends an LdapName to an existing LdapName, adds components to the front and the end, and removes the second component.
LdapName dn = new LdapName("ou=Fruits,o=Food"); LdapName dn2 = new LdapName("ou=Summer"); System.out.println(dn.addAll(dn2)); // ou=Summer,ou=Fruits,o=Food System.out.println(dn.add(0, "o=Resources")); // ou=Summer,ou=Fruits,o=Food,o=Resources System.out.println(dn.add("cn=WaterMelon")); // cn=WaterMelon,ou=Summer,ou=Fruits,o=Food,o=Resources System.out.println(dn.remove(1)); // o=Food System.out.println(dn); // cn=WaterMelon,ou=Summer,ou=Fruits,o=Resources
Following are the methods that you can use to compare two LDAP names:
compareTo(Object name)
equals(Object name)
endsWith(List)
endWith(Name name)
startsWith(List rdns)
startsWith(Name name)
isEmpty()
You can use compareTo() to sort a list of LdapName instances. The equals() method lets you determine whether two LdapNames are syntactically equal. Two LdapNames are equal if they both have the same (case-exact matched) components in the same order.
With startsWith() and endsWith(), you can learn whether an LdapName starts or ends with another LdapName; that is, whether an LdapName is a suffix or prefix of another LdapName.
The convenience method isEmpty() enables you to determine whether an LdapName has zero components. You can also use the expression size() == 0 to perform the same check.
Here is an example,
CompareLdapNames
, that uses some of these comparison methods.
LdapName one = new LdapName("cn=Vincent Ryan, ou=People, o=JNDITutorial"); LdapName two = new LdapName("cn=Vincent Ryan"); LdapName three = new LdapName("o=JNDITutorial"); LdapName four = new LdapName(""); System.out.println(one.equals(two)); // false System.out.println(one.startsWith(three)); // true System.out.println(one.endsWith(two)); // true System.out.println(one.startsWith(four)); // true System.out.println(one.endsWith(four)); // true System.out.println(one.endsWith(three)); // false System.out.println(one.isEmpty()); // false System.out.println(four.isEmpty()); // true System.out.println(four.size() == 0); // true
The method below gets you the string representation of an LDAP name formatted according to the syntax specified in RFC 2253:
When you use the LdapName constructor, you supply the string representation of an LDAP name and get back an LdapName instance. To do the reverse, that is, to get the string representation of an LdapName instance, you use toString(). The result of toString() can be fed back to the constructor to produce a LdapName instance that is equal to the original LdapName instance. Here's an example,
LdapNametoString
:
LdapName dn = new LdapName(name); String str = dn.toString(); System.out.println(str); LdapName dn2 = new LdapName(str); System.out.println(dn.equals(dn2)); // true
The Context method require either a composite or a compound name passed as argument to its methods. Hence an LdapName can be directly passed to a context method as shown in
LookupLdapName
:
// Create the initial context Context ctx = new InitialContext(env); // An LDAP name LdapName dn = new LdapName("ou=People,o=JNDITutorial"); // Perform the lookup using the dn Object obj = ctx.lookup(dn);
Similarly, when the Context methods return results from list(), listBindings(), or search() operations, the DN can be retrieved by calling
getNameInNamespace(). The LdapName can be constructed directly from the DN as shown in the example,
RetrievingLdapName
:
while (answer.hasMore()) { SearchResult sr = (SearchResult) answer.next(); String name = sr.getNameInNamespace(); System.out.println(name); LdapName dn = new LdapName(name); // do something with the dn