• Home
• com.novell.ldap
• jldap
• 2009-10-07
• source code
• LDAPException.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.novell.ldap.LDAPException Maven / Gradle / Ivy

/* **************************************************************************
 * $OpenLDAP$
 *
 * Copyright (C) 1999 - 2002 Novell, Inc. All Rights Reserved.
 *
 * THIS WORK IS SUBJECT TO U.S. AND INTERNATIONAL COPYRIGHT LAWS AND
 * TREATIES. USE, MODIFICATION, AND REDISTRIBUTION OF THIS WORK IS SUBJECT
 * TO VERSION 2.0.1 OF THE OPENLDAP PUBLIC LICENSE, A COPY OF WHICH IS
 * AVAILABLE AT HTTP://WWW.OPENLDAP.ORG/LICENSE.HTML OR IN THE FILE "LICENSE"
 * IN THE TOP-LEVEL DIRECTORY OF THE DISTRIBUTION. ANY USE OR EXPLOITATION
 * OF THIS WORK OTHER THAN AS AUTHORIZED IN VERSION 2.0.1 OF THE OPENLDAP
 * PUBLIC LICENSE, OR OTHER PRIOR WRITTEN CONSENT FROM NOVELL, COULD SUBJECT
 * THE PERPETRATOR TO CRIMINAL AND CIVIL LIABILITY.
 ******************************************************************************/

package com.novell.ldap;

import com.novell.ldap.client.Debug;
import com.novell.ldap.resources.*;
import java.util.Locale;

/**
 *  Thrown to indicate that an LDAP exception has occurred. This is a general
 *  exception which includes a message and an LDAP result code.
 *
 *  
An LDAPException can result from physical problems (such as
 *  network errors) as well as problems with LDAP operations detected
 *  by the server. For example, if an LDAP add operation fails because of a
 *  duplicate entry, the server returns a result code.
 *
 *  
Five possible sources of information are available from LDAPException:
 *  

 *      
Result Code:
 *      
The getResultCode method returns a result code,
 *      which can be compared against standard LDAP result codes. 
 *      
Message:
 *      
The getMessage method returns a localized message
 *      from the message resource that corresponds to the result code.
 *      
 *      
LDAP server Message:
 *      
The getLDAPErrorMessage method returns any error
 *      message received from the LDAP server.
 *      
Matched DN:
 *      
The getMatchedDN method retrieves the part of a
 *      submitted distinguished name which could be matched by the server
 *      
Root Cause:
 *      
The getCause method returns the a nested exception
 *      that was the original cause for the error. 
 *  

 *
 *  
The toString method returns a string containing all
 *  the above sources of information, if they have a value.
 *
 *  
Exceptions generated by the API, i.e. that are not a result
 *  of a server response, can be identified as instanceof
 *  {@link LDAPLocalException}
 *
 *  
The following table lists the standard LDAP result codes.
 *  See RFC2251 for a discussion of the meanings of the result codes.
 *  The corresponding ASN.1 definition from RFC2251 is provided in parentheses.
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
 *  
Value
 *  
Result Code
 *  
 0
{@link #SUCCESS} (success) 
 1
{@link #OPERATIONS_ERROR} (operationsError) 
 2
{@link #PROTOCOL_ERROR} (protocolError) 
 3
{@link #TIME_LIMIT_EXCEEDED} (timeLimitExceeded) 
 4
{@link #SIZE_LIMIT_EXCEEDED} (sizeLimitExceeded) 
 5
{@link #COMPARE_FALSE} (compareFalse) 
 6
{@link #COMPARE_TRUE} (compareTrue) 
 7
{@link #AUTH_METHOD_NOT_SUPPORTED} (authMethodNotSupported) 
 8
{@link #STRONG_AUTH_REQUIRED} (strongAuthRequired) 
 10
{@link #REFERRAL} (referral) 
 11
{@link #ADMIN_LIMIT_EXCEEDED} (adminLimitExceeded) 
 12
{@link #UNAVAILABLE_CRITICAL_EXTENSION} (unavailableCriticalExtension) 
 13
{@link #CONFIDENTIALITY_REQUIRED} (confidentialityRequired) 
 14
{@link #SASL_BIND_IN_PROGRESS} (saslBindInProgress) 
 16
{@link #NO_SUCH_ATTRIBUTE} (noSuchAttribute) 
 17
{@link #UNDEFINED_ATTRIBUTE_TYPE} (undefinedAttributeType) 
 18
{@link #INAPPROPRIATE_MATCHING} (inappropriateMatching) 
 19
{@link #CONSTRAINT_VIOLATION} (constraintViolation) 
 20
{@link #ATTRIBUTE_OR_VALUE_EXISTS} (AttributeOrValueExists) 
 21
{@link #INVALID_ATTRIBUTE_SYNTAX} (invalidAttributeSyntax) 
 32
{@link #NO_SUCH_OBJECT} (noSuchObject) 
 33
{@link #ALIAS_PROBLEM} (aliasProblem) 
 34
{@link #INVALID_DN_SYNTAX} (invalidDNSyntax) 
 35
{@link #IS_LEAF} (isLeaf) 
 36
{@link #ALIAS_DEREFERENCING_PROBLEM} (aliasDereferencingProblem) 
 48
{@link #INAPPROPRIATE_AUTHENTICATION} (inappropriateAuthentication) 
 49
{@link #INVALID_CREDENTIALS} (invalidCredentials) 
 50
{@link #INSUFFICIENT_ACCESS_RIGHTS} (insufficientAccessRights) 
 51
{@link #BUSY} (busy) 
 52
{@link #UNAVAILABLE} (unavailable) 
 53
{@link #UNWILLING_TO_PERFORM} (unwillingToPerform) 
 54
{@link #LOOP_DETECT} (loopDetect) 
 64
{@link #NAMING_VIOLATION} (namingViolation) 
 65
{@link #OBJECT_CLASS_VIOLATION} (objectClassViolation) 
 66
{@link #NOT_ALLOWED_ON_NONLEAF} (notAllowedOnNonLeaf) 
 67
{@link #NOT_ALLOWED_ON_RDN} (notAllowedOnRDN) 
 68
{@link #ENTRY_ALREADY_EXISTS} (entryAlreadyExists) 
 69
{@link #OBJECT_CLASS_MODS_PROHIBITED} (objectClassModsProhibited) 
 71
{@link #AFFECTS_MULTIPLE_DSAS} (affectsMultipleDSAs 
 80
{@link #OTHER} (other) 
 *
 *  
Local errors, resulting from actions other than an operation on a
 *  server.
 *
 *  
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *   
 *  
Value
 *   
Result Code
 *   
81
{@link #SERVER_DOWN}
82
{@link #LOCAL_ERROR}
83
{@link #ENCODING_ERROR}
84
{@link #DECODING_ERROR}
85
{@link #LDAP_TIMEOUT}
86
{@link #AUTH_UNKNOWN}
87
{@link #FILTER_ERROR}
88
{@link #USER_CANCELLED}
90
{@link #NO_MEMORY}
91
{@link #CONNECT_ERROR}
92
{@link #LDAP_NOT_SUPPORTED}
93
{@link #CONTROL_NOT_FOUND}
94
{@link #NO_RESULTS_RETURNED}
95
{@link #MORE_RESULTS_TO_RETURN}
96
{@link #CLIENT_LOOP}
97
{@link #REFERRAL_LIMIT_EXCEEDED}
100
{@link #INVALID_RESPONSE}
101
{@link #AMBIGUOUS_RESPONSE}
112
{@link #TLS_NOT_SUPPORTED}
 */

