NamingException


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