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 duplicate entry).
*
*
* Most errors that occur throw this type of exception. In order to determine
* the cause of the error, you can call the getLDAPResultCode()
* method to get the specific result code and compare this code against
* the result codes defined as fields in this class. (For example, if
* the result code matches the value of the field
* LDAPException.TIME_LIMIT_EXCEEDED, the time limit passed
* before the search operation could be completed.)
*
*
* This exception includes methods for getting an error message that
* corresponds to the LDAP result code (for example, "Timelimit exceeded"
* for LDAPException.TIME_LIMIT_EXCEEDED). These error
* messages are specified in the following files:
*
netscape/ldap/errors/ErrorCodes_locale_string.props* where locale_string is the name of the locale that includes * the language and country, but not the variant. *
* * For example: *
netscape/ldap/errors/ErrorCodes_en_US.props* * The LDAP Java classes get this locale name by calling the *
java.util.Locale.toString method for the specified
* locale and ignoring the variant. If no locale is specified, the
* LDAP Java classes use the java.util.Locale.getDefault
* method to get the locale of the local host system.
*
*
* In order to get error messages for different locales, you need to
* provide files containing the error messages for those locales.
* The files should be located in the netscape/ldap/errors
* directory and should use the naming convention specified above.
*
* * The following is a list of LDAP result codes: *
* Result * Code Defined Value * ====== ============= * 0 SUCCESS * 1 OPERATION_ERROR * 2 PROTOCOL_ERROR * 3 TIME_LIMIT_EXCEEDED * 4 SIZE_LIMIT_EXCEEDED * 5 COMPARE_FALSE * 6 COMPARE_TRUE * 7 AUTH_METHOD_NOT_SUPPORTED * 8 STRONG_AUTH_REQUIRED * 9 LDAP_PARTIAL_RESULTS * 10 REFERRAL (LDAP v3) * 11 ADMIN_LIMIT_EXCEEDED (LDAP v3) * 12 UNAVAILABLE_CRITICAL_EXTENSION (LDAP v3) * 13 CONFIDENTIALITY_REQUIRED (LDAP v3) * 14 SASL_BIND_IN_PROGRESS (LDAP v3) * 16 NO_SUCH_ATTRIBUTE * 17 UNDEFINED_ATTRIBUTE_TYPE * 18 INAPPROPRIATE_MATCHING * 19 CONSTRAINT_VIOLATION * 20 ATTRIBUTE_OR_VALUE_EXISTS * 21 INVALID_ATTRIBUTE_SYNTAX * 32 NO_SUCH_OBJECT * 33 ALIAS_PROBLEM * 34 INVALID_DN_SYNTAX * 35 IS_LEAF * 36 ALIAS_DEREFERENCING_PROBLEM * 48 INAPPROPRIATE_AUTHENTICATION * 49 INVALID_CREDENTIALS * 50 INSUFFICIENT_ACCESS_RIGHTS * 51 BUSY * 52 UNAVAILABLE * 53 UNWILLING_TO_PERFORM * 54 LOOP_DETECT * 64 NAMING_VIOLATION * 65 OBJECT_CLASS_VIOLATION * 66 NOT_ALLOWED_ON_NONLEAF * 67 NOT_ALLOWED_ON_RDN * 68 ENTRY_ALREADY_EXISTS * 69 OBJECT_CLASS_MODS_PROHIBITED * 71 AFFECTS_MULTIPLE_DSAS (LDAP v3) * 80 OTHER * 81 SERVER_DOWN * 85 LDAP_TIMEOUT * 89 PARAM_ERROR * 91 CONNECT_ERROR * 92 LDAP_NOT_SUPPORTED * 93 CONTROL_NOT_FOUND * 94 NO_RESULTS_RETURNED * 95 MORE_RESULTS_TO_RETURN * 96 CLIENT_LOOP * 97 REFERRAL_LIMIT_EXCEEDED **
* * @version 1.0 * @see netscape.ldap.LDAPReferralException */ public class LDAPException extends java.lang.Exception { /** * (0) The operation completed successfully. */ public final static int SUCCESS = 0; /** * (1) An internal error occurred in the LDAP server. */ public final static int OPERATION_ERROR = 1; /** * (2) A LDAP server could not correctly interpret the request * sent by your client because the request does not strictly * comply with the LDAP protocol. (For example, the data * was not correctly BER-encoded, or a specified value -- such * as the search scope or modification type -- does not * comply with the LDAP protocol. If you invent your own * search scope, for instance, this result code might be returned.
*/
public final static int PROTOCOL_ERROR = 2;
/**
* (3) The search operation could not be completed within
* the maximum time limit. You can specify the maximum time
* limit by calling the LDAPConnection.setOption
* method or the LDAPSearchConstraints.setServerTimeLimit
* method.
*
* @see netscape.ldap.LDAPConnection#setOption
* @see netscape.ldap.LDAPSearchConstraints#setServerTimeLimit
*/
public final static int TIME_LIMIT_EXCEEDED = 3;
/**
* (4) The search found more than the maximum number of results.
* You can specify the maximum number of results by calling the
* LDAPConnection.setOption method or the
* LDAPSearchConstraints.setSizeLimit method.
*
* @see netscape.ldap.LDAPConnection#setOption
* @see netscape.ldap.LDAPSearchConstraints#setMaxResults
*/
public final static int SIZE_LIMIT_EXCEEDED = 4;
/**
* (5) Value returned by an LDAP compare operation if the
* specified attribute and value is not found in the entry
* (no matching value found).
*
* @see netscape.ldap.LDAPConnection#compare
*/
public final static int COMPARE_FALSE = 5;
/**
* (6) Value returned by an LDAP compare operation if the
* specified attribute and value is found in the entry
* (matching value found).
*
* @see netscape.ldap.LDAPConnection#compare
*/
public final static int COMPARE_TRUE = 6;
/**
* (7) The specified authentication method is not supported
* by the LDAP server that you are connecting to. The
* LDAPConnection class is implemented so that
* LDAPConnection.authenticate always
* uses the LDAP_AUTH_SIMPLE method of authentication.
* (LDAPConnection.authenticate does not
* allow you to select the method of authentication.)
*/
public final static int AUTH_METHOD_NOT_SUPPORTED = 7;
/**
* (8) A stronger authentication method (more than LDAP_AUTH_SIMPLE)
* is required by the LDAP server that you are connecting to.
* The LDAPConnection class is implemented so that
* LDAPConnection.authenticate always
* uses the LDAP_AUTH_SIMPLE method of authentication.
* (LDAPConnection.authenticate does not
* allow you to select the method of authentication.)
*/
public final static int STRONG_AUTH_REQUIRED = 8;
/**
* (9) The LDAP server is referring your client to another
* LDAP server. If you set up the LDAPConnection
* options or the LDAPConstraints options
* for automatic referral, your client will automatically
* connect and authenticate to the other LDAP server.
* (This LDAPException will not be raised.)
*
*
* (To set up automatic referrals in an LDAPConnection
* object, set the LDAPConnection.REFERRALS option
* to true and the LDAPConnection.REFERRALS_REBIND_PROC
* option to the object containing the method for retrieving
* authentication information (in other words, the distinguished
* name and password to use when authenticating to other LDAP servers).
*
*
* If instead you set LDAPConnection.REFERRALS
* to false (or if you set
* LDAPConstraints.setReferrals to false,
* an LDAPReferralException is raised.
*
*
* If an error occurs during the referral process, an
* LDAPException with this result code
* (LDAP_PARTIAL_RESULTS) is raised.
*
* * @see netscape.ldap.LDAPConnection#setOption * @see netscape.ldap.LDAPConstraints#setReferrals * @see netscape.ldap.LDAPConstraints#setRebindProc * @see netscape.ldap.LDAPRebind * @see netscape.ldap.LDAPRebindAuth * @see netscape.ldap.LDAPReferralException */ public final static int LDAP_PARTIAL_RESULTS = 9; /** * (10) [LDAP v3] The server does not hold the requested entry. * The referral field of the server's response contains a * reference to another server (or set of servers), which * your client can access through LDAP or other protocols. * Typically, these references are LDAP URLs that identify * the server that may contain the requested entry. *
*
* When this occurs, a LDAPReferralException
* is thrown. You can catch this exception and call the
* getURLs method to get the list of LDAP
* URLs from the exception.
*
* * @see netscape.ldap.LDAPReferralException */ public final static int REFERRAL = 10; /** * (11) [LDAP v3] The adminstrative limit on the * maximum number of entries to return was exceeded. * In the Netscape Directory Server 3.0, this * corresponds to the "look through limit" for * the server. This is the maximum number of * entries that the server will check through * when determining which entries match the * search filter and scope. *
*/ public final static int ADMIN_LIMIT_EXCEEDED = 11; /** * (12) [LDAP v3] The server received an LDAP v3 control * that is marked critical and either (1) is not * recognized or supported by the server, or * (2) is inappropriate for the operation requested. * The Netscape Directory Server 3.0 also returns * this result code if the client specifies a * matching rule that is not supported by the server. *
* * @see netscape.ldap.LDAPControl */ public final static int UNAVAILABLE_CRITICAL_EXTENSION = 12; /** * (13) [LDAP v3] A secure connection is required for * this operation. */ public final static int CONFIDENTIALITY_REQUIRED = 13; /** * (14) [LDAP v3] While authenticating your client * by using a SASL (Simple Authentication Security Layer) * mechanism, the server requires the client to send * a new SASL bind request (specifying the same SASL * mechanism) to continue the authentication process. */ public final static int SASL_BIND_IN_PROGRESS = 14; /** * (16) The specified attribute could not be found. */ public final static int NO_SUCH_ATTRIBUTE = 16; /** * (17) The specified attribute is not defined. */ public final static int UNDEFINED_ATTRIBUTE_TYPE = 17; /** * (18) An inappropriate type of matching was used. */ public final static int INAPPROPRIATE_MATCHING = 18; /** * (19) An internal error occurred in the LDAP server. */ public final static int CONSTRAINT_VIOLATION = 19; /** * (20) The value that you are adding to an attribute * already exists in the attribute. */ public final static int ATTRIBUTE_OR_VALUE_EXISTS = 20; /** * (21) The request contains invalid syntax. */ public final static int INVALID_ATTRIBUTE_SYNTAX = 21; /** * (32) The entry specified in the request does not exist. */ public final static int NO_SUCH_OBJECT = 32; /** * (33) An problem occurred with an alias. */ public final static int ALIAS_PROBLEM = 33; /** * (34) The specified distinguished name (DN) uses invalid syntax. */ public final static int INVALID_DN_SYNTAX = 34; /** * (35) The specified entry is a "leaf" entry (it has no entries * beneath it in the directory tree). */ public final static int IS_LEAF = 35; /** * (36) An error occurred when dereferencing an alias. */ public final static int ALIAS_DEREFERENCING_PROBLEM = 36; /** * (48) The authentication presented to the server is inappropriate. * This result code might occur, for example, if your client * presents a password and the corresponding entry has no * userpassword attribute. */ public final static int INAPPROPRIATE_AUTHENTICATION = 48; /** * (49) The credentials presented to the server for authentication * are not valid. (For example, the password sent to the server * does not match the user's password in the directory.) */ public final static int INVALID_CREDENTIALS = 49; /** * (50) The client is authenticated as a user who does not have the * access privileges to perform this operation. */ public final static int INSUFFICIENT_ACCESS_RIGHTS = 50; /** * (51) The LDAP server is busy. */ public final static int BUSY = 51; /** * (52) The LDAP server is unavailable. */ public final static int UNAVAILABLE = 52; /** * (53) The LDAP server is unable to perform the specified operation. */ public final static int UNWILLING_TO_PERFORM = 53; /** * (54) A loop has been detected. */ public final static int LOOP_DETECT = 54; /** * (60) The "server-side sorting" control * was not included with the "virtual list view" * control in the search request. */ public final static int SORT_CONTROL_MISSING = 60; /** * (61) An index range error occurred. */ public final static int INDEX_RANGE_ERROR = 61; /** * (64) A naming violation has occurred. */ public final static int NAMING_VIOLATION = 64; /** * (65) The requested operation will add or change * data so that the data no longer complies with * the schema. */ public final static int OBJECT_CLASS_VIOLATION = 65; /** * (66) The requested operation can only be performed * on an entry that has no entries beneath it in the * directory tree (in other words, a "leaf" entry). *
* * For example, you cannot delete or rename an entry * if the entry has subentries beneath it. *
*/ public final static int NOT_ALLOWED_ON_NONLEAF = 66; /** * (67) The specified operation cannot be performed on * a relative distinguished name (RDN). */ public final static int NOT_ALLOWED_ON_RDN = 67; /** * (68) The specified entry already exists. You might receive * this error if, for example, you attempt to add an entry * that already exists or if you attempt to change the name * of an entry to the name of an entry that already exists. */ public final static int ENTRY_ALREADY_EXISTS = 68; /** * (69) You cannot modify the specified object class. */ public final static int OBJECT_CLASS_MODS_PROHIBITED = 69; /** * (71) [LDAP v3] The client attempted to move an entry * from one LDAP server to another by requesting a "modify * DN" operation. In general, clients should not be able * to arbitrarily move entries and subtrees between servers. *
*
* @see netscape.ldap.LDAPConnection#rename(java.lang.String, java.lang.String, java.lang.String, boolean)
* @see netscape.ldap.LDAPConnection#rename(java.lang.String, java.lang.String, java.lang.String, boolean, LDAPConstraints)
*/
public final static int AFFECTS_MULTIPLE_DSAS = 71;
/**
* (80) General result code for other types of errors
* that may occur.
*/
public final static int OTHER = 80;
/**
* (81) The LDAP server cannot be contacted.
*/
public final static int SERVER_DOWN = 0x51;
/**
* (85) The operation could not be completed within the
* maximum time limit. You can specify the maximum time limit
* by calling the LDAPConstraints.setTimeLimit
* method.
* * @see netscape.ldap.LDAPConstraints#setTimeLimit */ public final static int LDAP_TIMEOUT = 0x55; /** * (89) When calling a constructor or method from your client, * one or more parameters were incorrectly specified. */ public final static int PARAM_ERROR = 0x59; /** * (91) Your LDAP client failed to connect to the LDAP server. */ public final static int CONNECT_ERROR = 0x5b; /** * (92) The request is not supported by this version of the LDAP protocol. */ public final static int LDAP_NOT_SUPPORTED = 0x5c; /** * (93) The requested control is not found. *
*
* @see netscape.ldap.LDAPControl
*/
public final static int CONTROL_NOT_FOUND = 0x5d;
/**
* (94) No results have been returned from the server.
*/
public final static int NO_RESULTS_RETURNED = 0x5e;
/**
* (95) More results are being returned from the server.
*/
public final static int MORE_RESULTS_TO_RETURN = 0x5f;
/**
* (96) Your LDAP client detected a loop in the referral.
*/
public final static int CLIENT_LOOP = 0x60;
/**
* (97) The number of sequential referrals (for example,
* the client may be referred first from LDAP server A to
* LDAP server B, then from LDAP server B to LDAP server C,
* and so on) has exceeded the maximum number of referrals
* (the LDAPv2.REFERRALS_HOP_LIMIT option).
*
*
* @see netscape.ldap.LDAPv2#REFERRALS_HOP_LIMIT
* @see netscape.ldap.LDAPConnection#getOption
* @see netscape.ldap.LDAPConnection#setOption
*/
public final static int REFERRAL_LIMIT_EXCEEDED = 0x61;
/**
* Internal variables
*/
private int resultCode = -1;
private String errorMessage = null;
private String matchedDN = null;
private Locale m_locale = Locale.getDefault();
private static Hashtable cacheResource = new Hashtable();
private static final String baseName = "netscape/ldap/errors/ErrorCodes";
/**
* Constructs a default exception with no specific error information.
*/
public LDAPException() {
}
/**
* Constructs a default exception with a specified string of
* additional information. This string appears if you call
* the toString() method.
*
* * This form is used for lower-level errors. * It is recommended that you always use one of the constructors * that takes a result code as a parameter. (If your exception is * thrown, any code that catches the exception may need to extract * the result code from the exception.) *
* @param message the additional error information
* @see netscape.ldap.LDAPException#toString()
*/
public LDAPException( String message ) {
super( message );
}
/**
* Constructs a default exception with a result code and
* a specified string of additional information. This string
* appears if you call the toString() method.
* The result code that you set is accessible through the
* getLDAPResultCode() method.
*
* * @param message the additional error information to specify * @param resultCode the result code returned from the * operation that caused this exception * @see netscape.ldap.LDAPException#toString() * @see netscape.ldap.LDAPException#getLDAPResultCode() */ public LDAPException( String message, int resultCode ) { super( message ); this.resultCode = resultCode; } /** * Constructs a default exception with a result code, a specified * string of additional information, and a string containing * information passed back from the server. *
*
* After you construct the LDAPException object,
* the result code and messages will be accessible through the
* following ways:
*
*
toString() method. *
getLDAPResultCode() method. *
getLDAPErrorMessage
* method. *
*
* Use this form of the constructor
* for higher-level LDAP operational errors.
* @param message the additional error information to specify
* @param resultCode the result code returned from the
* operation that caused this exception
* @param serverErrorMessage error message specifying additional
* information returned from the server
* @see netscape.ldap.LDAPException#toString()
* @see netscape.ldap.LDAPException#getLDAPResultCode()
* @see netscape.ldap.LDAPException#getLDAPErrorMessage()
*/
public LDAPException( String message, int resultCode,
String serverErrorMessage ) {
super( message );
this.resultCode = resultCode;
this.errorMessage = serverErrorMessage;
}
/**
* Constructs a default exception with a result code, a specified
* string of additional information, a string containing
* information passed back from the server, and the DN of the
* closest matching entry, if the exception was thrown because
* an entry could not be found (for example, if cn=Babs Jensen,
* ou=People, c=Airius.com could not be found but
* ou=People, c=Airius.com is a valid directory entry,
* the "matched DN" is ou=People, c=Airius.com.
*
*
* After you construct the LDAPException object,
* the result code and messages will be accessible through the
* following ways:
*
*
toString() method. *
getLDAPResultCode() method. *
getLDAPErrorMessage
* method. *
getMatchedDN method.*
*
* This form is used for higher-level LDAP operational errors.
* @param message the additional error information
* @param resultCode the result code returned
* @param serverErrorMessage error message specifying additional information
* returned from the server
* @param matchedDN maximal subset of a specified DN which could be
* matched by the server
* @see netscape.ldap.LDAPException#toString()
* @see netscape.ldap.LDAPException#getLDAPResultCode()
* @see netscape.ldap.LDAPException#getLDAPErrorMessage()
* @see netscape.ldap.LDAPException#getMatchedDN()
*/
public LDAPException( String message, int resultCode,
String serverErrorMessage, String matchedDN ) {
super( message );
this.resultCode = resultCode;
this.errorMessage = serverErrorMessage;
this.matchedDN = matchedDN;
}
/**
* Returns the result code from the last error that occurred.
* This result code is defined as a public final static int member
* of this class. Note that this value is not always valid.
* -1 indicates that the result code is invalid.
* @return the LDAP result code of the last operation.
*/
public int getLDAPResultCode () {
return resultCode;
}
/**
* Returns the error message from the last error, if this message
* is available (that is, if this message was set). If the message
* was not set, this method returns null.
*
*
* Note that this message is rarely set. (In order to set this message,
* the code constructing this exception must have called the constructor
* LDAPException(String, int, String). The last argument,
* which is additional error information returned from the server,
* is the string returned by getLDAPErrorMessage.
*
*
* In most cases, if you want information about
* the error generated, you should call the toString()
* method instead.
*
*
* @return the error message of the last error (or null
* if no message was set).
* @see netscape.ldap.LDAPException#toString()
*/
public String getLDAPErrorMessage () {
return errorMessage;
}
/**
* Returns the maximal subset of a DN which could be matched by the
* server, if the server returned one of the following errors:
*
NO_SUCH_OBJECT
* ALIAS_PROBLEM
* INVALID_DN_SYNTAX
* ALIAS_DEREFERENCING_PROBLEM
* cn=Babs Jensen, o=People, c=Airius.com
* could not be found by the DN o=People, c=Airius.com
* could be found, the matched DN is
* o=People, c=Airius.com.
*
*
* If the exception does not specify a matching DN,
* this method returns null.
* @return the maximal subset of a DN which could be matched,
* or null if the error is not one of the above.
*/
public String getMatchedDN () {
return matchedDN;
}
/**
* Gets the string representation of the exception, which
* includes the result code, the message sent back from
* the LDAP server, the portion of the DN that the server
* could find in the directory (if applicable), and the
* error message corresponding to this result code.
*
* * For example: * *
netscape.ldap.LDAPException: error result (32); server error message; matchedDN = ou=people,o=airius.com; No such object* * In this example,
error result is the string of
* additional information specified in the exception, 32 is
* the result code, server error message is the additional
* information from the server specified in the exception, the
* matched DN is ou=people,o=airius.com, and the error message
* corresponding to the result code 32 is No such
* object.
*
*
* The error message corresponding to the error code can also be
* retrieved by using the errorCodeToString method.
* Note that this method can generate error messages specific to
* a current locale.
*
*
* @return string representation of exception.
* @see netscape.ldap.LDAPException#errorCodeToString(int)
*/
public String toString() {
String str = super.toString() + " (" + resultCode + ")" ;
if ( (errorMessage != null) && (errorMessage.length() > 0) )
str += "; " + errorMessage;
if ( (matchedDN != null) && (matchedDN.length() > 0) )
str += "; matchedDN = " + matchedDN;
String errorStr = null;
if (((errorStr = errorCodeToString(m_locale)) != null) &&
(errorStr.length() > 0))
str += "; " + errorStr;
return str;
}
/**
* Returns the error message describing the error code (for this
* exception). The error message is specific to the default locale
* for this system. (The LDAP Java classes determine the default
* locale by calling the java.util.Locale.getDefault
* method and retrieve the error messages from the following file:
*
netscape/ldap/error/ErrorCodes_locale_name.props* where locale_name is the language and country (concatenated * and delimited by an underscore) of the default locale. For example: *
netscape/ldap/error/ErrorCodes_en_US.props* * @return the error message describing the error code for this * exception in the default locale. */ public String errorCodeToString() { return errorCodeToString(resultCode, m_locale); } /** * Returns the error message describing the error code for this * exception. The error message for the specified locale is retrieved * from the following file: *
netscape/ldap/error/ErrorCodes_locale_name.props* where locale_name is the language and country (concatenated * and delimited by an underscore) of the default locale. For example: *
netscape/ldap/error/ErrorCodes_en_US.props* * @param l the
java.util.Locale object representing the
* locale of the error message to retrieve
* @return the error message describing the current error code
* in the specified locale.
*/
public String errorCodeToString(Locale l) {
return errorCodeToString(resultCode, l);
}
/**
* Returns the error message describing the specified error code.
* The error message is specific to the default locale
* for this system. (The LDAP Java classes determine the default
* locale by calling the java.util.Locale.getDefault
* method and retrieve the error messages from the following file:
* netscape/ldap/error/ErrorCodes_locale_name.props* where locale_name is the language and country (concatenated * and delimited by an underscore) of the default locale. For example: *
netscape/ldap/error/ErrorCodes_en_US.props* * @param code the error code for which to get the * corresponding error message * @return error message describing the specified error code for * the default locale. */ public static String errorCodeToString(int code) { return errorCodeToString(code, Locale.getDefault()); } /** * Returns the error message describing the specified error code. * The error message for the specified locale is retrieved from * the following file: *
netscape/ldap/error/ErrorCodes_locale_name.props* where locale_name is the language and country (concatenated * and delimited by an underscore) of the default locale. For example: *
netscape/ldap/error/ErrorCodes_en_US.props* * @param code the error code for which to get the * corresponding error * @param locale the
java.util.Locale object representing the
* locale of the error message that you want to retrieve
* @return error message describing the specified error code for
* the specified locale.
*/
public synchronized static String errorCodeToString(int code, Locale locale) {
try {
String localeStr = locale.toString();
PropertyResourceBundle p =
(PropertyResourceBundle)cacheResource.get(localeStr);
if (p == null) {
p = LDAPResourceBundle.getBundle(baseName);
if (p != null)
cacheResource.put(localeStr, p);
}
if (p != null) {
return (String)p.handleGetObject(Integer.toString(code));
}
} catch (IOException e) {
System.out.println("Cannot open resource file for LDAPException "+
baseName);
}
return null;
}
}