public class LDAPException extends Exception
{
   // The Result Code
   private int resultCode = 0;
   // The localized message
   private String messageOrKey = null;
   // The arguments associated with the localized message
   private Object[] arguments = null;
   // The Matched DN
   private String matchedDN = null;
   // The Root Cause
   private Throwable rootException = null;
   // A message from the server
   private String serverMessage = null;

  /**
   *Indicates the requested client operation completed successfully.
   *
   * 
SUCCESS = 0

   */
   public final static int SUCCESS = 0;

  /**
   * Indicates an internal error.
   *
   * 
The server is unable to respond with a more specific error and is
   * also unable to properly respond to a request. It does not indicate
   * that the client has sent an erroneous message.
   *
   *
OPERATIONS_ERROR = 1
   */
   public final static int OPERATIONS_ERROR = 1;

  /**
   * Indicates that the server has received an invalid or malformed request
   * from the client.
   *
   *
PROTOCOL_ERROR = 2
   */
   public final static int PROTOCOL_ERROR = 2;

  /**
   * Indicates that the operation's time limit specified by either the
   * client or the server has been exceeded.
   *
   * 
On search operations, incomplete results are returned.
   *
   *
TIME_LIMIT_EXCEEDED = 3
   */
   public final static int TIME_LIMIT_EXCEEDED = 3;

  /**
   * Indicates that in a search operation, the size limit specified by
   * the client or the server has been exceeded. Incomplete results are
   * returned.
   *
   * 
SIZE_LIMIT_EXCEEDED = 4
   */
   public final static int SIZE_LIMIT_EXCEEDED = 4;

  /**
   * Does not indicate an error condition. Indicates that the results of
   * a compare operation are false.
   *
   * 
COMPARE_FALSE = 5
   */
   public final static int COMPARE_FALSE = 5;

  /**
   * Does not indicate an error condition. Indicates that the results of a
   * compare operation are true.
   *
   * 
COMPARE_TRUE = 6
   */
   public final static int COMPARE_TRUE = 6;

