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}