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
Manage Referral Control

> The Manage Referral control (RFC3296) enables manipulation of the referral and other special objects as normal objects when performing an LDAP operation. In other words, Manage Referral control tells the LDAP server to return referral entries as ordinary entries instead of returning "referral" error responses or continuation references. The new class in JDK 5.0 below enables you to send Manage Referral Control along with an LDAP request:

> `javax.naming.ldap.ManageReferralControl`

> The Sun LDAP service provider will send this control automatically along with any request. You can also explicitly enable it setting Context.REFERRAL environment property to "ignore". For more information on Referral handling check the Referrals in the JNDI section of the JNDI Tutorial.

> Here is an example that sends Manage Referral control along with an LDAP request. <blackquote>

>     	   // Create initial context
>     	    LdapContext ctx = (LdapContext) new InitialDirContext(env);
>     	    ctx.setRequestControl(new Control[] new ManageReferralControl());

>     	    // Set controls for performing subtree search
>     	    SearchControls ctls = new SearchControls();
>     	    ctls.setSearchScope(SearchControls.SUBTREE_SCOPE);

>     	    // Perform search
>     	    NamingEnumeration answer = ctx.search("", "(objectclass=*)", ctls);

>     	    // Print the answer
>     	    while (answer.hasMore()) {
>     		System.out.println(">>>" + ((SearchResult)answer.next()).getName());
>     	    }

>     	    // Close the context when we're done
>     	    ctx.close();

> </blackquote> The complete example can be found here.

> Note 1: The above example will require you to set up a second server using the configuration file refserver.ldif. The server must support LDAP v3 and RFC 3296. If the server does not support referrals in this way, then the example won't work as shown. The configuration file contains referrals that point to the original server that you've set up. It assumes that the original server is on port 389 on the local machine. If you have set up the server on another machine or port, then you need to edit the "ref" entries in the refserver.ldif file and replace "localhost:389" with the appropriate setting. The second server is to be set up on port 489 on the local machine. If you set up the second server on another machine or port, then you need to adjust the setting of the Context.PROVIDER_URL environment property for the initial context accordingly.

> Setting up a directory server is typically performed by the directory or system administrator. See the Software Setup lesson for more information.

> Note 2: Windows Active Directory: Because Active Directory does not support the Manage Referral control, none of the examples in this lesson will work against Active Directory.

Previous page: Sort Control
Next page: Manipulating LdapName (Distinguished Name)