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