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