Download the JDK
Search the Tutorials
Hide the TOC
Trail: Java Naming and Directory Interface(TM).
Lesson: New features in JDK 5.0 and JDK 6
New features in JDK 5.0 and JDK 6
Retrieving Distinguished Name
Standard LDAP Controls
Paged Results Control
Sort Control
Manage Referral Control
Manipulating LdapName (Distinguished Name)
Manipulating Relative Distringuished Name (RDN)
Setting Timeout for Ldap Operations
Home Page > Java Naming and Directory Interface(TM). > New features in JDK 5.0 and JDK 6
Manipulating Relative Distringuished Name (RDN)

> The class `javax.naming.ldap.Rdn` represents a Relative Distinguished name (RDN) as specified in RFC2253. An RDN represents a component of a DN as explained in the Manipulating LdapName lesson. An RDN is made up of type and value pair(s). Examples of RDNs are:

> - `OU=Sun`
> - `OU=Sales+CN=J.Smith`.
>   The above example shows a representation of a multi-valued RDN.
> The `Rdn` class provides methods to access name/value pair(s) of an RDN, obtain its string representation, retrieve an `Attributes` view, compare and determine equality of RDNs and methods to escape and unescape the value part of the RDN.

> The `Rdn` class is immutable.

> #### Constructing an Rdn

> An Rdn can be constructed with the specified name and value pair, if it's a single name/value paired RDN. For a multi-valued RDN, you should create an attribute set consisting of all the name/value pairs and use a constructor that takes `Attributes` as an argument. You can also create an Rdn from its string representation specified in RFC2253. Finally, you can clone an Rdn using its copy constructor. Here is an example that creates RDNs using different types of constructors.

>         <blackquote>
>     	Rdn rdn1 = new Rdn("ou= Juicy\\, Fruit");
>             System.out.println("rdn1:" + rdn1.toString());

>             Rdn rdn2 = new Rdn(rdn1);
>             System.out.println("rdn2:" + rdn2.toString());

>             Attributes attrs = new BasicAttributes();
>             attrs.put("ou", "Juicy, Fruit");
>             attrs.put("cn", "Mango");
>             Rdn rdn3 = new Rdn(attrs);
>             System.out.println("rdn3:" + rdn3.toString());

>             Rdn rdn4 = new Rdn("ou", "Juicy, Fruit");
>             System.out.println("rdn4:" + rdn4.toString());

> </blackquote>

> #### Accessing type/value pairs of an RDN

> The type/values of and RDN can be obtained using the methods below:

> `getType()`
> `getValue()`
> `toAttributes()`

> For a an RDN made up of single type/value pair, the `getType()` method returns the type and the `getValue()` method returns the value of the RDN. The method `toAttributes()` returns the attribute view of the type/value pairs. The example below prints the type/value pairs of RDNs.

>         <blackquote>
>     	Attributes attrs = new BasicAttributes();
>             attrs.put("o", "Yellow");
>             attrs.put("cn", "Mango");

>     	// create a binary value for the RDN
>             byte[] mangoJuice = new byte[6];
>             for (int i = 0; i < mangoJuice.length; i++) {
>                 mangoJuice[i] = (byte) i;
>             }
>             attrs.put("ou", mangoJuice);
>             Rdn rdn = new Rdn(attrs);

>             System.out.println();
>             System.out.println("size:" + rdn.size());
>             System.out.println("getType(): " + rdn.getType());
>             System.out.println("getValue(): " + rdn.getValue());

>             // test toAttributes
>             System.out.println();
>             System.out.println("toAttributes(): " + rdn.toAttributes());

> </blackquote>

> #### Getting the String Representation

> In order to get the string representation of an RDN formatted according to the syntax specified in RFC2253, you can use:

> `toString()`

> When you use the Rdn constructor that takes a `String` argument, you supply the string representation of an RDN, and get back an Rdn instance. To do the reverse, that is, to get the string representation of a Rdn instance, you use toString(). The result of toString() can be fed back to the Rdn constructor to produce an Rdn instance that is equal to the original Rdn instance.

> Here's an example:

>        <blackquote>
>     	Rdn rdn = new Rdn("cn=Juicy\\,Fruit");
>     	String str = rdn.toString();
>     	System.out.println(str);
>     	Rdn rdn2 = new Rdn(str);
>     	System.out.println(rdn.equals(rdn2));    // true