  /**
   * Indicates that during a bind operation the client requested an
   * authentication method not supported by the LDAP server.
   *
   * 
AUTH_METHOD_NOT_SUPPORTED = 7
   */
   public final static int AUTH_METHOD_NOT_SUPPORTED = 7;

  /**
   *Indicates a problem with the level of authentication.
   *
   * 
One of the following has occurred:
   *

   * 
In bind requests, the LDAP server accepts only strong
   *     authentication.
   * 
In a client request, the client requested an operation such as delete
   *     that requires strong authentication.
   * 
In an unsolicited notice of disconnection, the LDAP server discovers
   *     the security protecting the communication between the client and
   *     server has unexpectedly failed or been compromised.
   *
   * 
STRONG_AUTH_REQUIRED = 8
   */
   public final static int STRONG_AUTH_REQUIRED = 8;

   /**
   * Returned by some LDAP servers to LDAPv2 clients to indicate that a referral
   * has been returned in the error string.
   *
   * 
LDAP_PARTIAL_RESULTS = 9
   */
   public final static int LDAP_PARTIAL_RESULTS = 9;

  /**
   * Does not indicate an error condition. In LDAPv3, indicates that the server
   * does not hold the target entry of the request, but that the servers in the
   * referral field may.
   *
   * 
REFERRAL = 10
   */
   public final static int REFERRAL = 10;

  /**
   * Indicates that an LDAP server limit set by an administrative authority
   * has been exceeded.
   *
   * 
ADMIN_LIMIT_EXCEEDED = 11
   */
   public final static int ADMIN_LIMIT_EXCEEDED = 11;

  /**
   * Indicates that the LDAP server was unable to satisfy a request because
   * one or more critical extensions were not available.
   *
   * 
Either the server does not support the control or the control is not
   *  appropriate for the operation type.
   *
   * 
UNAVAILABLE_CRITICAL_EXTENSION = 12
   */
   public final static int UNAVAILABLE_CRITICAL_EXTENSION = 12;

  /**
   * Indicates that the session is not protected by a protocol such as
   * Transport Layer Security (TLS), which provides session confidentiality.
   *
   * 
CONFIDENTIALITY_REQUIRED = 13
   */
   public final static int CONFIDENTIALITY_REQUIRED = 13;

  /**
   * Does not indicate an error condition, but indicates that the server is
   * ready for the next step in the process. The client must send the server
   * the same SASL mechanism to continue the process.
   *
   * 
SASL_BIND_IN_PROGRESS = 14
   */
   public final static int SASL_BIND_IN_PROGRESS = 14;

  /**
   * Indicates that the attribute specified in the modify or compare
   * operation does not exist in the entry.
   *
   * 
NO_SUCH_ATTRIBUTE = 16
   */
   public final static int NO_SUCH_ATTRIBUTE = 16;

  /**
   * Indicates that the attribute specified in the modify or add operation
   * does not exist in the LDAP server's schema.
   *
   * 
UNDEFINED_ATTRIBUTE_TYPE = 17
   */
   public final static int UNDEFINED_ATTRIBUTE_TYPE = 17;

  /**
   * Indicates that the matching rule specified in the search filter does
   * not match a rule defined for the attribute's syntax.
   *
   * 
INAPPROPRIATE_MATCHING = 18
   */
   public final static int INAPPROPRIATE_MATCHING = 18;

  /**
   * Indicates that the attribute value specified in a modify, add, or
   * modify DN operation violates constraints placed on the attribute. The
   * constraint can be one of size or content (for example, string only,
   * no binary data).
   *
   * 
CONSTRAINT_VIOLATION = 19
   */
   public final static int CONSTRAINT_VIOLATION = 19;

  /**
   * Indicates that the attribute value specified in a modify or add
   * operation already exists as a value for that attribute.
   *
   * 
ATTRIBUTE_OR_VALUE_EXISTS = 20
   */
   public final static int ATTRIBUTE_OR_VALUE_EXISTS = 20;

  /**
   * Indicates that the attribute value specified in an add, compare, or
   * modify operation is an unrecognized or invalid syntax for the attribute.
   *
   * 
INVALID_ATTRIBUTE_SYNTAX = 21
   */
   public final static int INVALID_ATTRIBUTE_SYNTAX = 21;

  /**
   * Indicates the target object cannot be found.
   *
   * 
This code is not returned on the following operations:
   * 

   * 
Search operations that find the search base but cannot find any
   *     entries that match the search filter.
   * 
Bind operations.
   * 
   * 
NO_SUCH_OBJECT = 32
   */
   public final static int NO_SUCH_OBJECT = 32;

  /**
   * Indicates that an error occurred when an alias was dereferenced.
   *
   * 
ALIAS_PROBLEM = 33
   */
   public final static int ALIAS_PROBLEM = 33;

