001    /*
002     * Copyright 2007-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2016 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;
022    
023    
024    
025    import com.unboundid.util.LDAPSDKException;
026    import com.unboundid.util.StaticUtils;
027    
028    
029    
030    /**
031     * This class defines an exception that can be thrown if a problem occurs while
032     * performing LDAP-related processing.  An LDAP exception can include all of
033     * the elements of an {@code LDAPResult}, so that all of the response elements
034     * will be available.
035     */
036    public class LDAPException
037           extends LDAPSDKException
038    {
039      /**
040       * The serial version UID for this serializable class.
041       */
042      private static final long serialVersionUID = -4257171063946350327L;
043    
044    
045    
046      /**
047       * An empty array that will be used when no controls were provided.
048       */
049      protected static final Control[] NO_CONTROLS = StaticUtils.NO_CONTROLS;
050    
051    
052    
053      /**
054       * An empty array that will be used when no referrals were provided.
055       */
056      protected static final String[] NO_REFERRALS = StaticUtils.NO_STRINGS;
057    
058    
059    
060      // The set of response controls for this LDAP exception.
061      private final Control[] responseControls;
062    
063      // The result code for this LDAP exception.
064      private final ResultCode resultCode;
065    
066      // The set of referral URLs for this LDAP exception.
067      private final String[] referralURLs;
068    
069      // The diagnostic message returned by the directory server.
070      private final String diagnosticMessage;
071    
072      // The matched DN for this LDAP exception.
073      private final String matchedDN;
074    
075    
076    
077      /**
078       * Creates a new LDAP exception with the provided result code.  A default
079       * message (based on the result code) will be used.
080       *
081       * @param  resultCode  The result code for this LDAP exception.
082       */
083      public LDAPException(final ResultCode resultCode)
084      {
085        super(resultCode.getName());
086    
087        this.resultCode = resultCode;
088    
089        matchedDN         = null;
090        diagnosticMessage = null;
091        referralURLs      = NO_REFERRALS;
092        responseControls  = NO_CONTROLS;
093      }
094    
095    
096    
097      /**
098       * Creates a new LDAP exception with the provided result code.  A default
099       * message (based on the result code) will be used.
100       *
101       * @param  resultCode  The result code for this LDAP exception.
102       * @param  cause       The underlying exception that triggered this exception.
103       */
104      public LDAPException(final ResultCode resultCode, final Throwable cause)
105      {
106        super(resultCode.getName(), cause);
107    
108        this.resultCode = resultCode;
109    
110        matchedDN         = null;
111        diagnosticMessage = null;
112        referralURLs      = NO_REFERRALS;
113        responseControls  = NO_CONTROLS;
114      }
115    
116    
117    
118      /**
119       * Creates a new LDAP exception with the provided result code and message.
120       *
121       * @param  resultCode    The result code for this LDAP exception.
122       * @param  errorMessage  The error message for this LDAP exception.
123       */
124      public LDAPException(final ResultCode resultCode, final String errorMessage)
125      {
126        super(errorMessage);
127    
128        this.resultCode = resultCode;
129    
130        matchedDN         = null;
131        diagnosticMessage = null;
132        referralURLs      = NO_REFERRALS;
133        responseControls  = NO_CONTROLS;
134      }
135    
136    
137    
138      /**
139       * Creates a new LDAP exception with the provided result code and message.
140       *
141       * @param  resultCode    The result code for this LDAP exception.
142       * @param  errorMessage  The error message for this LDAP exception.
143       * @param  cause         The underlying exception that triggered this
144       *                       exception.
145       */
146      public LDAPException(final ResultCode resultCode, final String errorMessage,
147                           final Throwable cause)
148      {
149        super(errorMessage, cause);
150    
151        this.resultCode = resultCode;
152    
153        matchedDN         = null;
154        diagnosticMessage = null;
155        referralURLs      = NO_REFERRALS;
156        responseControls  = NO_CONTROLS;
157      }
158    
159    
160    
161      /**
162       * Creates a new LDAP exception with the provided information.
163       *
164       * @param  resultCode    The result code for this LDAP exception.
165       * @param  errorMessage  The error message for this LDAP exception.
166       * @param  matchedDN     The matched DN for this LDAP exception.
167       * @param  referralURLs  The set of referral URLs for this LDAP exception.
168       */
169      public LDAPException(final ResultCode resultCode, final String errorMessage,
170                           final String matchedDN, final String[] referralURLs)
171      {
172        super(errorMessage);
173    
174        this.resultCode = resultCode;
175        this.matchedDN  = matchedDN;
176    
177        if (referralURLs == null)
178        {
179          this.referralURLs = NO_REFERRALS;
180        }
181        else
182        {
183          this.referralURLs = referralURLs;
184        }
185    
186        diagnosticMessage = null;
187        responseControls  = NO_CONTROLS;
188      }
189    
190    
191    
192      /**
193       * Creates a new LDAP exception with the provided information.
194       *
195       * @param  resultCode    The result code for this LDAP exception.
196       * @param  errorMessage  The error message for this LDAP exception.
197       * @param  matchedDN     The matched DN for this LDAP exception.
198       * @param  referralURLs  The set of referral URLs for this LDAP exception.
199       * @param  cause         The underlying exception that triggered this
200       *                       exception.
201       */
202      public LDAPException(final ResultCode resultCode, final String errorMessage,
203                           final String matchedDN, final String[] referralURLs,
204                           final Throwable cause)
205      {
206        super(errorMessage, cause);
207    
208        this.resultCode = resultCode;
209        this.matchedDN  = matchedDN;
210    
211        if (referralURLs == null)
212        {
213          this.referralURLs = NO_REFERRALS;
214        }
215        else
216        {
217          this.referralURLs = referralURLs;
218        }
219    
220        diagnosticMessage = null;
221        responseControls  = NO_CONTROLS;
222      }
223    
224    
225    
226      /**
227       * Creates a new LDAP exception with the provided information.
228       *
229       * @param  resultCode    The result code for this LDAP exception.
230       * @param  errorMessage  The error message for this LDAP exception.
231       * @param  matchedDN     The matched DN for this LDAP exception.
232       * @param  referralURLs  The set of referral URLs for this LDAP exception.
233       * @param  controls      The set of response controls for this LDAP exception.
234       */
235      public LDAPException(final ResultCode resultCode, final String errorMessage,
236                           final String matchedDN, final String[] referralURLs,
237                           final Control[] controls)
238      {
239        super(errorMessage);
240    
241        this.resultCode = resultCode;
242        this.matchedDN  = matchedDN;
243    
244        diagnosticMessage = null;
245    
246        if (referralURLs == null)
247        {
248          this.referralURLs = NO_REFERRALS;
249        }
250        else
251        {
252          this.referralURLs = referralURLs;
253        }
254    
255        if (controls == null)
256        {
257          responseControls = NO_CONTROLS;
258        }
259        else
260        {
261          responseControls = controls;
262        }
263      }
264    
265    
266    
267      /**
268       * Creates a new LDAP exception with the provided information.
269       *
270       * @param  resultCode    The result code for this LDAP exception.
271       * @param  errorMessage  The error message for this LDAP exception.
272       * @param  matchedDN     The matched DN for this LDAP exception.
273       * @param  referralURLs  The set of referral URLs for this LDAP exception.
274       * @param  controls      The set of response controls for this LDAP exception.
275       * @param  cause         The underlying exception that triggered this
276       *                       exception.
277       */
278      public LDAPException(final ResultCode resultCode, final String errorMessage,
279                           final String matchedDN, final String[] referralURLs,
280                           final Control[] controls, final Throwable cause)
281      {
282        super(errorMessage, cause);
283    
284        this.resultCode = resultCode;
285        this.matchedDN  = matchedDN;
286    
287        diagnosticMessage = null;
288    
289        if (referralURLs == null)
290        {
291          this.referralURLs = NO_REFERRALS;
292        }
293        else
294        {
295          this.referralURLs = referralURLs;
296        }
297    
298        if (controls == null)
299        {
300          responseControls = NO_CONTROLS;
301        }
302        else
303        {
304          responseControls = controls;
305        }
306      }
307    
308    
309    
310      /**
311       * Creates a new LDAP exception using the information contained in the
312       * provided LDAP result object.
313       *
314       * @param  ldapResult  The LDAP result object containing the information to
315       *                     use for this LDAP exception.
316       */
317      public LDAPException(final LDAPResult ldapResult)
318      {
319        super((ldapResult.getDiagnosticMessage() == null)
320              ? ldapResult.getResultCode().getName()
321              : ldapResult.getDiagnosticMessage());
322    
323        resultCode        = ldapResult.getResultCode();
324        matchedDN         = ldapResult.getMatchedDN();
325        diagnosticMessage = ldapResult.getDiagnosticMessage();
326        referralURLs      = ldapResult.getReferralURLs();
327        responseControls  = ldapResult.getResponseControls();
328      }
329    
330    
331    
332      /**
333       * Creates a new LDAP exception using the information contained in the
334       * provided LDAP result object.
335       *
336       * @param  ldapResult  The LDAP result object containing the information to
337       *                     use for this LDAP exception.
338       * @param  cause       The underlying exception that triggered this exception.
339       */
340      public LDAPException(final LDAPResult ldapResult, final Throwable cause)
341      {
342        super(((ldapResult.getDiagnosticMessage() == null)
343               ? ldapResult.getResultCode().getName()
344               : ldapResult.getDiagnosticMessage()),
345              cause);
346    
347        resultCode        = ldapResult.getResultCode();
348        matchedDN         = ldapResult.getMatchedDN();
349        diagnosticMessage = ldapResult.getDiagnosticMessage();
350        referralURLs      = ldapResult.getReferralURLs();
351        responseControls  = ldapResult.getResponseControls();
352      }
353    
354    
355    
356      /**
357       * Creates a new LDAP exception using the information contained in the
358       * provided LDAP exception.
359       *
360       * @param  e  The LDAP exception to use to create this exception.
361       */
362      public LDAPException(final LDAPException e)
363      {
364        super(e.getMessage(), e.getCause());
365    
366        resultCode        = e.getResultCode();
367        matchedDN         = e.getMatchedDN();
368        diagnosticMessage = e.getDiagnosticMessage();
369        referralURLs      = e.getReferralURLs();
370        responseControls  = e.getResponseControls();
371      }
372    
373    
374    
375      /**
376       * Retrieves the result code for this LDAP exception.
377       *
378       * @return  The result code for this LDAP exception.
379       */
380      public final ResultCode getResultCode()
381      {
382        return resultCode;
383      }
384    
385    
386    
387      /**
388       * Retrieves the matched DN for this LDAP exception.
389       *
390       * @return  The matched DN for this LDAP exception, or {@code null} if there
391       *          is none.
392       */
393      public final String getMatchedDN()
394      {
395        return matchedDN;
396      }
397    
398    
399    
400      /**
401       * Retrieves the diagnostic message returned by the directory server.
402       *
403       * @return  The diagnostic message returned by the directory server, or
404       *          {@code null} if there is none.
405       */
406      public final String getDiagnosticMessage()
407      {
408        return diagnosticMessage;
409      }
410    
411    
412    
413      /**
414       * Retrieves the set of referral URLs for this LDAP exception.
415       *
416       * @return  The set of referral URLs for this LDAP exception, or an empty
417       *          array if there are none.
418       */
419      public final String[] getReferralURLs()
420      {
421        return referralURLs;
422      }
423    
424    
425    
426      /**
427       * Indicates whether this result contains at least one control.
428       *
429       * @return  {@code true} if this result contains at least one control, or
430       *          {@code false} if not.
431       */
432      public final boolean hasResponseControl()
433      {
434        return (responseControls.length > 0);
435      }
436    
437    
438    
439      /**
440       * Indicates whether this result contains at least one control with the
441       * specified OID.
442       *
443       * @param  oid  The object identifier for which to make the determination.  It
444       *              must not be {@code null}.
445       *
446       * @return  {@code true} if this result contains at least one control with
447       *          the specified OID, or {@code false} if not.
448       */
449      public final boolean hasResponseControl(final String oid)
450      {
451        for (final Control c : responseControls)
452        {
453          if (c.getOID().equals(oid))
454          {
455            return true;
456          }
457        }
458    
459        return false;
460      }
461    
462    
463    
464      /**
465       * Retrieves the set of response controls for this LDAP exception.
466       * Individual response controls of a specific type may be retrieved and
467       * decoded using the {@code get} method in the response control class, using
468       * the {@code toLDAPResult()} method to convert this exception to an
469       * {@code LDAPResult}.
470       *
471       * @return  The set of response controls for this LDAP exception, or an empty
472       *          array if there are none.
473       */
474      public final Control[] getResponseControls()
475      {
476        return responseControls;
477      }
478    
479    
480    
481      /**
482       * Retrieves the response control with the specified OID.
483       *
484       * @param  oid  The OID of the control to retrieve.
485       *
486       * @return  The response control with the specified OID, or {@code null} if
487       *          there is no such control.
488       */
489      public final Control getResponseControl(final String oid)
490      {
491        for (final Control c : responseControls)
492        {
493          if (c.getOID().equals(oid))
494          {
495            return c;
496          }
497        }
498    
499        return null;
500      }
501    
502    
503    
504      /**
505       * Creates a new {@code LDAPResult} object from this exception.
506       *
507       * @return  The {@code LDAPResult} object created from this exception.
508       */
509      public LDAPResult toLDAPResult()
510      {
511        if ((diagnosticMessage == null) && (getMessage() != null))
512        {
513          return new LDAPResult(-1, resultCode, getMessage(), matchedDN,
514               referralURLs, responseControls);
515        }
516        else
517        {
518          return new LDAPResult(-1, resultCode, diagnosticMessage, matchedDN,
519               referralURLs, responseControls);
520        }
521      }
522    
523    
524    
525      /**
526       * Retrieves a string representation of this LDAP result, consisting of
527       * the result code, diagnostic message (if present), matched DN (if present),
528       * and referral URLs (if present).
529       *
530       * @return  A string representation of this LDAP result.
531       */
532      public String getResultString()
533      {
534        final StringBuilder buffer = new StringBuilder();
535        buffer.append("result code='");
536        buffer.append(resultCode);
537        buffer.append('\'');
538    
539        if ((diagnosticMessage != null) && (diagnosticMessage.length() > 0))
540        {
541          buffer.append(" diagnostic message='");
542          buffer.append(diagnosticMessage);
543          buffer.append('\'');
544        }
545    
546        if ((matchedDN != null) && (matchedDN.length() > 0))
547        {
548          buffer.append("  matched DN='");
549          buffer.append(matchedDN);
550          buffer.append('\'');
551        }
552    
553        if ((referralURLs != null) && (referralURLs.length > 0))
554        {
555          buffer.append("  referral URLs={");
556    
557          for (int i=0; i < referralURLs.length; i++)
558          {
559            if (i > 0)
560            {
561              buffer.append(", ");
562            }
563    
564            buffer.append('\'');
565            buffer.append(referralURLs[i]);
566            buffer.append('\'');
567          }
568    
569          buffer.append('}');
570        }
571    
572        return buffer.toString();
573      }
574    
575    
576    
577      /**
578       * {@inheritDoc}
579       */
580      @Override()
581      public void toString(final StringBuilder buffer)
582      {
583        buffer.append("LDAPException(resultCode=");
584        buffer.append(resultCode);
585    
586        final String errorMessage = getMessage();
587        if (errorMessage != null)
588        {
589          buffer.append(", errorMessage='");
590          buffer.append(errorMessage);
591          buffer.append('\'');
592        }
593    
594        if (matchedDN != null)
595        {
596          buffer.append(", matchedDN='");
597          buffer.append(matchedDN);
598          buffer.append('\'');
599        }
600    
601        if (diagnosticMessage != null)
602        {
603          buffer.append(", diagnosticMessage='");
604          buffer.append(diagnosticMessage);
605          buffer.append('\'');
606        }
607    
608        if (referralURLs.length > 0)
609        {
610          buffer.append(", referralURLs={");
611    
612          for (int i=0; i < referralURLs.length; i++)
613          {
614            if (i > 0)
615            {
616              buffer.append(", ");
617            }
618    
619            buffer.append('\'');
620            buffer.append(referralURLs[i]);
621            buffer.append('\'');
622          }
623    
624          buffer.append('}');
625        }
626    
627        if (responseControls.length > 0)
628        {
629          buffer.append(", responseControls={");
630    
631          for (int i=0; i < responseControls.length; i++)
632          {
633            if (i > 0)
634            {
635              buffer.append(", ");
636            }
637    
638            buffer.append(responseControls[i]);
639          }
640    
641          buffer.append('}');
642        }
643    
644        buffer.append(')');
645      }
646    
647    
648    
649      /**
650       * {@inheritDoc}
651       */
652      @Override()
653      public final String getExceptionMessage()
654      {
655        return toString();
656      }
657    }