001/* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt 010 * or http://forgerock.org/license/CDDLv1.0.html. 011 * See the License for the specific language governing permissions 012 * and limitations under the License. 013 * 014 * When distributing Covered Code, include this CDDL HEADER in each 015 * file and include the License file at legal-notices/CDDLv1_0.txt. 016 * If applicable, add the following below this CDDL HEADER, with the 017 * fields enclosed by brackets "[]" replaced with your own identifying 018 * information: 019 * Portions Copyright [yyyy] [name of copyright owner] 020 * 021 * CDDL HEADER END 022 * 023 * 024 * Copyright 2006-2008 Sun Microsystems, Inc. 025 * Portions Copyright 2013-2014 ForgeRock AS 026 */ 027package org.opends.server.types; 028 029import java.util.List; 030 031import org.forgerock.i18n.LocalizableMessage; 032import org.forgerock.opendj.ldap.ResultCode; 033 034/** 035 * This class defines an exception that may be thrown if a problem 036 * occurs in the Directory Server. 037 */ 038@org.opends.server.types.PublicAPI( 039 stability=org.opends.server.types.StabilityLevel.UNCOMMITTED, 040 mayInstantiate=true, 041 mayExtend=false, 042 mayInvoke=true) 043public final class DirectoryException 044 extends IdentifiedException 045{ 046 /** 047 * The serial version identifier required to satisfy the compiler 048 * because this class extends <CODE>java.lang.Exception</CODE>, 049 * which implements the <CODE>java.io.Serializable</CODE> interface. 050 * This value was generated using the <CODE>serialver</CODE> 051 * command-line utility included with the Java SDK. 052 */ 053 private static final long serialVersionUID = 2615453139798417203L; 054 055 056 057 /** The matched DN returned to the client for this directory exception. */ 058 private final DN matchedDN; 059 060 /** The set of referral URLs for this directory exception. */ 061 private final List<String> referralURLs; 062 063 /** 064 * The result code returned to the client for this directory exception. Note: 065 * for security considerations (information leak) this result code might not 066 * be the underlying reason why the directory server refused to execute the 067 * operation. 068 * 069 * @see #maskedResultCode for the underlying reason why the directory server 070 * refused to execute the operation 071 */ 072 private final ResultCode resultCode; 073 074 /** 075 * If set, this is the real message for this directory exception that cannot 076 * be returned to the client, but will be logged. 077 * 078 * @see #getMessage() for the message returned to the client 079 */ 080 private LocalizableMessage maskedMessage; 081 082 /** 083 * If set, this is the real result code for this directory exception that 084 * cannot be returned to the client, but will be logged. 085 * 086 * @see #resultCode for the reason code returned to the client 087 */ 088 private ResultCode maskedResultCode; 089 090 /** 091 * Creates a new directory exception with the provided information. 092 * 093 * @param resultCode The result code for this directory 094 * exception. 095 * @param errorMessage The error message for this directory 096 * exception. 097 */ 098 public DirectoryException(ResultCode resultCode, 099 LocalizableMessage errorMessage) 100 { 101 super(errorMessage); 102 103 104 this.resultCode = resultCode; 105 this.matchedDN = null; 106 this.referralURLs = null; 107 } 108 109 110 111 /** 112 * Creates a new directory exception with the provided information. 113 * 114 * @param resultCode The result code for this directory 115 * exception. 116 * @param errorMessage The error message for this directory 117 * exception. 118 * @param cause The exception that was caught to trigger 119 * this directory exception. 120 */ 121 public DirectoryException(ResultCode resultCode, 122 LocalizableMessage errorMessage, 123 Throwable cause) 124 { 125 super(errorMessage, cause); 126 127 128 this.resultCode = resultCode; 129 this.matchedDN = null; 130 this.referralURLs = null; 131 } 132 133 134 /** 135 * Creates a new directory exception with the provided information. 136 * 137 * @param resultCode The result code for this directory 138 * exception. 139 * @param cause The exception that was caught to trigger 140 * this directory exception. The message of 141 * this exception will be set to that of this 142 * parameter. 143 */ 144 public DirectoryException(ResultCode resultCode, 145 OpenDsException cause) 146 { 147 super(cause.getMessageObject(), cause); 148 149 150 this.resultCode = resultCode; 151 this.matchedDN = null; 152 this.referralURLs = null; 153 } 154 155 156 /** 157 * Creates a new directory exception with the provided information. 158 * 159 * @param resultCode The result code for this directory 160 * exception. 161 * @param errorMessage The error message for this directory 162 * exception. 163 * @param matchedDN The matched DN for this directory 164 * exception. 165 * @param cause The exception that was caught to trigger 166 * this directory exception. 167 */ 168 public DirectoryException(ResultCode resultCode, 169 LocalizableMessage errorMessage, 170 DN matchedDN, Throwable cause) 171 { 172 super(errorMessage, cause); 173 174 175 this.resultCode = resultCode; 176 this.matchedDN = matchedDN; 177 this.referralURLs = null; 178 } 179 180 181 182 /** 183 * Creates a new directory exception with the provided information. 184 * 185 * @param resultCode The result code for this directory 186 * exception. 187 * @param errorMessage The error message for this directory 188 * @param matchedDN The matched DN for this directory 189 * exception. 190 * @param referralURLs The set of referral URLs for this 191 * directory exception. 192 * @param cause The exception that was caught to trigger 193 * this directory exception. 194 */ 195 public DirectoryException(ResultCode resultCode, 196 LocalizableMessage errorMessage, 197 DN matchedDN, List<String> referralURLs, 198 Throwable cause) 199 { 200 super(errorMessage, cause); 201 202 203 this.resultCode = resultCode; 204 this.matchedDN = matchedDN; 205 this.referralURLs = referralURLs; 206 } 207 208 209 210 /** 211 * Retrieves the result code for this directory exception. 212 * 213 * @return The result code for this directory exception. 214 */ 215 public ResultCode getResultCode() 216 { 217 return resultCode; 218 } 219 220 221 222 /** 223 * Retrieves the matched DN for this directory exception. 224 * 225 * @return The matched DN for this directory exception, or 226 * <CODE>null</CODE> if there is none. 227 */ 228 public DN getMatchedDN() 229 { 230 return matchedDN; 231 } 232 233 234 235 /** 236 * Retrieves the set of referral URLs for this directory exception. 237 * 238 * @return The set of referral URLs for this directory exception, 239 * or <CODE>null</CODE> if there are none. 240 */ 241 public List<String> getReferralURLs() 242 { 243 return referralURLs; 244 } 245 246 /** 247 * Returns the real, masked message for this directory exception that cannot 248 * be returned to the client, but will be logged. 249 * 250 * @return the real, masked message 251 * @see #getMessage() for the message returned to the client 252 */ 253 public LocalizableMessage getMaskedMessage() 254 { 255 return maskedMessage; 256 } 257 258 /** 259 * Returns the real result code for this directory exception that cannot be 260 * returned to the client, but will be logged. 261 * 262 * @return the real, masked result code 263 * @see #getResultCode() for the result code returned to the client 264 */ 265 public ResultCode getMaskedResultCode() 266 { 267 return maskedResultCode; 268 } 269 270 /** 271 * Sets the real message for this directory exception that cannot be returned 272 * to the client, but will be logged. 273 * 274 * @param maskedMessage 275 * the real, masked message to set 276 */ 277 public void setMaskedMessage(LocalizableMessage maskedMessage) 278 { 279 this.maskedMessage = maskedMessage; 280 } 281 282 /** 283 * Sets the real result code for this directory exception that cannot be 284 * returned to the client, but will be logged. 285 * 286 * @param maskedResultCode 287 * the real, masked result code to set 288 */ 289 public void setMaskedResultCode(ResultCode maskedResultCode) 290 { 291 this.maskedResultCode = maskedResultCode; 292 } 293}