| Miscellaneous

## 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 `ReferralException`s 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