When performing synchronous operations, referrals can be followed automatically with or without authentication, or they can be handled manually.
When referral handling is disabled, an LdapReferralException is thrown if the search result is a referral or a continuation reference.
You can use LdapReferralExceptions to follow referrals or continuation references by retrieving the URLs from the LdapReferralException and manually following them.
If you receive some data and an LdapReferralException is thrown, this is not an error. The server has probably returned partial data and a continuation reference for the remaining data. A separate LdapReferralException is thrown for each continuation reference received during a search.
If referral following is enabled, referrals are followed by default using an anonymous bind to the next server. If your application does not require authentication, this default behavior is ideal.
If the server encounters a problem following a referral, an LdapReferralException is thrown. This exception provides information on the URLs that could not be followed, and it may contain a nested exception or throwable class with more information on what caused the exception. Be aware that if you receive some data and an LdapReferralException when using automatic referral handling, you most likely have incomplete results. This does not indicate the end of the data in your enumeration.
If your application requires more than anonymous authentication, you will need to implement a referral handler. The LDAP SDK provides interfaces your application can implement to provide credentials when following referrals. These interfaces are LdapAuthHandler and LdapBindHandler.
LdapAuthHandler: This interface is the simplest to use. Your application creates an object that implements this interface and the SDK uses this class under-the-covers to authenticate.
LdapBindHandler: Used to do explicit bind processing on a referral. This interface provides greater control over the bind process when following a referral but requires more work.
To use LdapAuthHandler you must create a class that extends the LdapAuthHandler interface. The following is an example of an LdapAuthHandler class:
class AuthImpl implements LdapAuthHandler
{
private LdapAuthHandler auth;
AuthImpl( String dn, byte[] pw )
{
auth = new LdapAuthProvider( dn, pw);
return;
}
public LdapAuthProvider getAuthProvider(String host, int port)
{
return auth;
}
}
To use LdapBindHandler, you must create a class that extends the LdapBindHandler interface. The LdapBindHandler class provides the most flexibility, but you must perform your own bind operation. If the bind is successful, the referral will then be followed automatically.