1.5 Exception Handling

There are two types of exceptions in the Java LDAP SDK:

Most errors that occur throw an LDAPException. An LDAPException is a general exception including an error message and an LDAP result code. An LDAPException can result from physical problems (such as network errors) as well as problems with LDAP operations (for example, if the LDAP add operation fails because of a duplicate entry).

An LDAPException can also contain a nested exception or a Throwable class with more information about the cause of the error. To retrieve the nested exception or Throwable class, use LDAPException.getCause, which returns the lower-level exception which caused the failure. For example, an IOException with additional information may be returned on a CONNECT_ERROR failure. The various result codes returned from an LDAP request are defined as constants in the LDAPException class.

Depending whether you are using asynchronous or synchronous functions, exceptions are handled differently. These differences are outlined in the following sections.

1.5.1 Synchronous Methods

Synchronous methods throw an LDAPException on result codes other than SUCCESS (0). This eliminates the need to check for errors, therefore a standard try/catch statement can be used to handle exceptions.

The following is an example using the LDAPException.toString method to print error information:

 try {
       [Attempt an LDAP operation]
 }
 catch(LDAPException e) {
    System.out.println("Error:" + e.toString());
 }

To facilitate user feedback during synchronous searches, intermediate search results can be obtained before the entire search operation is completed by specifying the number of entries to return at a time. By calling the LDAPSearchConstraints.setBatchSize method, you can set the number of results to obtain before returning information back to the application. The default setting is 1, allowing results to be obtained as they are received by the server. By setting the batch size to 0, you ensure all the results have been received from the server and stored in local memory before returning to the application.

 LDAPConnection ld = new LDAPConnection();
 LDAPSearchConstraints cons = ld.getSearchConstraints();
 cons.setBatchSize(0);
 ld.setConstraints(cons);

This allows you to enumerate through the results without ever blocking.

1.5.2 Asynchronous Methods

For the asynchronous methods, exceptions are thrown only for local or non-server errors, such as connection errors or parameter errors. For server errors, LDAP result messages are returned as LDAPResponse objects which must be checked by the client for errors using the LDAPResponse.getResultCode method.

The following is an example of error handling with a failed asynchronous search.

NOTE:Before you check the response for an error message you need to determine which type of LDAP message has been returned. See Asynchronous Searching for additional information.

 //previously determined that the message is an LDAPResponse
 if (message instanceof LDAPResponse)
 {
   LDAPResponse response = (LDAPResponse) message;
   int status = response.getResultCode();
   if (status!= LDAPException.SUCCESS)
   {
     System.out.println("Asynchronous search failed.");
     throw new LDAPException(response.getErrorMessage(),
                              status,
                              response.getMatchedDN());
   }
 }

1.5.3 Referral Exceptions

LDAPReferralExceptions are encountered when performing synchronous LDAP operations. They are derived from LDAPException and contain a list of URL strings corresponding to referrals received on an LDAP operation.

LDAPReferralExceptions are thrown when referral handling is turned off in your application, or if the API attempted to follow a referral and the referral could not be followed. For example, if you have enabled automatic referral handling and the API throws an LDAPReferralException, it means the referral could not be followed and you most likely have incomplete results. The LDAPReferral exception will contain a list of LDAP URL strings the API attempted to follow.

The following is an example of retrieving LDAP URLs from an LDAPReferralException:

 try {
   [perform an LDAP search operation here]
 }
 catch(LDAPReferralException e) {
   LDAPUrl urls[] = e.getURLs();
   System.out.println("Referral Exception");
   for(i=0;i < urls.length;i++)
     System.out.println(urls[i];
 }

For more information on LDAPReferralExceptions read the section on Section 1.6, Referral Handling in LDAP v3.