Because of the distributed nature of directory services, a search sent to an LDAP server on eDirectory has a high probability of returning partial data, and referrals for the rest of the data.
When an LDAP server does not contain the requested data and a referral is necessary, the LDAPGroup object in eDirectory can be configured to handle them in one of four ways:
Configure eDirectory to return complete data and never referrals to the client (always chain).
Send referrals to the client only for eDirectory servers that do not support chaining.
Always send referrals to the client (never chain).
The client applications can be configured to have the API follow referrals, or the applications can perform their own handling of the referrals.
When you are using the LDAP SDK, note that referrals are handled differently for asynchronous and synchronous requests. Details are outlined in the following sections.
In eDirectory, the LDAP server can be configured to return complete data and not return referrals. This is done through the LDAP Group Object using ConsoleOne. For possible configurations in e-Directory, see the documentation for the LDAP Group Object.
The LDAP server in eDirectory can also be configured to return referrals to your application. This is done through the LDAP Group Object using ConsoleOne. For possible configurations in Novell e-Directory, see the documentation for the LDAP Group Object
To enable referral following, use LDAPConstraints.setReferralFollowing passing TRUE to enable referrals, FALSE (default) to disable referrals. See Using Constraints to Control Operations for information on setting constraints.
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, most likely the server has 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;
}
}
For more information on LDAPAuthHandler, see SearchUtil.java in the Sample Code.
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.
For more information on LDAP rebind, see SearchUtil.java in the Sample Code.
No mechanism for automatic referral handling is defined for asynchronous searches. To follow referrals you need to handle the referrals manually.
For some background information on how asynchronous operations handle responses from the server, read the sections on LDAP Messages and Asynchronous Searching.
A good example of performing asynchronous searches is contained in searchas.java in the sample code. This sample sets up a number of conditional statements to determine the message type and handle the message. When a referral is encountered, the URL is simply written out to the screen. If you wanted to follow referrals, you would replace this output with code to retrieve the URLs, and connect and bind to the server specified.
Your application can specify the maximum number of referral hops the LDAP classes will follow. For example, suppose you set the limit to 2. Your application performs a search, and the search refers you to the following:
The classes will follow the referral through Server C, but they will not continue to Server D because Server D exceeds the hop limit of 2. They return a result code of LDAP_REFERRAL_LIMIT_EXCEEDED.
To set a referral hop limit use LDAPConstraints.setHopLimit passing the maximum number of hops to follow in sequence during automatic referral handling. The default value is 10. See Using Constraints to Control Operations for information on setting constraints.
eDirectory 8.7 can return referrals for non-search operations. These referrals are followed using the same methods outlined in Enabling Referral Handling in the Application.