001 /* 002 * Copyright 2007-2014 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005 /* 006 * Copyright (C) 2008-2014 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 * {@inheritDoc} 527 */ 528 @Override() 529 public void toString(final StringBuilder buffer) 530 { 531 buffer.append("LDAPException(resultCode="); 532 buffer.append(resultCode); 533 534 final String errorMessage = getMessage(); 535 if (errorMessage != null) 536 { 537 buffer.append(", errorMessage='"); 538 buffer.append(errorMessage); 539 buffer.append('\''); 540 } 541 542 if (matchedDN != null) 543 { 544 buffer.append(", matchedDN='"); 545 buffer.append(matchedDN); 546 buffer.append('\''); 547 } 548 549 if (diagnosticMessage != null) 550 { 551 buffer.append(", diagnosticMessage='"); 552 buffer.append(diagnosticMessage); 553 buffer.append('\''); 554 } 555 556 if (referralURLs.length > 0) 557 { 558 buffer.append(", referralURLs={"); 559 560 for (int i=0; i < referralURLs.length; i++) 561 { 562 if (i > 0) 563 { 564 buffer.append(", "); 565 } 566 567 buffer.append('\''); 568 buffer.append(referralURLs[i]); 569 buffer.append('\''); 570 } 571 572 buffer.append('}'); 573 } 574 575 if (responseControls.length > 0) 576 { 577 buffer.append(", responseControls={"); 578 579 for (int i=0; i < responseControls.length; i++) 580 { 581 if (i > 0) 582 { 583 buffer.append(", "); 584 } 585 586 buffer.append(responseControls[i]); 587 } 588 589 buffer.append('}'); 590 } 591 592 buffer.append(')'); 593 } 594 595 596 597 /** 598 * {@inheritDoc} 599 */ 600 @Override() 601 public final String getExceptionMessage() 602 { 603 return toString(); 604 } 605 }