Chained exceptions

[Eric Blake]

A comment about the documentation of chained exceptions:

from the diff of Throwable:
@@ -88,14 +132,71 @@
   public String getLocalizedMessage() {
     return getMessage();
   }
-
   /**
+   * Sets the cause of this Throwable if it has not already been set.
+   * This can be even be used when the Throwable subclass has no contructor
+   * that takes a cause. So if the only declared exception for an method
+   * or interface allows you to throw for example a
<code>IOException</code>
+   * but the real cause is some <code>SQLException</code> then you can
+   * do the following:
+   * <pre>
+   *   try {
+   *       ...
+   *   } catch (SQLException sqle) {
+   *       throw new IOException(sqle.toString()).initCause(sqle);
+   *   }
+   * </pre>

Notice that to get this to compile, you really need the example to read:

<pre>
  try {
      ...
  } catch (SQLException sqle) {
      throw (IOException) new IOException("" + sqle).initCause(sqle);
  }
</pre>

Since initCause returns a Throwable, it will usually cause compilation
problems if not recast; and declaring your method as throws Throwable
defeats the purpose of chained exceptions.

(As a side note, ""+obj is easier to type than obj.toString(), and has the
added benefit of being null-pointer safe. I am looking into adding an
optimization in jikes that recognizes this idiom so that it emits less
bytecode if one of the arguments to string concatenation is "".)
--
Eric Blake, Elixent, Castlemead, Lwr Castle St., Bristol BS1 3AG, UK
address@hidden   tel:+44(0)117 917 5611