  /**
   * Indicates that the syntax of the DN is incorrect.
   *
   * 
If the DN syntax is correct, but the LDAP server's structure
   *  rules do not permit the operation, the server returns
   *  LDAP_UNWILLING_TO_PERFORM. 
   *
   * 
INVALID_DN_SYNTAX = 34
   */
   public final static int INVALID_DN_SYNTAX = 34;

  /**
   * Indicates that the specified operation cannot be performed on a
   * leaf entry.
   *
   * 
This code is not currently in the LDAP specifications, but is
   * reserved for this constant.
   *
   * 
IS_LEAF = 35
   */
   public final static int IS_LEAF = 35;

  /**
   * Indicates that during a search operation, either the client does not
   * have access rights to read the aliased object's name or dereferencing
   * is not allowed.
   *
   * 
ALIAS_DEREFERENCING_PROBLEM = 36
   */
   public final static int ALIAS_DEREFERENCING_PROBLEM = 36;

  /**
   * Indicates that during a bind operation, the client is attempting to use
   * an authentication method that the client cannot use correctly.
   *
   *
 For example, either of the following cause this error:
   * 

   * 
The client returns simple credentials when strong credentials are
   *     required.
   * 
The client returns a DN and a password for a simple bind when the
         entry does not have a password defined.
   * 
   * 
INAPPROPRIATE_AUTHENTICATION = 48
   */
   public final static int INAPPROPRIATE_AUTHENTICATION = 48;

  /**
   * Indicates that invalid information was passed during a bind operation.
   *
   * 
One of the following occurred:
   *

   * 
 The client passed either an incorrect DN or password.
   * 
 The password is incorrect because it has expired, intruder detection
   *       has locked the account, or some other similar reason.
   *
   * 
INVALID_CREDENTIALS = 49
   */
   public final static int INVALID_CREDENTIALS = 49;

  /**
   * Indicates that the caller does not have sufficient rights to perform
   * the requested operation.
   *
   * 
INSUFFICIENT_ACCESS_RIGHTS = 50
   */
   public final static int INSUFFICIENT_ACCESS_RIGHTS = 50;

  /**
   * Indicates that the LDAP server is too busy to process the client request
   * at this time, but if the client waits and resubmits the request, the
   * server may be able to process it then.
   *
   * 
BUSY = 51
   */
   public final static int BUSY = 51;

  /**
   * Indicates that the LDAP server cannot process the client's bind
   * request, usually because it is shutting down.
   *
   * 
UNAVAILABLE = 52
   */
   public final static int UNAVAILABLE = 52;

  /**
   * Indicates that the LDAP server cannot process the request because of
   * server-defined restrictions.
   *
   * 
This error is returned for the following reasons:
   * 

   * 
The add entry request violates the server's structure rules.
   * 
The modify attribute request specifies attributes that users
   *     cannot modify.
   * 
   * 
UNWILLING_TO_PERFORM = 53
   */
   public final static int UNWILLING_TO_PERFORM = 53;

  /**
   * Indicates that the client discovered an alias or referral loop,
   * and is thus unable to complete this request.
   *
   * 
LOOP_DETECT = 54
   */
   public final static int LOOP_DETECT = 54;

  /**
   * Indicates that the add or modify DN operation violates the schema's
   * structure rules.
   *
   * 
For example,
   *

   * 
The request places the entry subordinate to an alias.
   * 
The request places the entry subordinate to a container that
   *     is forbidden by the containment rules.
   * 
The RDN for the entry uses a forbidden attribute type.
   *
   * 
NAMING_VIOLATION = 64
   */
   public final static int NAMING_VIOLATION = 64;

  /**
   * Indicates that the add, modify, or modify DN operation violates the
   * object class rules for the entry.
   *
   * 
For example, the following types of request return this error:
   * 

   * 
The add or modify operation tries to add an entry without a value
   *     for a required attribute.
   * 
The add or modify operation tries to add an entry with a value for
   *     an attribute which the class definition does not contain.
   * 
The modify operation tries to remove a required attribute without
   *     removing the auxiliary class that defines the attribute as required.
   *
   * 
OBJECT_CLASS_VIOLATION = 65
   */
   public final static int OBJECT_CLASS_VIOLATION = 65;

  /**
   * Indicates that the requested operation is permitted only on leaf entries.
   *
   * 
For example, the following types of requests return this error:
   * 

   * 
The client requests a delete operation on a parent entry.
   * 
 The client request a modify DN operation on a parent entry.
   * 
   * 
NOT_ALLOWED_ON_NONLEAF = 66
   */
   public final static int NOT_ALLOWED_ON_NONLEAF = 66;

  /**
   * Indicates that the modify operation attempted to remove an attribute
   * value that forms the entry's relative distinguished name.
   *
   * 
NOT_ALLOWED_ON_RDN = 67
   */
   public final static int NOT_ALLOWED_ON_RDN = 67;

