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.
// 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();
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.