Referrals

Referrals in the JNDI

A JNDI application uses the Context.REFERRAL ("java.naming.referral") environment property to indicate to the service providers how to handle referrals. The following table shows the values defined for this property. If this property has not been set, then the default is to ignore referrals.

Property Setting	Description
ignore	Ignore referrals
follow	Automatically follow any referrals
throw	Throw a ReferralException for each referral

Unlike aliases, which are always ignored for LDAP operations that update the directory, the Context.REFERRAL property is in effect for all operations. See the Creating and Updating Referrals section for a discussion of how to update referrals.

This property affects both "referral" error responses and continuation references.

Interaction with the Manage Referral Control

The Manage Referral control (RFC 3296) tells the LDAP server to return referral entries as ordinary entries (instead of returning "referral" error responses or continuation references). If you are using the LDAP v3 and have set Context.REFERRAL to "ignore", then the LDAP service provider will automatically send this control along with the request. If you are using the LDAP v2, then the control will not be sent because it is not applicable in that protocol. When you set Context.REFERRAL to any other value, the control will not be sent regardless of the protocol version. When updating referral entries, you should always use "ignore".

When the LDAP service provider receives a referral despite your having set Context.REFERRAL to "ignore", it will throw a PartialResultException to indicate that more results might be forthcoming if the referral is followed. In this case, the server does not support the Manage Referral control and is supporting referral updates in some other way.

When Referrals Are Processed

Continuation references can be mixed in with search results returned by an LDAP "search" operation. For example, when searching a directory, the server might return several search results, in addition to a few continuation references that show where to obtain further results. These results and references might be interleaved at the protocol level. When the Context.REFERRAL property is set to "follow", the LDAP service provider processes all the normal entries first, before following the continuation references. When this property is set to "throw", all of normal entries are returned in the enumeration first, before the ReferralException is thrown.

By contrast, a "referral" error response is processed immediately when Context.REFERRAL is set to "follow" or "throw".

Server Configuration for Examples

The examples in this trail communicate with a new server whose directory contains referrals to the original server set up for this tutorial. The original server is assumed to be running on port 389 of the local machine, and the new server is assumed to be running on port 489 of the local machine.

The following three referrals are set up from the new server (port 489) to the original server (port 389).

• The entry "ou=People, o=JNDITutorial" in the new server is a referral to the entry by the same name in the original server.
• The entry "ou=People, ou=All, o=JNDITutorial" in the new server is a referral to the "ou=People, o=JNDITutorial" entry in the original server.
• The entry "ou=NewHires, ou=All, o=JNDITutorial" is a referral to the "ou=NewHires, o=JNDITutorial" entry in the original server.

The initial context used in the examples in this lesson is initialized by using the following environment properties.

// Set up the environment for creating the initial context
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, 
    "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://localhost:489/o=JNDITutorial");

Unlike in the remaining examples in this tutorial, the port number is 489 instead of 389.

---

Before you go on: The examples in this lesson 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 these examples won't work as shown. The configuration file contains referrals that point to the original server that you've set up and augmented for this lesson (using tutorial.ldif and ldaptrail.ldif). 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 Preparations lesson for more information.

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.

Referrals