  /**
   * Indicates that the add operation attempted to add an entry that already
   * exists, or that the modify operation attempted to rename an entry to the
   * name of an entry that already exists.
   *
   * 
ENTRY_ALREADY_EXISTS = 68
   */
   public final static int ENTRY_ALREADY_EXISTS = 68;

  /**
   * Indicates that the modify operation attempted to modify the structure
   * rules of an object class.
   *
   * 
OBJECT_CLASS_MODS_PROHIBITED = 69
   */
   public final static int OBJECT_CLASS_MODS_PROHIBITED = 69;

  /**
   * Indicates that the modify DN operation moves the entry from one LDAP
   * server to another and thus requires more than one LDAP server.
   *
   * 
AFFECTS_MULTIPLE_DSAS = 71
   */
   public final static int AFFECTS_MULTIPLE_DSAS = 71;

  /**
   * Indicates an unknown error condition.
   *
   * 
OTHER = 80
   */
   public final static int OTHER = 80;

  /////////////////////////////////////////////////////////////////////////////
  // Local Errors, resulting from actions other than an operation on a server
  /////////////////////////////////////////////////////////////////////////////

  /**
   * Indicates that the LDAP libraries cannot establish an initial connection
   * with the LDAP server. Either the LDAP server is down or the specified
   * host name or port number is incorrect.
   *
   * 
SERVER_DOWN = 81
   */
   public final static int SERVER_DOWN = 81;

  /**
   * Indicates that the LDAP client has an error. This is usually a failed
   * dynamic memory allocation error.
   *
   * 
LOCAL_ERROR = 82
   */
   public final static int LOCAL_ERROR = 82;

  /**
   * Indicates that the LDAP client encountered errors when encoding an
   * LDAP request intended for the LDAP server.
   *
   * 
ENCODING_ERROR = 83
   */
   public final static int ENCODING_ERROR = 83;

  /**
   * Indicates that the LDAP client encountered errors when decoding an
   * LDAP response from the LDAP server.
   *
   * 
DECODING_ERROR = 84
   */
   public final static int DECODING_ERROR = 84;

  /**
   * Indicates that the time limit of the LDAP client was exceeded while
   * waiting for a result.
   *
   * 
LDAP_TIMEOUT = 85
   */
   public final static int LDAP_TIMEOUT = 85;

  /**
   * Indicates that a bind method was called with an unknown
   * authentication method.
   *
   * 
AUTH_UNKNOWN = 86
   */
   public final static int AUTH_UNKNOWN = 86;

  /**
   * Indicates that the search method was called with an invalid
   * search filter.
   *
   * 
FILTER_ERROR = 87
   */
   public final static int FILTER_ERROR = 87;

  /**
   * Indicates that the user cancelled the LDAP operation.
   *
   * 
USER_CANCELLED = 88
   */
   public final static int USER_CANCELLED = 88;


  /**
   * Indicates that a dynamic memory allocation method failed when calling
   * an LDAP method.
   *
   * 
NO_MEMORY = 90
   */
   public final static int NO_MEMORY = 90;

  /**
   * Indicates that the LDAP client has lost either its connection or
   * cannot establish a connection to the LDAP server.
   *
   * 
CONNECT_ERROR = 91
   */
   public final static int CONNECT_ERROR = 91;

  /**
   * Indicates that the requested functionality is not supported by the
   * client. For example, if the LDAP client is established as an LDAPv2
   * client, the libraries set this error code when the client requests
   * LDAPv3 functionality.
   *
   * 
LDAP_NOT_SUPPORTED = 92
   */
   public final static int LDAP_NOT_SUPPORTED = 92;

  /**
   * Indicates that the client requested a control that the libraries
   * cannot find in the list of supported controls sent by the LDAP server.
   *
   * 
CONTROL_NOT_FOUND = 93
   */
   public final static int CONTROL_NOT_FOUND = 93;

  /**
   * Indicates that the LDAP server sent no results.
   *
   * 
NO_RESULTS_RETURNED = 94
   */
   public final static int NO_RESULTS_RETURNED = 94;

  /**
   * Indicates that more results are chained in the result message.
   *
   * 
MORE_RESULTS_TO_RETURN = 95
   */
   public final static int MORE_RESULTS_TO_RETURN = 95;

  /**
   * Indicates the LDAP libraries detected a loop. Usually this happens
   * when following referrals.
   *
   * 
CLIENT_LOOP = 96
   */
   public final static int CLIENT_LOOP = 96;

