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 gnu.java.lang.CPStringBuilder;
041
042 import java.io.PrintStream;
043 import java.io.PrintWriter;
044
045 /**
046 * Superclass of all naming Exceptions.
047 * Can contain extra information about the root cause of this exception
048 * (for example when the original exception was not a subclass of
049 * <code>NamingException</code>), the part of the <code>Name</code> that
050 * could be resolved (including the <code>Object</code> it resolved to)
051 * and the part of the <code>Name</code> that could not be resolved when
052 * the exception occured.
053 *
054 * @since 1.3
055 * @author Anthony Green (green@redhat.com)
056 * @author Mark Wielaard (mark@klomp.org)
057 */
058 public class NamingException extends Exception
059 {
060 private static final long serialVersionUID = -1299181962103167177L;
061
062 /**
063 * The root cause of this exception. Might be null. Set by calling
064 * <code>setRootCause()</code>, can be accessed by calling
065 * <code>getRootCause()</code>.
066 */
067 protected Throwable rootException;
068
069 /**
070 * If the exception was caused while resolving a <code>Name</code> then
071 * this field contains that part of the name that could be resolved.
072 * Field might be null. Set by calling <code>setResolvedName()</code>.
073 * Can be accessed by calling <code>getResolvedName</code>.
074 */
075 protected Name resolvedName;
076
077 /**
078 * If the exception was caused while resolving a <code>Name</code> then
079 * this field contains the object that part of the name could be resolved to.
080 * Field might be null. Set by calling <code>setResolvedObj()</code>.
081 * Can be accessed by calling <code>getResolvedObj</code>.
082 */
083 protected Object resolvedObj;
084
085 /**
086 * If the exception was caused while resolving a <code>Name</code> then
087 * this field contains that part of the name that could not be resolved.
088 * Field might be null. Set by calling <code>setRemainingName()</code>.
089 * The field can be extended by calling <code>appendRemainingName()</code>
090 * or <code>appendRemainingComponent()</code>.
091 * Can be accessed by calling <code>getRemainingName</code>.
092 */
093 protected Name remainingName;
094
095 /**
096 * Creates a new NamingException without a message. Does not set any of the
097 * <code>rootException</code>, <code>resolvedName</code>,
098 * <code>resolvedObj</code> or <code>remainingObject</code> fields.
099 * These fields can be set later.
100 */
101 public NamingException ()
102 {
103 super();
104 }
105
106 /**
107 * Creates a new NamingException with a detailed message. Does not set
108 * the <code>rootException</code>, <code>resolvedName</code>,
109 * <code>resolvedObj</code> or <code>remainingObject,</code> fields.
110 * These fields can be set later.
111 */
112 public NamingException (String msg)
113 {
114 super(msg);
115 }
116
117 /**
118 * Gets the root cause field <code>rootException</code> of this Exception.
119 */
120 public Throwable getRootCause ()
121 {
122 return rootException;
123 }
124
125 /**
126 * Sets the root cause field <code>rootException</code> of this Exception.
127 */
128 public void setRootCause (Throwable e)
129 {
130 rootException = e;
131 }
132
133 /**
134 * Gets the part of the name that could be resolved before this exception
135 * happend. Returns the <code>resolvedName</code> field of this Exception.
136 */
137 public Name getResolvedName ()
138 {
139 return resolvedName;
140 }
141
142 /**
143 * Sets the part of the name that could be resolved before this exception
144 * happend. Sets the <code>resolvedName</code> field of this Exception.
145 */
146 public void setResolvedName (Name name)
147 {
148 resolvedName = name;
149 }
150
151 /**
152 * Gets the Object to which (part of) the name could be resolved before this
153 * exception happend. Returns the <code>resolvedObj</code> field of this
154 * Exception.
155 */
156 public Object getResolvedObj ()
157 {
158 return resolvedObj;
159 }
160
161 /**
162 * Sets the Object to which (part of) the name could be resolved before this
163 * exception happend. Sets the <code>resolvedObj</code> field of this
164 * Exception.
165 */
166 public void setResolvedObj (Object o)
167 {
168 resolvedObj = o;
169 }
170
171 /**
172 * Gets the part of the name that could not be resolved before this exception
173 * happend. Returns the <code>remainingName</code> field of this Exception.
174 */
175 public Name getRemainingName ()
176 {
177 return remainingName;
178 }
179
180 /**
181 * Sets the part of the name that could be resolved before this exception
182 * happend. Sets the <code>resolvedName</code> field of this Exception.
183 * The field can be extended by calling <code>appendRemainingName()</code>
184 * or <code>appendRemainingComponent()</code>.
185 */
186 public void setRemainingName (Name name)
187 {
188 remainingName = name;
189 }
190
191 /**
192 * Adds the given <code>Name</code> to the <code>remainingName</code> field.
193 * Does nothing when <code>name</code> is null or when a
194 * <code>InvalidNameException</code> is thrown when adding the name.
195 *
196 * @see Name#addAll(Name)
197 */
198 public void appendRemainingName (Name name)
199 {
200 if (name != null)
201 try
202 {
203 remainingName.addAll(name);
204 }
205 catch(InvalidNameException ine) { /* ignored */ }
206 }
207
208 /**
209 * Adds the given <code>String</code> to the <code>remainingName</code> field.
210 * Does nothing when <code>name</code> is null or when a
211 * <code>InvalidNameException</code> is thrown when adding the component.
212 *
213 * @see Name#add(String)
214 */
215 public void appendRemainingComponent (String name)
216 {
217 if (name != null)
218 try
219 {
220 remainingName.add(name);
221 }
222 catch(InvalidNameException ine) { /* ignored */ }
223 }
224
225 /**
226 * Gets the message given to the constructor or null if no message was given.
227 *
228 * @see Throwable#getMessage()
229 */
230 public String getExplanation()
231 {
232 return getMessage();
233 }
234
235 /**
236 * Returns a String representation of this exception and possibly including
237 * the part object that could be resolved if the given flag is set to true.
238 * Always includes the root cause and the remaining name if not null.
239 */
240 public String toString(boolean objectInfo)
241 {
242 CPStringBuilder sb = new CPStringBuilder(super.toString());
243 Throwable cause = getRootCause();
244 if (cause != null)
245 {
246 sb.append(" caused by ");
247 sb.append(cause);
248 }
249 Name remaining = getRemainingName();
250 if (remaining != null)
251 {
252 sb.append(" [remainingName: ");
253 sb.append(remaining);
254 }
255 Object resolved = getResolvedObj();
256 if (objectInfo && resolved != null)
257 {
258 if (remainingName == null)
259 sb.append(" [");
260 else
261 sb.append(", ");
262 sb.append("resolvedObj: ");
263 sb.append(resolved);
264 }
265 if ((remaining != null) || (objectInfo && resolved != null))
266 sb.append(']');
267
268 return sb.toString();
269 }
270
271 /**
272 * Returns a string representation of this exception.
273 * Calls <code>toString(false)</code>.
274 */
275 public String toString()
276 {
277 return toString(false);
278 }
279 /**
280 * Prints the stacktrace of this exception or of the root cause if not null.
281 */
282 public void printStackTrace()
283 {
284 Throwable cause = getRootCause();
285 if (cause != null)
286 cause.printStackTrace();
287 else
288 super.printStackTrace();
289 }
290
291 /**
292 * Prints the stacktrace of this exception or of the root cause if not null
293 * to the given <code>PrintStream</code>.
294 */
295 public void printStackTrace(PrintStream ps)
296 {
297 Throwable cause = getRootCause();
298 if (cause != null)
299 cause.printStackTrace(ps);
300 else
301 super.printStackTrace(ps);
302 }
303
304 /**
305 * Prints the stacktrace of this exception or of the root cause if not null
306 * to the given <code>PrintWriter</code>.
307 */
308 public void printStackTrace(PrintWriter pw)
309 {
310 Throwable cause = getRootCause();
311 if (cause != null)
312 cause.printStackTrace(pw);
313 else
314 super.printStackTrace(pw);
315 }
316 }