View Javadoc
1   /*
2    * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.naming;
27  
28  /**
29    * This is the superclass of all exceptions thrown by
30    * operations in the Context and DirContext interfaces.
31    * The nature of the failure is described by the name of the subclass.
32    * This exception captures the information pinpointing where the operation
33    * failed, such as where resolution last proceeded to.
34    * <ul>
35    * <li> Resolved Name. Portion of name that has been resolved.
36    * <li> Resolved Object. Object to which resolution of name proceeded.
37    * <li> Remaining Name. Portion of name that has not been resolved.
38    * <li> Explanation. Detail explaining why name resolution failed.
39    * <li> Root Exception. The exception that caused this naming exception
40    *                     to be thrown.
41    *</ul>
42    * null is an acceptable value for any of these fields. When null,
43    * it means that no such information has been recorded for that field.
44    *<p>
45    * A NamingException instance is not synchronized against concurrent
46    * multithreaded access. Multiple threads trying to access and modify
47    * a single NamingException instance should lock the object.
48    *<p>
49    * This exception has been retrofitted to conform to
50    * the general purpose exception-chaining mechanism.  The
51    * <i>root exception</i> (or <i>root cause</i>) is the same object as the
52    * <i>cause</i> returned by the {@link Throwable#getCause()} method.
53    *
54    * @author Rosanna Lee
55    * @author Scott Seligman
56    * @since 1.3
57    */
58  
59  
60  public class NamingException extends Exception {
61      /**
62       * Contains the part of the name that has been successfully resolved.
63       * It is a composite name and can be null.
64       * This field is initialized by the constructors.
65       * You should access and manipulate this field
66       * through its get and set methods.
67       * @serial
68       * @see #getResolvedName
69       * @see #setResolvedName
70       */
71      protected Name resolvedName;
72      /**
73        * Contains the object to which resolution of the part of the name was
74        * successful. Can be null.
75        * This field is initialized by the constructors.
76        * You should access and manipulate this field
77        * through its get and set methods.
78        * @serial
79        * @see #getResolvedObj
80        * @see #setResolvedObj
81        */
82      protected Object resolvedObj;
83      /**
84       * Contains the remaining name that has not been resolved yet.
85       * It is a composite name and can be null.
86       * This field is initialized by the constructors.
87       * You should access and manipulate this field
88       * through its get, set, "append" methods.
89       * @serial
90       * @see #getRemainingName
91       * @see #setRemainingName
92       * @see #appendRemainingName
93       * @see #appendRemainingComponent
94       */
95      protected Name remainingName;
96  
97      /**
98       * Contains the original exception that caused this NamingException to
99       * be thrown. This field is set if there is additional
100      * information that could be obtained from the original
101      * exception, or if the original exception could not be
102      * mapped to a subclass of NamingException.
103      * Can be null.
104      *<p>
105      * This field predates the general-purpose exception chaining facility.
106      * The {@link #initCause(Throwable)} and {@link #getCause()} methods
107      * are now the preferred means of accessing this information.
108      *
109      * @serial
110      * @see #getRootCause
111      * @see #setRootCause(Throwable)
112      * @see #initCause(Throwable)
113      * @see #getCause
114      */
115     protected Throwable rootException = null;
116 
117     /**
118      * Constructs a new NamingException with an explanation.
119      * All unspecified fields are set to null.
120      *
121      * @param   explanation     A possibly null string containing
122      *                          additional detail about this exception.
123      * @see java.lang.Throwable#getMessage
124      */
125     public NamingException(String explanation) {
126         super(explanation);
127         resolvedName = remainingName = null;
128         resolvedObj = null;
129     }
130 
131     /**
132       * Constructs a new NamingException.
133       * All fields are set to null.
134       */
135     public NamingException() {
136         super();
137         resolvedName = remainingName = null;
138         resolvedObj = null;
139     }
140 
141     /**
142      * Retrieves the leading portion of the name that was resolved
143      * successfully.
144      *
145      * @return The part of the name that was resolved successfully.
146      *          It is a composite name. It can be null, which means
147      *          the resolved name field has not been set.
148      * @see #getResolvedObj
149      * @see #setResolvedName
150      */
151     public Name getResolvedName() {
152         return resolvedName;
153     }
154 
155     /**
156      * Retrieves the remaining unresolved portion of the name.
157      * @return The part of the name that has not been resolved.
158      *          It is a composite name. It can be null, which means
159      *          the remaining name field has not been set.
160      * @see #setRemainingName
161      * @see #appendRemainingName
162      * @see #appendRemainingComponent
163      */
164     public Name getRemainingName() {
165         return remainingName;
166     }
167 
168     /**
169      * Retrieves the object to which resolution was successful.
170      * This is the object to which the resolved name is bound.
171      *
172      * @return The possibly null object that was resolved so far.
173      *  null means that the resolved object field has not been set.
174      * @see #getResolvedName
175      * @see #setResolvedObj
176      */
177     public Object getResolvedObj() {
178         return resolvedObj;
179     }
180 
181     /**
182       * Retrieves the explanation associated with this exception.
183       *
184       * @return The possibly null detail string explaining more
185       *         about this exception. If null, it means there is no
186       *         detail message for this exception.
187       *
188       * @see java.lang.Throwable#getMessage
189       */
190     public String getExplanation() {
191         return getMessage();
192     }
193 
194     /**
195      * Sets the resolved name field of this exception.
196      *<p>
197      * <tt>name</tt> is a composite name. If the intent is to set
198      * this field using a compound name or string, you must
199      * "stringify" the compound name, and create a composite
200      * name with a single component using the string. You can then
201      * invoke this method using the resulting composite name.
202      *<p>
203      * A copy of <code>name</code> is made and stored.
204      * Subsequent changes to <code>name</code> does not
205      * affect the copy in this NamingException and vice versa.
206      *
207      * @param name The possibly null name to set resolved name to.
208      *          If null, it sets the resolved name field to null.
209      * @see #getResolvedName
210      */
211     public void setResolvedName(Name name) {
212         if (name != null)
213             resolvedName = (Name)(name.clone());
214         else
215             resolvedName = null;
216     }
217 
218     /**
219      * Sets the remaining name field of this exception.
220      *<p>
221      * <tt>name</tt> is a composite name. If the intent is to set
222      * this field using a compound name or string, you must
223      * "stringify" the compound name, and create a composite
224      * name with a single component using the string. You can then
225      * invoke this method using the resulting composite name.
226      *<p>
227      * A copy of <code>name</code> is made and stored.
228      * Subsequent changes to <code>name</code> does not
229      * affect the copy in this NamingException and vice versa.
230      * @param name The possibly null name to set remaining name to.
231      *          If null, it sets the remaining name field to null.
232      * @see #getRemainingName
233      * @see #appendRemainingName
234      * @see #appendRemainingComponent
235      */
236     public void setRemainingName(Name name) {
237         if (name != null)
238             remainingName = (Name)(name.clone());
239         else
240             remainingName = null;
241     }
242 
243     /**
244      * Sets the resolved object field of this exception.
245      * @param obj The possibly null object to set resolved object to.
246      *            If null, the resolved object field is set to null.
247      * @see #getResolvedObj
248      */
249     public void setResolvedObj(Object obj) {
250         resolvedObj = obj;
251     }
252 
253     /**
254       * Add name as the last component in remaining name.
255       * @param name The component to add.
256       *         If name is null, this method does not do anything.
257       * @see #setRemainingName
258       * @see #getRemainingName
259       * @see #appendRemainingName
260       */
261     public void appendRemainingComponent(String name) {
262         if (name != null) {
263             try {
264                 if (remainingName == null) {
265                     remainingName = new CompositeName();
266                 }
267                 remainingName.add(name);
268             } catch (NamingException e) {
269                 throw new IllegalArgumentException(e.toString());
270             }
271         }
272     }
273 
274     /**
275       * Add components from 'name' as the last components in
276       * remaining name.
277       *<p>
278       * <tt>name</tt> is a composite name. If the intent is to append
279       * a compound name, you should "stringify" the compound name
280       * then invoke the overloaded form that accepts a String parameter.
281       *<p>
282       * Subsequent changes to <code>name</code> does not
283       * affect the remaining name field in this NamingException and vice versa.
284       * @param name The possibly null name containing ordered components to add.
285       *                 If name is null, this method does not do anything.
286       * @see #setRemainingName
287       * @see #getRemainingName
288       * @see #appendRemainingComponent
289       */
290     public void appendRemainingName(Name name) {
291         if (name == null) {
292             return;
293         }
294         if (remainingName != null) {
295             try {
296                 remainingName.addAll(name);
297             } catch (NamingException e) {
298                 throw new IllegalArgumentException(e.toString());
299             }
300         } else {
301             remainingName = (Name)(name.clone());
302         }
303     }
304 
305     /**
306       * Retrieves the root cause of this NamingException, if any.
307       * The root cause of a naming exception is used when the service provider
308       * wants to indicate to the caller a non-naming related exception
309       * but at the same time wants to use the NamingException structure
310       * to indicate how far the naming operation proceeded.
311       *<p>
312       * This method predates the general-purpose exception chaining facility.
313       * The {@link #getCause()} method is now the preferred means of obtaining
314       * this information.
315       *
316       * @return The possibly null exception that caused this naming
317       *    exception. If null, it means no root cause has been
318       *    set for this naming exception.
319       * @see #setRootCause
320       * @see #rootException
321       * @see #getCause
322       */
323     public Throwable getRootCause() {
324         return rootException;
325     }
326 
327     /**
328       * Records the root cause of this NamingException.
329       * If <tt>e</tt> is <tt>this</tt>, this method does not do anything.
330       *<p>
331       * This method predates the general-purpose exception chaining facility.
332       * The {@link #initCause(Throwable)} method is now the preferred means
333       * of recording this information.
334       *
335       * @param e The possibly null exception that caused the naming
336       *          operation to fail. If null, it means this naming
337       *          exception has no root cause.
338       * @see #getRootCause
339       * @see #rootException
340       * @see #initCause
341       */
342     public void setRootCause(Throwable e) {
343         if (e != this) {
344             rootException = e;
345         }
346     }
347 
348     /**
349       * Returns the cause of this exception.  The cause is the
350       * throwable that caused this naming exception to be thrown.
351       * Returns <code>null</code> if the cause is nonexistent or
352       * unknown.
353       *
354       * @return  the cause of this exception, or <code>null</code> if the
355       *          cause is nonexistent or unknown.
356       * @see #initCause(Throwable)
357       * @since 1.4
358       */
359     public Throwable getCause() {
360         return getRootCause();
361     }
362 
363     /**
364       * Initializes the cause of this exception to the specified value.
365       * The cause is the throwable that caused this naming exception to be
366       * thrown.
367       *<p>
368       * This method may be called at most once.
369       *
370       * @param  cause   the cause, which is saved for later retrieval by
371       *         the {@link #getCause()} method.  A <tt>null</tt> value
372       *         indicates that the cause is nonexistent or unknown.
373       * @return a reference to this <code>NamingException</code> instance.
374       * @throws IllegalArgumentException if <code>cause</code> is this
375       *         exception.  (A throwable cannot be its own cause.)
376       * @throws IllegalStateException if this method has already
377       *         been called on this exception.
378       * @see #getCause
379       * @since 1.4
380       */
381     public Throwable initCause(Throwable cause) {
382         super.initCause(cause);
383         setRootCause(cause);
384         return this;
385     }
386 
387     /**
388      * Generates the string representation of this exception.
389      * The string representation consists of this exception's class name,
390      * its detailed message, and if it has a root cause, the string
391      * representation of the root cause exception, followed by
392      * the remaining name (if it is not null).
393      * This string is used for debugging and not meant to be interpreted
394      * programmatically.
395      *
396      * @return The non-null string containing the string representation
397      * of this exception.
398      */
399     public String toString() {
400         String answer = super.toString();
401 
402         if (rootException != null) {
403             answer += " [Root exception is " + rootException + "]";
404         }
405         if (remainingName != null) {
406             answer += "; remaining name '" + remainingName + "'";
407         }
408         return answer;
409     }
410 
411     /**
412       * Generates the string representation in more detail.
413       * This string representation consists of the information returned
414       * by the toString() that takes no parameters, plus the string
415       * representation of the resolved object (if it is not null).
416       * This string is used for debugging and not meant to be interpreted
417       * programmatically.
418       *
419       * @param detail If true, include details about the resolved object
420       *                 in addition to the other information.
421       * @return The non-null string containing the string representation.
422       */
423     public String toString(boolean detail) {
424         if (!detail || resolvedObj == null) {
425             return toString();
426         } else {
427             return (toString() + "; resolved object " + resolvedObj);
428         }
429     }
430 
431     /**
432      * Use serialVersionUID from JNDI 1.1.1 for interoperability
433      */
434     private static final long serialVersionUID = -1299181962103167177L;
435 };