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