Previous | Next | Trail Map | Tips for LDAP Users | Referrals

Referrals in the JNDI

A JNDI application uses the Context.REFERRAL(in the API reference documentation) (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(in the API reference documentation) 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 and continuation references.

Interaction with the Manage Referral Control

The manage referral control (draft-ietf-ldapext-referral-00.txt) tells the LDAP server to return referral entries as ordinary entries (instead of returning referral error responses or continuation references). When you set Context.REFERRAL to "ignore", Sun's LDAP service provider automatically sends this control along with the request if it is using the LDAP v3. If the LDAP v2 is being used, 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. So, if you are updating referral entries, you should always use "ignore".

The "manage referral" control is a critical control, which means that the request would fail if the server does not support it. Therefore, if the LDAP v3 server does not support this control, you need to use either "throw" or "follow" for Context.Referral.


Note: In the LDAP 1.0.1 version of Sun's LDAP provider, setting the Control.REFERRAL property to "ignore" does not cause the "manage referral" control to be sent. You must separately set the "manage referral" control by setting the java.naming.ldap.control.manageReferral property to "true". If you set this property to "true", the Context.REFERRAL environment property becomes irrelevant because the LDAP provider would not have any referrals to deal with. Therefore, it does not make sense to set the java.naming.ldap.control.manageReferral property when the Context.REFERRAL property is set to "follow" or "throw".

This way of setting the "manage referral" control is deprecated. Your application should only be dealing with the Context.REFERRAL property.


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 as to 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.

Referral Picture

There are three referrals set up from the new server (port 489) to the original server (port 389):

  1. The entry "ou=People, o=JNDITutorial" in the new server is a referral to the entry by the same name in the original server.
  2. 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.
  3. 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 are 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 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. 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 (in the Basics trail) lesson for more information.


Previous | Next | Trail Map | Tips for LDAP Users | Referrals