> </blackquote>

> #### Comparing RDNs

> The methods below enable comparison of RDNs:

> `equals(Object Rdn)`
> `compareTo(Object Rdn)`

> You can use compareTo() to sort a list of Rdn instances. equals() lets you determine whether two Rdns are syntactically equal. Two Rdns are equal if they both have the same (case-exact matched) type/value pairs. The order of components in a multi-valued RDNs is not significant.

> Here's an example:

>         <blackquote>
>     	Rdn one = new Rdn("ou=Sales+cn=Bob");
>             Rdn two = new Rdn("cn=Bob+ou=Sales");
>             Rdn three = new Rdn("ou=Sales+cn=Bob+c=US");
>             Rdn four = new Rdn("cn=lowercase");
>             Rdn five = new Rdn("cn=LowerCASE");
>             System.out.println(one.equals(two));    // true
>             System.out.println(two.equals(three));  // false
>             System.out.println(one.equals(three));  // false
>             System.out.println(four.equals(five));  // true

> </blackquote>

> #### Escaping and Unescaping of Special Characters

> One of the best use of Rdn class is when one has to deal with DNs consisting of special characters. It automatically takes care of escaping and unescaping the special characters. The characters such has '\' (backslash), ','(comma), + (plus) etc have a specific semantic according to RFC2253. You can find the list of all the special characters in RFC2253. When these characters are used as literals in a DN, they must be escaped with a '\' (blackslash).

> For example, consider an RDN:

>     	 cn=Juicy, Fruit

> The character , (comma) appearing between Juicy and Fruit is a special character that needs to be escaped by a '\' (blackslash). The resulting syntactically formatted RDN looks as below:

>     	cn=Juicy\, Fruit

> However, the '\' (backslash) character itself is a special character according to the Java Language String syntax, and it needs to escaped with a '\' (backslash) again. The Java Language String format and RFC2253 both use '\' (backslash) to escape the special characters. And therefore the Java formatted RDN String looks as below:

>     	cn=Juicy\\, Fruit

> Note that, the above mentioned formatting rules apply only to the value component of an Rdn. The `Rdn` class provides two `static` methods to handle automatic escaping and unescaping of the RDN values:

> `escapeValue()`
> `unescapeValue()`

> The example below shows how to get the string representation of a DN without having to deal with the syntax for handling special characters defined in RFC2253.

>     <blackquote>
>         // DN with ',' (comma)
>         String unformatted = "Juicy, Fruit";
>         String formatted = Rdn.escapeValue(unformatted);
>         LdapName dn = new LdapName("cn=" + formatted);
>         System.out.println("dn:" + dn);

>         unformatted = "true+false";
>         formatted = Rdn.escapeValue(unformatted);
>         dn = new LdapName("cn=" + formatted);
>         System.out.println("dn:" + dn);

>         // DN with a binary value as one one of its attribute value
>         byte[] bytes = new byte[] {1, 2, 3, 4};
>         formatted = Rdn.escapeValue(bytes);
>         System.out.println("Orig val: " + bytes +
>     		"	Escaped val: " + formatted);

> </blackquote> Similarly the using the static `unescapeValue()` method one can obtain the original string from the formatted value. Here is an example for retrieving the original value.

>     <blackquote>
>         // DN with ',' (comma)
>         String unformatted = "Juicy, Fruit";
>         String formatted = Rdn.escapeValue(unformatted);
>         System.out.println("Formatted:" + formatted);
>         Object original = Rdn.unescapeValue(formatted);
>         System.out.println("Original:" +  original);

>         // DN with a '+' (plus)
>         unformatted = "true+false";
>         formatted = Rdn.escapeValue(unformatted);
>         System.out.println("Formatted:" + formatted);
>         original = Rdn.unescapeValue(formatted);
>         System.out.println("Original:" +  original);

>         // DN with a binary value as one one of its attribute value
>         byte[] bytes = new byte[] {1, 2, 3, 4};
>         formatted = Rdn.escapeValue(bytes);
>         System.out.println("Formatted:" + formatted);
>         original = Rdn.unescapeValue(formatted);
>         System.out.println("Original:" +  original);
>     </blackquote>

Previous page: Manipulating LdapName (Distinguished Name)
Next page: Setting Timeout for Ldap Operations