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 values are defined for this property:

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

If this property has not been set, the default is to ignore referrals.

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 Update 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 (draft-ietf-ldapext-namedref-00.txt) 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", the LDAP service provider automatically sends this control along with the request. If you are using the LDAP v2, the control is not sent because it is not applicable in that protocol. When you set Context.REFERRAL to any other value, the control is not sent regardless of the version of the protocol. So, if you are updating referral entries, you should always use "ignore".

When the LDAP service provider receives a referral despite you having set Context.REFERRAL to "ignore", it will throw a PartialResultException to indicate that there might be more results 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

It is possible for continuation references to 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 the Context.REFERRAL property is set to "throw", all 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, while the new server is assumed to be running on port 489 of the local machine.

There are three referrals 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 using the following environment properties:

// Set up environment for creating 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 rest of the 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 draft-ietf-ldapext-namedref-00.txt. If the server does not support referrals in this way, 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.

Referrals