001 /* NamingException.java -- Superclass of all naming Exceptions
002 Copyright (C) 2000, 2001 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038 package javax.naming;
039
040 import java.io.PrintStream;
041 import java.io.PrintWriter;
042
043 /**
044 * Superclass of all naming Exceptions.
045 * Can contain extra information about the root cause of this exception
046 * (for example when the original exception was not a subclass of
047 * <code>NamingException</code>), the part of the <code>Name</code> that
048 * could be resolved (including the <code>Object</code> it resolved to)
049 * and the part of the <code>Name</code> that could not be resolved when
050 * the exception occured.
051 *
052 * @since 1.3
053 * @author Anthony Green (green@redhat.com)
054 * @author Mark Wielaard (mark@klomp.org)
055 */
056 public class NamingException extends Exception
057 {
058 private static final long serialVersionUID = -1299181962103167177L;
059
060 /**
061 * The root cause of this exception. Might be null. Set by calling
062 * <code>setRootCause()</code>, can be accessed by calling
063 * <code>getRootCause()</code>.
064 */
065 protected Throwable rootException;
066
067 /**
068 * If the exception was caused while resolving a <code>Name</code> then
069 * this field contains that part of the name that could be resolved.
070 * Field might be null. Set by calling <code>setResolvedName()</code>.
071 * Can be accessed by calling <code>getResolvedName</code>.
072 */
073 protected Name resolvedName;
074
075 /**
076 * If the exception was caused while resolving a <code>Name</code> then
077 * this field contains the object that part of the name could be resolved to.
078 * Field might be null. Set by calling <code>setResolvedObj()</code>.
079 * Can be accessed by calling <code>getResolvedObj</code>.
080 */
081 protected Object resolvedObj;
082
083 /**
084 * If the exception was caused while resolving a <code>Name</code> then
085 * this field contains that part of the name that could not be resolved.
086 * Field might be null. Set by calling <code>setRemainingName()</code>.
087 * The field can be extended by calling <code>appendRemainingName()</code>
088 * or <code>appendRemainingComponent()</code>.
089 * Can be accessed by calling <code>getRemainingName</code>.
090 */
091 protected Name remainingName;
092
093 /**
094 * Creates a new NamingException without a message. Does not set any of the
095 * <code>rootException</code>, <code>resolvedName</code>,
096 * <code>resolvedObj</code> or <code>remainingObject</code> fields.
097 * These fields can be set later.
098 */
099 public NamingException ()
100 {
101 super();
102 }
103
104 /**
105 * Creates a new NamingException with a detailed message. Does not set
106 * the <code>rootException</code>, <code>resolvedName</code>,
107 * <code>resolvedObj</code> or <code>remainingObject,</code> fields.
108 * These fields can be set later.
109 */
110 public NamingException (String msg)
111 {
112 super(msg);
113 }
114
115 /**
116 * Gets the root cause field <code>rootException</code> of this Exception.
117 */
118 public Throwable getRootCause ()
119 {
120 return rootException;
121 }
122
123 /**
124 * Sets the root cause field <code>rootException</code> of this Exception.
125 */
126 public void setRootCause (Throwable e)
127 {
128 rootException = e;
129 }
130
131 /**
132 * Gets the part of the name that could be resolved before this exception
133 * happend. Returns the <code>resolvedName</code> field of this Exception.
134 */
135 public Name getResolvedName ()
136 {
137 return resolvedName;
138 }
139
140 /**
141 * Sets the part of the name that could be resolved before this exception
142 * happend. Sets the <code>resolvedName</code> field of this Exception.
143 */
144 public void setResolvedName (Name name)
145 {
146 resolvedName = name;
147 }
148
149 /**
150 * Gets the Object to which (part of) the name could be resolved before this
151 * exception happend. Returns the <code>resolvedObj</code> field of this
152 * Exception.
153 */
154 public Object getResolvedObj ()
155 {
156 return resolvedObj;
157 }
158
159 /**
160 * Sets the Object to which (part of) the name could be resolved before this
161 * exception happend. Sets the <code>resolvedObj</code> field of this
162 * Exception.
163 */
164 public void setResolvedObj (Object o)
165 {
166 resolvedObj = o;
167 }
168
169 /**
170 * Gets the part of the name that could not be resolved before this exception
171 * happend. Returns the <code>remainingName</code> field of this Exception.
172 */
173 public Name getRemainingName ()
174 {
175 return remainingName;
176 }
177
178 /**
179 * Sets the part of the name that could be resolved before this exception
180 * happend. Sets the <code>resolvedName</code> field of this Exception.
181 * The field can be extended by calling <code>appendRemainingName()</code>
182 * or <code>appendRemainingComponent()</code>.
183 */
184 public void setRemainingName (Name name)
185 {
186 remainingName = name;
187 }
188
189 /**
190 * Adds the given <code>Name</code> to the <code>remainingName</code> field.
191 * Does nothing when <code>name</code> is null or when a
192 * <code>InvalidNameException</code> is thrown when adding the name.
193 *
194 * @see Name#addAll(Name)
195 */
196 public void appendRemainingName (Name name)
197 {
198 if (name != null)
199 try
200 {
201 remainingName.addAll(name);
202 }
203 catch(InvalidNameException ine) { /* ignored */ }
204 }
205
206 /**
207 * Adds the given <code>String</code> to the <code>remainingName</code> field.
208 * Does nothing when <code>name</code> is null or when a
209 * <code>InvalidNameException</code> is thrown when adding the component.
210 *
211 * @see Name#add(String)
212 */
213 public void appendRemainingComponent (String name)
214 {
215 if (name != null)
216 try
217 {
218 remainingName.add(name);
219 }
220 catch(InvalidNameException ine) { /* ignored */ }
221 }
222
223 /**
224 * Gets the message given to the constructor or null if no message was given.
225 *
226 * @see Throwable#getMessage()
227 */
228 public String getExplanation()
229 {
230 return getMessage();
231 }
232
233 /**
234 * Returns a String representation of this exception and possibly including
235 * the part object that could be resolved if the given flag is set to true.
236 * Always includes the root cause and the remaining name if not null.
237 */
238 public String toString(boolean objectInfo)
239 {
240 StringBuffer sb = new StringBuffer(super.toString());
241 Throwable cause = getRootCause();
242 if (cause != null)
243 {
244 sb.append(" caused by ");
245 sb.append(cause);
246 }
247 Name remaining = getRemainingName();
248 if (remaining != null)
249 {
250 sb.append(" [remainingName: ");
251 sb.append(remaining);
252 }
253 Object resolved = getResolvedObj();
254 if (objectInfo && resolved != null)
255 {
256 if (remainingName == null)
257 sb.append(" [");
258 else
259 sb.append(", ");
260 sb.append("resolvedObj: ");
261 sb.append(resolved);
262 }
263 if ((remaining != null) || (objectInfo && resolved != null))
264 sb.append(']');
265
266 return sb.toString();
267 }
268
269 /**
270 * Returns a string representation of this exception.
271 * Calls <code>toString(false)</code>.
272 */
273 public String toString()
274 {
275 return toString(false);
276 }
277 /**
278 * Prints the stacktrace of this exception or of the root cause if not null.
279 */
280 public void printStackTrace()
281 {
282 Throwable cause = getRootCause();
283 if (cause != null)
284 cause.printStackTrace();
285 else
286 super.printStackTrace();
287 }
288
289 /**
290 * Prints the stacktrace of this exception or of the root cause if not null
291 * to the given <code>PrintStream</code>.
292 */
293 public void printStackTrace(PrintStream ps)
294 {
295 Throwable cause = getRootCause();
296 if (cause != null)
297 cause.printStackTrace(ps);
298 else
299 super.printStackTrace(ps);
300 }
301
302 /**
303 * Prints the stacktrace of this exception or of the root cause if not null
304 * to the given <code>PrintWriter</code>.
305 */
306 public void printStackTrace(PrintWriter pw)
307 {
308 Throwable cause = getRootCause();
309 if (cause != null)
310 cause.printStackTrace(pw);
311 else
312 super.printStackTrace(pw);
313 }
314 }
315