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