some more javadoc work on the util and util.image packages

src/com/silverwrist/venice/VeniceException.java

@@ -7,7 +7,7 @@
  * WARRANTY OF ANY KIND, either express or implied. See the License for the specific
  * language governing rights and limitations under the License.
  * 
- * The Original Code is the Venice Web Community System.
+ * The Original Code is the Venice Web Communities System.
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
@@ -17,47 +17,141 @@
  */
 package com.silverwrist.venice;
 
+import java.io.PrintStream;
+import java.io.PrintWriter;
+
+/**
+ * The root exception of all exceptions thrown by the Venice core code.  It is capable of "wrapping"
+ * another exception within it.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public class VeniceException extends Exception
 {
-  // Attributes
-  private Exception e = null;           // internal "root cause" exception
+  /*--------------------------------------------------------------------------------
+   * Attributes
+   *--------------------------------------------------------------------------------
+   */
 
+  private Throwable inner = null;           // internal "root cause" exception
+
+  /*--------------------------------------------------------------------------------
+   * Constructors
+   *--------------------------------------------------------------------------------
+   */
+
+  /**
+   * Constructs a new <CODE>VeniceException</CODE>.
+   */
   public VeniceException()
   {
     super();
 
   } // end constructor
 
+  /**
+   * Constructs a new <CODE>VeniceException</CODE> with a text message.
+   *
+   * @param msg The message to set in this exception.
+   */
   public VeniceException(String msg)
   {
     super(msg);
 
   } // end constructor
 
-  public VeniceException(Exception e)
+  /**
+   * Constructs a new <CODE>VeniceException</CODE> wrapping another exception.
+   *
+   * @param inner The exception wrapped by this one.
+   */
+  public VeniceException(Throwable inner)
   {
-    super(e.getMessage());
-    this.e = e;
+    super(inner.getMessage());
+    this.inner = inner;
 
   } // end constructor
 
-  public VeniceException(String msg, Exception e)
+  /**
+   * Constructs a new <CODE>VeniceException</CODE> wrapping another exception.
+   *
+   * @param msg The message to set in this exception.
+   * @param inner The exception wrapped by this one.
+   */
+  public VeniceException(String msg, Throwable inner)
   {
     super(msg);
-    this.e = e;
+    this.inner = inner;
 
   } // end constructor
 
-  protected void finalize() throws Throwable
-  {
-    e = null;
-    super.finalize();
+  /*--------------------------------------------------------------------------------
+   * Overrides from class Throwable
+   *--------------------------------------------------------------------------------
+   */
 
-  } // end finalize
-
-  public Exception getException()
+  /**
+   * Prints this exception and its backtrace to the standard error stream.  Also prints the backtrace
+   * of any "wrapped" exception.
+   *
+   * @see java.lang.System#err
+   */
+  public void printStackTrace()
   {
-    return e;
+    this.printStackTrace(System.err);
+
+  } // end printStackTrace
+
+  /**
+   * Prints this exception and its backtrace to the specified <CODE>PrintStream</CODE>.  Also prints the
+   * backtrace of any "wrapped" exception.
+   *
+   * @param s <CODE>PrintStream</CODE> to use for output.
+   */
+  public void printStackTrace(PrintStream s)
+  {
+    super.printStackTrace(s);
+    if (inner!=null)
+    { // print the inner stack trace
+      s.print("Root cause: ");
+      inner.printStackTrace(s);
+
+    } // end if
+
+  } // end printStackTrace
+
+  /**
+   * Prints this exception and its backtrace to the specified <CODE>PrintWriter</CODE>.  Also prints the
+   * backtrace of any "wrapped" exception.
+   *
+   * @param s <CODE>PrintWriter</CODE> to use for output.
+   */
+  public void printStackTrace(PrintWriter s)
+  {
+    super.printStackTrace(s);
+    if (inner!=null)
+    { // print the inner stack trace
+      s.print("Root cause: ");
+      inner.printStackTrace(s);
+
+    } // end if
+
+  } // end printStackTrace
+
+  /*--------------------------------------------------------------------------------
+   * External operations
+   *--------------------------------------------------------------------------------
+   */
+
+  /**
+   * Returns the exception wrapped by this exception, or <CODE>null</CODE> if there is none.
+   *
+   * @return See above.
+   */
+  public Throwable getException()
+  {
+    return inner;
 
   } // end getException