gomp-20050608-branch/libjava/classpath/javax/naming/NamingException.java

   1 /* NamingException.java -- Superclass of all naming Exceptions
   2    Copyright (C) 2000, 2001 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package javax.naming;
  39
  40 import java.io.PrintStream;
  41 import java.io.PrintWriter;
  42
  43 /**
  44  * Superclass of all naming Exceptions.
  45  * Can contain extra information about the root cause of this exception
  46  * (for example when the original exception was not a subclass of
  47  * <code>NamingException</code>), the part of the <code>Name</code> that
  48  * could be resolved (including the <code>Object</code> it resolved to)
  49  * and the part of the <code>Name</code> that could not be resolved when
  50  * the exception occured.
  51  *
  52  * @since 1.3
  53  * @author Anthony Green (green@redhat.com)
  54  * @author Mark Wielaard (mark@klomp.org)
  55  */
  56 public class NamingException extends Exception
  57 {
  58   private static final long serialVersionUID = -1299181962103167177L;
  59
  60   /**
  61    * The root cause of this exception. Might be null. Set by calling
  62    * <code>setRootCause()</code>, can be accessed by calling
  63    * <code>getRootCause()</code>.
  64    */
  65   protected Throwable rootException;
  66
  67   /**
  68    * If the exception was caused while resolving a <code>Name</code> then
  69    * this field contains that part of the name that could be resolved.
  70    * Field might be null. Set by calling <code>setResolvedName()</code>.
  71    * Can be accessed by calling <code>getResolvedName</code>.
  72    */
  73   protected Name resolvedName;
  74
  75   /**
  76    * If the exception was caused while resolving a <code>Name</code> then
  77    * this field contains the object that part of the name could be resolved to.
  78    * Field might be null. Set by calling <code>setResolvedObj()</code>.
  79    * Can be accessed by calling <code>getResolvedObj</code>.
  80    */
  81   protected Object resolvedObj;
  82
  83   /**
  84    * If the exception was caused while resolving a <code>Name</code> then
  85    * this field contains that part of the name that could not be resolved.
  86    * Field might be null. Set by calling <code>setRemainingName()</code>.
  87    * The field can be extended by calling <code>appendRemainingName()</code>
  88    * or <code>appendRemainingComponent()</code>.
  89    * Can be accessed by calling <code>getRemainingName</code>.
  90    */
  91   protected Name remainingName;
  92
  93   /**
  94    * Creates a new NamingException without a message. Does not set any of the
  95    * <code>rootException</code>, <code>resolvedName</code>,
  96    * <code>resolvedObj</code> or <code>remainingObject</code> fields.
  97    * These fields can be set later.
  98    */
  99   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