001/*
002 * Copyright 2009-2020 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2009-2020 Ping Identity Corporation
007 *
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *    http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020/*
021 * Copyright (C) 2009-2020 Ping Identity Corporation
022 *
023 * This program is free software; you can redistribute it and/or modify
024 * it under the terms of the GNU General Public License (GPLv2 only)
025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
026 * as published by the Free Software Foundation.
027 *
028 * This program is distributed in the hope that it will be useful,
029 * but WITHOUT ANY WARRANTY; without even the implied warranty of
030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
031 * GNU General Public License for more details.
032 *
033 * You should have received a copy of the GNU General Public License
034 * along with this program; if not, see <http://www.gnu.org/licenses>.
035 */
036package com.unboundid.ldap.sdk.migrate.ldapjdk;
037
038
039
040import java.util.Locale;
041
042import com.unboundid.ldap.sdk.ResultCode;
043import com.unboundid.util.NotExtensible;
044import com.unboundid.util.NotMutable;
045import com.unboundid.util.ThreadSafety;
046import com.unboundid.util.ThreadSafetyLevel;
047
048
049
050/**
051 * This class defines an exception that may be thrown if an error occurs during
052 * LDAP-related processing.
053 * <BR><BR>
054 * This class is primarily intended to be used in the process of updating
055 * applications which use the Netscape Directory SDK for Java to switch to or
056 * coexist with the UnboundID LDAP SDK for Java.  For applications not written
057 * using the Netscape Directory SDK for Java, the
058 * {@link com.unboundid.ldap.sdk.LDAPException} class should be used instead.
059 */
060@NotExtensible()
061@NotMutable()
062@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
063public class LDAPException
064       extends Exception
065{
066  /**
067   * The int value for the SUCCESS result code.
068   */
069  public static final int SUCCESS = ResultCode.SUCCESS_INT_VALUE;
070
071
072
073  /**
074   * The int value for the OPERATION_ERROR result code.
075   */
076  public static final int OPERATION_ERROR =
077       ResultCode.OPERATIONS_ERROR_INT_VALUE;
078
079
080
081  /**
082   * The int value for the PROTOCOL_ERROR result code.
083   */
084  public static final int PROTOCOL_ERROR = ResultCode.PROTOCOL_ERROR_INT_VALUE;
085
086
087
088  /**
089   * The int value for the TIME_LIMIT_EXCEEDED result code.
090   */
091  public static final int TIME_LIMIT_EXCEEDED =
092       ResultCode.TIME_LIMIT_EXCEEDED_INT_VALUE;
093
094
095
096  /**
097   * The int value for the SIZE_LIMIT_EXCEEDED result code.
098   */
099  public static final int SIZE_LIMIT_EXCEEDED =
100       ResultCode.SIZE_LIMIT_EXCEEDED_INT_VALUE;
101
102
103
104  /**
105   * The int value for the COMPARE_FALSE result code.
106   */
107  public static final int COMPARE_FALSE = ResultCode.COMPARE_FALSE_INT_VALUE;
108
109
110
111  /**
112   * The int value for the COMPARE_TRUE result code.
113   */
114  public static final int COMPARE_TRUE = ResultCode.COMPARE_TRUE_INT_VALUE;
115
116
117
118  /**
119   * The int value for the AUTH_METHOD_NOT_SUPPORTED result code.
120   */
121  public static final int AUTH_METHOD_NOT_SUPPORTED =
122       ResultCode.AUTH_METHOD_NOT_SUPPORTED_INT_VALUE;
123
124
125
126  /**
127   * The int value for the STRONG_AUTH_REQUIRED result code.
128   */
129  public static final int STRONG_AUTH_REQUIRED =
130       ResultCode.STRONG_AUTH_REQUIRED_INT_VALUE;
131
132
133
134  /**
135   * The int value for the LDAP_PARTIAL_RESULTS result code.
136   */
137  public static final int LDAP_PARTIAL_RESULTS = 9;
138
139
140
141  /**
142   * The int value for the REFERRAL result code.
143   */
144  public static final int REFERRAL = ResultCode.REFERRAL_INT_VALUE;
145
146
147
148  /**
149   * The int value for the ADMIN_LIMIT_EXCEEDED result code.
150   */
151  public static final int ADMIN_LIMIT_EXCEEDED =
152       ResultCode.ADMIN_LIMIT_EXCEEDED_INT_VALUE;
153
154
155
156  /**
157   * The int value for the UNAVAILABLE_CRITICAL_EXTENSION result code.
158   */
159  public static final int UNAVAILABLE_CRITICAL_EXTENSION =
160       ResultCode.UNAVAILABLE_CRITICAL_EXTENSION_INT_VALUE;
161
162
163
164  /**
165   * The int value for the CONFIDENTIALITY_REQUIRED result code.
166   */
167  public static final int CONFIDENTIALITY_REQUIRED =
168       ResultCode.CONFIDENTIALITY_REQUIRED_INT_VALUE;
169
170
171
172  /**
173   * The int value for the SASL_BIND_IN_PROGRESS result code.
174   */
175  public static final int SASL_BIND_IN_PROGRESS =
176       ResultCode.SASL_BIND_IN_PROGRESS_INT_VALUE;
177
178
179
180  /**
181   * The int value for the NO_SUCH_ATTRIBUTE result code.
182   */
183  public static final int NO_SUCH_ATTRIBUTE =
184       ResultCode.NO_SUCH_ATTRIBUTE_INT_VALUE;
185
186
187
188  /**
189   * The int value for the UNDEFINED_ATTRIBUTE_TYPE result code.
190   */
191  public static final int UNDEFINED_ATTRIBUTE_TYPE =
192       ResultCode.UNDEFINED_ATTRIBUTE_TYPE_INT_VALUE;
193
194
195
196  /**
197   * The int value for the INAPPROPRIATE_MATCHING result code.
198   */
199  public static final int INAPPROPRIATE_MATCHING =
200       ResultCode.INAPPROPRIATE_MATCHING_INT_VALUE;
201
202
203
204  /**
205   * The int value for the CONSTRAINT_VIOLATION result code.
206   */
207  public static final int CONSTRAINT_VIOLATION =
208       ResultCode.CONSTRAINT_VIOLATION_INT_VALUE;
209
210
211
212  /**
213   * The int value for the ATTRIBUTE_OR_VALUE_EXISTS result code.
214   */
215  public static final int ATTRIBUTE_OR_VALUE_EXISTS =
216       ResultCode.ATTRIBUTE_OR_VALUE_EXISTS_INT_VALUE;
217
218
219
220  /**
221   * The int value for the INVALID_ATTRIBUTE_SYNTAX result code.
222   */
223  public static final int INVALID_ATTRIBUTE_SYNTAX =
224       ResultCode.INVALID_ATTRIBUTE_SYNTAX_INT_VALUE;
225
226
227
228  /**
229   * The int value for the NO_SUCH_OBJECT result code.
230   */
231  public static final int NO_SUCH_OBJECT = ResultCode.NO_SUCH_OBJECT_INT_VALUE;
232
233
234
235  /**
236   * The int value for the ALIAS_PROBLEM result code.
237   */
238  public static final int ALIAS_PROBLEM = ResultCode.ALIAS_PROBLEM_INT_VALUE;
239
240
241
242  /**
243   * The int value for the INVALID_DN_SYNTAX result code.
244   */
245  public static final int INVALID_DN_SYNTAX =
246       ResultCode.INVALID_DN_SYNTAX_INT_VALUE;
247
248
249
250  /**
251   * The int value for the IS_LEAF result code.
252   */
253  public static final int IS_LEAF = 35;
254
255
256
257  /**
258   * The int value for the ALIAS_DEREFERENCING_PROBLEM result code.
259   */
260  public static final int ALIAS_DEREFERENCING_PROBLEM =
261       ResultCode.ALIAS_DEREFERENCING_PROBLEM_INT_VALUE;
262
263
264
265  /**
266   * The int value for the INAPPROPRIATE_AUTHENTICATION result code.
267   */
268  public static final int INAPPROPRIATE_AUTHENTICATION =
269       ResultCode.INAPPROPRIATE_AUTHENTICATION_INT_VALUE;
270
271
272
273  /**
274   * The int value for the INVALID_CREDENTIALS result code.
275   */
276  public static final int INVALID_CREDENTIALS =
277       ResultCode.INVALID_CREDENTIALS_INT_VALUE;
278
279
280
281  /**
282   * The int value for the INSUFFICIENT_ACCESS_RIGHTS result code.
283   */
284  public static final int INSUFFICIENT_ACCESS_RIGHTS =
285       ResultCode.INSUFFICIENT_ACCESS_RIGHTS_INT_VALUE;
286
287
288
289  /**
290   * The int value for the BUSY result code.
291   */
292  public static final int BUSY = ResultCode.BUSY_INT_VALUE;
293
294
295
296  /**
297   * The int value for the UNAVAILABLE result code.
298   */
299  public static final int UNAVAILABLE = ResultCode.UNAVAILABLE_INT_VALUE;
300
301
302
303  /**
304   * The int value for the UNWILLING_TO_PERFORM result code.
305   */
306  public static final int UNWILLING_TO_PERFORM =
307       ResultCode.UNWILLING_TO_PERFORM_INT_VALUE;
308
309
310
311  /**
312   * The int value for the LOOP_DETECT result code.
313   */
314  public static final int LOOP_DETECTED = ResultCode.LOOP_DETECT_INT_VALUE;
315
316
317
318  /**
319   * The int value for the SORT_CONTROL_MISSING result code.
320   */
321  public static final int SORT_CONTROL_MISSING =
322       ResultCode.SORT_CONTROL_MISSING_INT_VALUE;
323
324
325
326  /**
327   * The int value for the INDEX_RANGE_ERROR result code.
328   */
329  public static final int INDEX_RANGE_ERROR =
330       ResultCode.OFFSET_RANGE_ERROR_INT_VALUE;
331
332
333
334  /**
335   * The int value for the NAMING_VIOLATION result code.
336   */
337  public static final int NAMING_VIOLATION =
338       ResultCode.NAMING_VIOLATION_INT_VALUE;
339
340
341
342  /**
343   * The int value for the OBJECT_CLASS_VIOLATION result code.
344   */
345  public static final int OBJECT_CLASS_VIOLATION =
346       ResultCode.OBJECT_CLASS_VIOLATION_INT_VALUE;
347
348
349
350  /**
351   * The int value for the NOT_ALLOWED_ON_NONLEAF result code.
352   */
353  public static final int NOT_ALLOWED_ON_NONLEAF =
354       ResultCode.NOT_ALLOWED_ON_NONLEAF_INT_VALUE;
355
356
357
358  /**
359   * The int value for the NOT_ALLOWED_ON_RDN result code.
360   */
361  public static final int NOT_ALLOWED_ON_RDN =
362       ResultCode.NOT_ALLOWED_ON_RDN_INT_VALUE;
363
364
365
366  /**
367   * The int value for the ENTRY_ALREADY_EXISTS result code.
368   */
369  public static final int ENTRY_ALREADY_EXISTS =
370       ResultCode.ENTRY_ALREADY_EXISTS_INT_VALUE;
371
372
373
374  /**
375   * The int value for the OBJECT_CLASS_MODS_PROHIBITED result code.
376   */
377  public static final int OBJECT_CLASS_MODS_PROHIBITED =
378       ResultCode.OBJECT_CLASS_MODS_PROHIBITED_INT_VALUE;
379
380
381
382  /**
383   * The int value for the AFFECTS_MULTIPLE_DSAS result code.
384   */
385  public static final int AFFECTS_MULTIPLE_DSAS =
386       ResultCode.AFFECTS_MULTIPLE_DSAS_INT_VALUE;
387
388
389
390  /**
391   * The int value for the OTHER result code.
392   */
393  public static final int OTHER = ResultCode.OTHER_INT_VALUE;
394
395
396
397  /**
398   * The int value for the SERVER_DOWN result code.
399   */
400  public static final int SERVER_DOWN = ResultCode.SERVER_DOWN_INT_VALUE;
401
402
403
404  /**
405   * The int value for the LDAP_TIMEOUT result code.
406   */
407  public static final int LDAP_TIMEOUT = ResultCode.TIMEOUT_INT_VALUE;
408
409
410
411  /**
412   * The int value for the PARAM_ERROR result code.
413   */
414  public static final int PARAM_ERROR = ResultCode.PARAM_ERROR_INT_VALUE;
415
416
417
418  /**
419   * The int value for the CONNECT_ERROR result code.
420   */
421  public static final int CONNECT_ERROR = ResultCode.CONNECT_ERROR_INT_VALUE;
422
423
424
425  /**
426   * The int value for the LDAP_NOT_SUPPORTED result code.
427   */
428  public static final int LDAP_NOT_SUPPORTED =
429       ResultCode.NOT_SUPPORTED_INT_VALUE;
430
431
432
433  /**
434   * The int value for the CONTROL_NOT_FOUND result code.
435   */
436  public static final int CONTROL_NOT_FOUND =
437       ResultCode.CONTROL_NOT_FOUND_INT_VALUE;
438
439
440
441  /**
442   * The int value for the NO_RESULTS_RETURNED result code.
443   */
444  public static final int NO_RESULTS_RETURNED =
445       ResultCode.NO_RESULTS_RETURNED_INT_VALUE;
446
447
448
449  /**
450   * The int value for the MORE_RESULTS_TO_RETURN result code.
451   */
452  public static final int MORE_RESULTS_TO_RETURN =
453       ResultCode.MORE_RESULTS_TO_RETURN_INT_VALUE;
454
455
456
457  /**
458   * The int value for the CLIENT_LOOP result code.
459   */
460  public static final int CLIENT_LOOP =
461       ResultCode.CLIENT_LOOP_INT_VALUE;
462
463
464
465  /**
466   * The int value for the REFERRAL_LIMIT_EXCEEDED result code.
467   */
468  public static final int REFERRAL_LIMIT_EXCEEDED =
469       ResultCode.REFERRAL_LIMIT_EXCEEDED_INT_VALUE;
470
471
472
473  /**
474   * The serial version UID for this serializable class.
475   */
476  private static final long serialVersionUID = 1942111440459840394L;
477
478
479
480  // The result code for this LDAP exception.
481  private final int resultCode;
482
483  // The matched DN for this LDAP exception.
484  private final String matchedDN;
485
486  // The error message for this LDAP exception.
487  private final String serverErrorMessage;
488
489
490
491  /**
492   * Creates a new LDAP exception with no information.
493   */
494  public LDAPException()
495  {
496    this(null, OTHER, null, null);
497  }
498
499
500
501  /**
502   * Creates a new LDAP exception with the provided information.
503   *
504   * @param  message  The message for this exception, if available.
505   */
506  public LDAPException(final String message)
507  {
508    this(message, OTHER, null, null);
509  }
510
511
512
513  /**
514   * Creates a new LDAP exception with the provided information.
515   *
516   * @param  message     The message for this exception, if available.
517   * @param  resultCode  The result code for this exception.
518   */
519  public LDAPException(final String message, final int resultCode)
520  {
521    this(message, resultCode, null, null);
522  }
523
524
525
526  /**
527   * Creates a new LDAP exception with the provided information.
528   *
529   * @param  message             The message for this exception, if available.
530   * @param  resultCode          The result code for this exception.
531   * @param  serverErrorMessage  The error message received from the server, if
532   *                             available.
533   */
534  public LDAPException(final String message, final int resultCode,
535                       final String serverErrorMessage)
536  {
537    this(message, resultCode, serverErrorMessage, null);
538  }
539
540
541
542  /**
543   * Creates a new LDAP exception with the provided information.
544   *
545   * @param  message             The message for this exception, if available.
546   * @param  resultCode          The result code for this exception.
547   * @param  serverErrorMessage  The error message received from the server, if
548   *                             available.
549   * @param  matchedDN           The matched DN for this exception, if
550   *                             available.
551   */
552  public LDAPException(final String message, final int resultCode,
553                       final String serverErrorMessage, final String matchedDN)
554  {
555    super(getMessage(message, serverErrorMessage, resultCode));
556
557    this.resultCode         = resultCode;
558    this.serverErrorMessage = serverErrorMessage;
559    this.matchedDN          = matchedDN;
560  }
561
562
563
564  /**
565   * Creates a new LDAP exception from the provided
566   * {@link com.unboundid.ldap.sdk.LDAPException} object.
567   *
568   * @param  ldapException  The {@code LDAPException} object to use to create
569   *                        this LDAP exception.
570   */
571  public LDAPException(final com.unboundid.ldap.sdk.LDAPException ldapException)
572  {
573    this(ldapException.getMessage(), ldapException.getResultCode().intValue(),
574         ldapException.getMessage(), ldapException.getMatchedDN());
575  }
576
577
578
579  /**
580   * Determines the appropriate message to use for this LDAP exception.
581   *
582   * @param  message             The message for this exception, if available.
583   * @param  serverErrorMessage  The error message received from the server, if
584   *                             available.
585   * @param  resultCode          The result code for this exception.
586   *
587   * @return  The appropriate message to use for this LDAP exception.
588   */
589  private static String getMessage(final String message,
590                                   final String serverErrorMessage,
591                                   final int resultCode)
592  {
593    if ((message != null) && (! message.isEmpty()))
594    {
595      return message;
596    }
597
598    if ((serverErrorMessage != null) && (! serverErrorMessage.isEmpty()))
599    {
600      return serverErrorMessage;
601    }
602
603    return ResultCode.valueOf(resultCode).getName();
604  }
605
606
607
608  /**
609   * Retrieves the result code for this LDAP exception.
610   *
611   * @return  The result code for this LDAP exception.
612   */
613  public int getLDAPResultCode()
614  {
615    return resultCode;
616  }
617
618
619
620  /**
621   * Retrieves the error message received from the server, if available.
622   *
623   * @return  The error message received from the server, or {@code null} if
624   *          none is available.
625   */
626  public String getLDAPErrorMessage()
627  {
628    return serverErrorMessage;
629  }
630
631
632
633  /**
634   * Retrieves the matched DN for this LDAP exception, if available.
635   *
636   * @return  The matched DN for this LDAP exception, or {@code null} if none is
637   *          available.
638   */
639  public String getMatchedDN()
640  {
641    return matchedDN;
642  }
643
644
645
646  /**
647   * Retrieves an {@link com.unboundid.ldap.sdk.LDAPException} object that is
648   * the equivalent of this LDAP exception.
649   *
650   * @return  The {@code LDAPException} object that is the equivalent of this
651   *          LDAP exception.
652   */
653  public final com.unboundid.ldap.sdk.LDAPException toLDAPException()
654  {
655    return new com.unboundid.ldap.sdk.LDAPException(
656         ResultCode.valueOf(resultCode), getMessage(), matchedDN, null);
657  }
658
659
660
661  /**
662   * Retrieves a string representation of the result code for this LDAP
663   * exception.
664   *
665   * @return  A string representation of the result code for this LDAP
666   *          exception.
667   */
668  public String errorCodeToString()
669  {
670    return ResultCode.valueOf(resultCode).getName();
671  }
672
673
674
675  /**
676   * Retrieves a string representation of the result code for this LDAP
677   * exception.
678   *
679   * @param  l  The locale for the string representation.
680   *
681   * @return  A string representation of the result code for this LDAP
682   *          exception.
683   */
684  public String errorCodeToString(final Locale l)
685  {
686    return ResultCode.valueOf(resultCode).getName();
687  }
688
689
690
691  /**
692   * Retrieves a string representation of the result code for this LDAP
693   * exception.
694   *
695   * @param  code  The result code for which to retrieve the corresponding
696   *               message.
697   *
698   * @return  A string representation of the result code for this LDAP
699   *          exception.
700   */
701  public static String errorCodeToString(final int code)
702  {
703    return ResultCode.valueOf(code).getName();
704  }
705
706
707
708  /**
709   * Retrieves a string representation of the result code for this LDAP
710   * exception.
711   *
712   * @param  code    The result code for which to retrieve the corresponding
713   *                 message.
714   * @param  locale  The locale for the string representation.
715   *
716   * @return  A string representation of the result code for this LDAP
717   *          exception.
718   */
719  public static String errorCodeToString(final int code, final Locale locale)
720  {
721    return ResultCode.valueOf(code).getName();
722  }
723
724
725
726  /**
727   * Retrieves a string representation of this LDAP exception.
728   *
729   * @return  A string representation of this LDAP exception.
730   */
731  @Override()
732  public String toString()
733  {
734    return toLDAPException().toString();
735  }
736}