  /**
   * Indicates that the referral exceeds the hop limit. The default hop
   * limit is ten.
   *
   * 
The hop limit determines how many servers the client can hop through
   * to retrieve data. For example, suppose the following conditions:
   * 

   * 
Suppose the hop limit is two.
   * 
 If the referral is to server D which can be contacted only through
          server B (1 hop) which contacts server C (2 hops) which contacts
          server D (3 hops).
   * 
   * 
 With these conditions, the hop limit is exceeded and the LDAP
   * libraries set this code.
   *
   * 
REFERRAL_LIMIT_EXCEEDED = 97
   */
   public final static int REFERRAL_LIMIT_EXCEEDED = 97;

   /**
    * Indicates that the server response to a request is invalid.
    *
    * 
INVALID_RESPONSE = 100
    */
   public final static int INVALID_RESPONSE = 100;

   /**
    * Indicates that the server response to a request is ambiguous.
    *
    * 
AMBIGUOUS_RESPONSE = 101
    */
   public final static int AMBIGUOUS_RESPONSE = 101;

   /**
    * Indicates that TLS is not supported on the server.
    *
    * 
TLS_NOT_SUPPORTED = 112
    */
   public final static int TLS_NOT_SUPPORTED = 112;

   /*
    * Note: Error strings have been pulled out into
    * ResultCodeMessages.properties
    */

   /**
    * Constructs a default exception with no specific error information.
    */
   public LDAPException()
   {
      super();
      return;
   }

   /**
    * 
Constructs an exception with a detailed message obtained from the
    * specified MessageOrKey String, the result code,
    * and a server meessage.
    *
    * 
The String is used either as a message key to obtain a localized
    * messsage from ExceptionMessages, or if there is no key in the
    * resource matching the text, it is used as the detailed message itself.
    *
    *  @param messageOrKey  Key to addition result information, a key into
    *                       ExceptionMessages, or the information
    *                       itself if the key doesn't exist.
    *


    *  @param resultCode    The result code returned.
    *


    *  @param serverMsg     Error message specifying additional information
    *                       from the server
    */
   public LDAPException(String messageOrKey, int resultCode, String serverMsg)
   {
      this( messageOrKey, null, resultCode, serverMsg, null, null);
      return;
   }

   /**
    * 
Constructs an exception with a detailed message obtained from the
    * specified MessageOrKey String and modifying arguments.
    * Additional parameters specify the result code and server message.
    *
    * 
The String is used either as a message key to obtain a localized
    * messsage from ExceptionMessages, or if there is no key in the
    * resource matching the text, it is used as the detailed message itself.
    *
    * 
The message in the default locale is built with the supplied arguments,
    * which are saved to be used for building messages for other locales.
    *
    *  @param messageOrKey  Key to addition result information, a key into
    *                       ExceptionMessages, or the information
    *                       itself if the key doesn't exist.
    *


    *  @param arguments    The modifying arguments to be included in the
    *                      message string.
    *


    *  @param serverMsg     Error message specifying additional information
    *                       from the server
    *


    *  @param resultCode    The result code returned.
    */
   public LDAPException( String messageOrKey,
                         Object[] arguments,
                         int resultCode,
                         String serverMsg)
   {
      this( messageOrKey, arguments, resultCode, serverMsg, null, null);
      return;
   }

   /**
    * 
Constructs an exception with a detailed message obtained from the
    * specified MessageOrKey String.
    * Additional parameters specify the result code, the server message, and a
    * rootException which is the underlying cause of an error on the client.

    *
    * 
The String is used either as a message key to obtain a localized
    * messsage from ExceptionMessages, or if there is no key in the
    * resource matching the text, it is used as the detailed message itself.
    *
    *  @param messageOrKey  Key to addition result information, a key into
    *                       ExceptionMessages, or the information
    *                       itself if the key doesn't exist.
    *


    *  @param resultCode    The result code returned.
    *


    *  @param serverMsg     Error message specifying additional information
    *                       from the server
    *


    *  @param rootException  A throwable which is the underlying cause
    *                        of the LDAPException.
    */
   public LDAPException( String messageOrKey,
                         int resultCode,
                         String serverMsg,
                         Throwable rootException)
   {
      this( messageOrKey, null, resultCode, serverMsg, null, rootException);
      return;
   }

   /**
    * 
Constructs an exception with a detailed message obtained from the
    * specified MessageOrKey String and modifying arguments.
    * Additional parameters specify the result code, the server message,
    * and a rootException which is the underlying cause of an error
    * on the client.
    *
    * 
The String is used either as a message key to obtain a localized
    * messsage from ExceptionMessages, or if there is no key in the
    * resource matching the text, it is used as the detailed message itself.
    *
    * 
The message in the default locale is built with the supplied arguments,
    * which are saved to be used for building messages for other locales.
    *
    *  @param messageOrKey  Key to addition result information, a key into
    *                       ExceptionMessages, or the information
    *                       itself if the key doesn't exist.
    *


    *  @param arguments    The modifying arguments to be included in the
    *                       message string.
    *


    *  @param resultCode    The result code returned.
    *


    *  @param serverMsg     Error message specifying additional information
    *                       from the server
    *


    *  @param rootException  A throwable which is the underlying cause
    *                        of the LDAPException.
    */
   public LDAPException( String messageOrKey,
                         Object[] arguments,
                         int resultCode,
                         String serverMsg,
                         Throwable rootException)
   {
      this( messageOrKey, arguments, resultCode, serverMsg, null, rootException);
      return;
   }

