Manipulating LdapName (Distinguished Name)

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:

• CN=John Smith
• O=Isode Limited
• C=GB

The classes below represent the DN and RDN respectively.

• javax.naming.ldap.LdapName
• javax.naming.ldap.Rdn

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.

LdapName

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.

Accessing the name components of an LDAP 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().

Modifying an LDAP name

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

Comparing an LDAP name

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

Getting the String Representation

The method below gets you the string representation of an LDAP name formatted according to the syntax specified in RFC 2253:

toString()

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

LdapName as an Argument to Context Methods

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