001    /*
002     * Copyright 2009-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2009-2015 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     */
021    package com.unboundid.ldap.sdk.migrate.ldapjdk;
022    
023    
024    
025    import java.util.Locale;
026    
027    import com.unboundid.ldap.sdk.ResultCode;
028    import com.unboundid.util.NotExtensible;
029    import com.unboundid.util.NotMutable;
030    import com.unboundid.util.ThreadSafety;
031    import 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)
048    public 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    }