   /**
    * 
Constructs an exception with a detailed message obtained from the
    * specified MessageOrKey String.
    * Additional parameters specify the result code, the message returned
    * from the server, and a matchedDN returned from the server.
    *
    * 
The String is used either as a message key to obtain a localized
    * messsage from ExceptionMessages, or if there is no key in the
    * resource matching the text, it is used as the detailed message itself.
    *
    *  @param messageOrKey  Key to addition result information, a key into
    *                       ExceptionMessages, or the information
    *                       itself if the key doesn't exist.
    *


    *  @param resultCode    The result code returned.
    *


    *  @param serverMsg     Error message specifying additional information
    *                       from the server
    *


    *  @param matchedDN      The maximal subset of a specified DN which could
    *                        be matched by the server on a search operation.
    */
   public LDAPException( String messageOrKey,
                         int resultCode,
                         String serverMsg,
                         String matchedDN)
   {
      this( messageOrKey, null, resultCode, serverMsg, matchedDN, null);
      return;
   }

   /**
    * 
Constructs an exception with a detailed message obtained from the
    * specified MessageOrKey String and modifying arguments.
    * Additional parameters specify the result code, a message returned from
    * the server, and a matchedDN returned from the server.
    *
    * 
The String is used either as a message key to obtain a localized
    * messsage from ExceptionMessages, or if there is no key in the
    * resource matching the text, it is used as the detailed message itself.
    *
    * 
The message in the default locale is built with the supplied arguments,
    * which are saved to be used for building messages for other locales.
    *
    *  @param messageOrKey  Key to addition result information, a key into
    *                       ExceptionMessages, or the information
    *                       itself if the key doesn't exist.
    *


    *  @param arguments    The modifying arguments to be included in the
    *                       message string.
    *


    *  @param resultCode    The result code returned.
    *


    *  @param serverMsg     Error message specifying additional information
    *                       from the server
    *


    *  @param matchedDN      The maximal subset of a specified DN which could
    *                        be matched by the server on a search operation.
    */
   public LDAPException( String messageOrKey,
                         Object[] arguments,
                         int resultCode,
                         String serverMsg,
                         String matchedDN)
   {
      this( messageOrKey, arguments, resultCode, serverMsg, matchedDN, null);
      return;
   }

   /**
    * 
Constructs an exception with a detailed message obtained from the
    * specified MessageOrKey String and modifying arguments.
    * Additional parameters specify the result code, a message returned
    * from the server, a matchedDN returned from
    * the server, and a rootException which is the underlying cause of an error
    * on the client.
    *
    * 
The String is used either as a message key to obtain a localized
    * messsage from ExceptionMessages, or if there is no key in the
    * resource matching the text, it is used as the detailed message itself.
    *
    * 
The message in the default locale is built with the supplied arguments,
    * which are saved to be used for building messages for other locales.
    *
    *  @param messageOrKey  Key to addition result information, a key into
    *                       ExceptionMessages, or the information
    *                       itself if the key doesn't exist.
    *


    *  @param arguments    The modifying arguments to be included in the
    *                       message string.
    *


    *  @param resultCode    The result code returned.
    *


    *  @param serverMsg     Error message specifying additional information
    *                       from the server
    *


    *  @param rootException  A throwable which is the underlying cause
    *                        of the LDAPException.
    *


    *  @param matchedDN      The maximal subset of a specified DN which could
    *                        be matched by the server on a search operation.
    */
   /* package */
   LDAPException(String messageOrKey,
                        Object[] arguments,
                        int resultCode,
                        String serverMsg,
                        String matchedDN,
                        Throwable rootException)
   {
      super(ResourcesHandler.getMessage(messageOrKey, arguments));
      this.messageOrKey = messageOrKey;
      this.arguments = arguments;
      this.resultCode = resultCode;
      this.rootException = rootException;
      this.matchedDN = matchedDN;
      this.serverMessage = serverMsg;
      if( Debug.LDAP_DEBUG) {
       Debug.trace( Debug.messages, "new LDAPException(Result=" +
            resultCode + ") " + super.getMessage());
      }
      return;
   }

   /**
    * Returns a string representing the result code in the default
    * locale.
    *
    * @return The message for the result code in the LDAPException object.
    */
   public String resultCodeToString()
   {
       return ResourcesHandler.getResultString( resultCode);
   }

