IBM JNDI LDAP Provider Programming Guide

Referrals and Search References

LDAP servers may return either referrals or search references. A referral can be returned on any operation and indicates that the server does not hold the target entry of the request. A search reference is only returned on a search operation and indicates that the server was able to locate the entry referred to by the baseObject but was unable to search all the entries in the scope at and under the baseObject. A server may return one or more search references.

A context may be configured to handle referrals and search references in one of three ways:

1. It can be set to automatically follow the reference and perform the operation at the referred to server. This toolkit automatically recognizes and avoids referral loops, this is, situations where a referral points back to one already chased earlier in the chain.
2. It can be set to throw a ReferralException when either a referral or search reference is received. This is useful if the automated handling is somehow deficient, for example, each server requires a different binding.
3. It can be set to ignore the reference and continue as if nothing happened. In the case of a search reference this would mean that only entries found at the originating server are returned.

The following environment properties are defined by this toolkit to handle referrals and search references:

• java.naming.referral (Context.REFERRAL): Set to either "follow", "throw" or "ignore". If not set the default is to automatically follow referrals.
• java.naming.ldap.referral.limit: Defines the number of referral hops the class library will make when chasing referrals. If not specified the default is "10".
• java.naming.ldap.referral.bind: If set to "true" the classes, when automatically following referrals, will bind to any referred to server using exactly the same SASL mechanism and credentials as with the originating context. If set to "false" the classes will not bind (anonymous access). The default behavior is to bind.

The following rules apply when chasing referrals or search references:

1. If the reference contains a port then it is used. Otherwise, the port from the primary connection is used.
2. The type of security connection from the primary connection is maintained. That is, if the primary connection was over SSL then all chased referrals will also be over SSL.

Note that a context may still throw a ReferralException even when set to "follow". This can occur if the referral hop limit is exceeded or if the context cannot connect or bind to any of the referred to servers.

The follow example catches and displays a referral and/or search references on a search request. For more information on handling referral exceptions see ReferralException in the JNDI documentation.

ctx.addToEnvironment(ctx.REFERRAL, "throw");
try {
    NamingEnumeration results = ctx.search(url);
    while (true) {
        try {
            if (!results.hasMore())
                break;
            SearchResult si =(SearchResult) results.next();
            System.out.println(si.getName());
        } catch (ReferralException re) {
            System.out.println("Reference caught");
            do {
                System.out.println(re.getReferralInfo());
            } while (re.skipReferral());
        }
    }
} catch (ReferralException re) {
    System.out.println("Referral caught");
    do {
        System.out.println(re.getReferralInfo());
    } while (re.skipReferral());
}

Note
If you get an error message javax.naming.PartialResultException: Unprocessed Continuation Reference(s), try adding
follow to the LDAPCredentialsProvider section.