Adding Referral Support

Prerequisite: You should be familiar with referrals before reading this section. Referrals are covered in the Referrals lesson.

A service provider typically supports referrals only when the underlying naming/directory service provides such a feature. Only the LDAP and LDAP-like services support referrals.
How referrals are supported is an integral part of the service provider implementation. It permeates every aspect of how responses from the underlying LDAP service are processed. This section touches on only a few topics related to implementing referrals.
Referral Exception
A referral is represented by the abstract class ReferralException or its subclass LdapReferralException. The latter should be used by service providers that support LDAP controls.
Providing a concrete implementation for this class is key to providing referral support. The implementation's main task is to return a referral context for getReferralContext(). This method has a couple of overloads, including one declared in LdapReferralException. It is responsible for generating a Context instance that represents the location identified by the referral. A referral is defined as a URL in the LDAP. One way to create the referral context is to use the JNDI's support for URLs, for example by creating a Reference using the URL and then using NamingManager.getObjectInstance() to get the context.
Once the user program has a referral context, it is supposed to invoke on the context the original method that caused the ReferralException to be thrown by using the original arguments. Some of the original arguments might be affected by the referral's contents, including the name, search scope, search filter, and returning attributes. (See draft-ietf-ldapext-namedref-00.txt for details.) Your implementation of the referral context is responsible for modifying and/or replacing the supplied arguments with the ones from the referral. Here is an example of how bind() might be implemented in the referral context.
public void bind(Name name, Object obj) throws NamingException {
    // This referral has been skipped; throw a ReferralException
    if (skipThisReferral) {
	throw new ReferralExceptionImpl(untriedReferrals);
    }

    // Override the name from the referral URL if appropriate
    Name nm = (urlName == null ? name : urlName);

    // Invoke the method on the real referral context
    refCtx.bind(nm, obj);
}
Skipping Referrals
A single LDAP referral entry might contain several alternate but equivalent referral URLs. A ReferralException actually represents a single referral URL. As a result, the user program can choose from the alternates by using skipReferral(). The implementation of a ReferralException must take this into account and generate possibly multiple ReferralExceptions from a single LDAP referral entry. After the user program calls skipReferral(), it must then call getReferralContext() to get to a valid context. That context's sole purpose is to provide a context whose methods simply throw a ReferralException for the next referral URL in the list of alternates.
Note that if the user program successfully follows one alternate, then all other untried alternates should be discarded.
Referral Modes
A JNDI program determines how it wants to handle referrals by using the Context.REFERRAL ("java.naming.referral") environment property. In this way, the user program can specify whether it wants referrals to be followed automatically, followed manually, or ignored. As a service provider developer, you must handle all three cases.
When referrals are followed automatically, you should put in a mechanism to limit the number of referrals followed so as to prevent referrals from being followed indefinitely due to misconfigured servers. This can be done by, for example, maintaining a count in the referral exception and referral context and then updating them as each referral exception is processed.
When referrals are followed manually, you must do some bookkeeping to track which is the "current" referral, as explained in the previous section.
LDAP referrals currently are specified by an Internet-draft, draft-ietf-ldapext-namedref-00.txt. Not all servers support this Internet-draft. Your LDAP service provider must decide how to support referrals. If it uses this Internet-draft, then it might not be fully interoperable with servers that do not. This might cause the servers always to return referrals in LDAP responses regardless of what your provider does. One way to handle this mismatch is for your provider to throw a PartialResultException to indicate that there might be more results than those returned.

Miscellaneous