   /**
    * Returns a string representing the specified result code in the default
    * locale.
    *
    * @param code  The result code for which a message is to be returned.
    *
    * @return The message corresponding to the specified result code, or
    *           or null if the message is not available for the default locale.
    */
   public static String resultCodeToString( int code )
   {
       return ResourcesHandler.getResultString( code);
   }

   /**
    * Returns a string representing the result code in the
    * specified locale.
    *
    * @param locale The locale in which to render the error message.
    *
    * @return A message corresponding to the result code in the
    * specified locale, or null if the message is not available
    * for the requested locale.

    */
   public String resultCodeToString( Locale locale )
   {
        return ResourcesHandler.getResultString( resultCode, locale);
   }

   /**
    * Returns a string representing the specified error code in the
    * specified locale.
    *
    *  @param code     The result code for which a message is to be
    *                  returned.
    *


    *  @param locale   The locale in which to render the message.
    *
    *  @return A message corresponding to the result code in the
    *  specified locale, or null if the message is not available
    *  for the requested locale.
    */
   public static String resultCodeToString( int code, Locale locale )
   {
        return ResourcesHandler.getResultString( code, locale);
   }

   /**
    * Returns the error message from the LDAP server, if this message is
    * available (that is, if this message was set). If the message was not set,
    * this method returns null.
    *
    * @return The error message or null if the message was not set.
    *
    */
    public String getLDAPErrorMessage()
    {
        if( (serverMessage != null) && ( serverMessage.length() == 0)) {
            return null;
        }
        return serverMessage;
    }

    /**
     * Returns the lower level Exception which caused the failure, if any.
     * For example, an IOException with additional information may be returned
     * on a CONNECT_ERROR failure.
     */
    public Throwable getCause()
    {
        return rootException;
    }


   /**
    * Returns the result code from the exception.
    *
    * 
The codes are defined as public final static int members
    * of the LDAP Exception class. If the exception is a
    * result of error information returned from a directory operation, the
    * code will be one of those defined for the class. Otherwise, a local error
    * code is returned. 
    */
   public int getResultCode()
   {
      return resultCode;
   }

   /**
    * Returns the part of a submitted distinguished name which could be
    * matched by the server.
    *
    * 
If the exception was caused by a local error, such as no server
    * available, the return value is null. If the exception resulted from
    * an operation being executed on a server, the value is an empty string
    * except when the result of the operation was one of the following:

    * 

    *  
NO_SUCH_OBJECT
    *  
ALIAS_PROBLEM
    *  
INVALID_DN_SYNTAX
    *  
ALIAS_DEREFERENCING_PROBLEM
    * 
    *
    *@return The part of a submitted distinguished name which could be
    * matched by the server or null if the error is a local error.
    */
   public String getMatchedDN()
   {
      return matchedDN;
   }

   public String getMessage()
   {
      return resultCodeToString();
   }

   public String getLocalizedMessage()
   {
      return resultCodeToString();
   }

   /**
    * returns a string of information about the exception and the
    * the nested exceptions, if any.
    */
   public String toString()
   {
       return getExceptionString("LDAPException");
   }

   /**
    * builds a string of information about the exception and the
    * the nested exceptions, if any.
    *
    * @param exception The name of the exception class
    */
   /* package */
   String getExceptionString( String exception)
   {
      String tmsg;

        // Format the basic exception information

        // Craft a string from the resouce file
        String msg = ResourcesHandler.getMessage("TOSTRING",
                                                 new Object[]
                                                 { exception,
                                                   super.getMessage(),
                                                   new Integer(resultCode),
                                                   resultCodeToString()
                                                 });
        // If found no string from resource file, use a default string
        if( msg.equalsIgnoreCase( "TOSTRING")) {
            msg = exception + ": (" + resultCode + ") " + resultCodeToString();
        }

        // Add server message
        if( (serverMessage != null) && ( serverMessage.length() != 0)) {
            tmsg = ResourcesHandler.getMessage("SERVER_MSG",
                                                new Object[]
                                                { exception,
                                                  serverMessage
                                                });
            // If found no string from resource file, use a default string
            if( tmsg.equalsIgnoreCase( "SERVER_MSG")) {
                tmsg = exception + ": Server Message: " + serverMessage;
            }

            msg = msg + '\n' + tmsg;
        }

        // Add Matched DN message
        if( matchedDN != null) {
            tmsg = ResourcesHandler.getMessage("MATCHED_DN",
                                                new Object[]
                                                { exception,
                                                  matchedDN
                                                });
            // If found no string from resource file, use a default string
            if( tmsg.equalsIgnoreCase( "MATCHED_DN")) {
                tmsg = exception + ": Matched DN: " + matchedDN;
            }

            msg = msg + '\n' + tmsg;
        }

        if( rootException != null) {
                msg = msg + '\n' + rootException.toString();
        }
        return msg;
    }

}