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 }