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

src/com/silverwrist/util/AnyCharMatcher.java

@@ -34,8 +34,8 @@ public final class AnyCharMatcher
    *--------------------------------------------------------------------------------
    */
 
-  private char[] charset;
+  private char[] charset;     // the set of characters to look for
-  private int[] locs;
+  private int[] locs;         // a temporary array used for locations
 
   /*--------------------------------------------------------------------------------
    * Constructors

src/com/silverwrist/util/DOMElementHelper.java

@@ -19,6 +19,14 @@ package com.silverwrist.util;
 
 import org.w3c.dom.*;
 
+/**
+ * A class which wraps around the DOM <CODE>Element</CODE> class, providing some
+ * additional functionality.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ * @see org.w3c.dom.Element
+ */
 public class DOMElementHelper
 {
   /*--------------------------------------------------------------------------------
@@ -33,6 +41,11 @@ public class DOMElementHelper
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Constructs a new <CODE>DOMElementHelper</CODE> to wrap a specific <CODE>Element</CODE>.
+   *
+   * @param elt The <CODE>Element</CODE> to be wrapped.
+   */
   public DOMElementHelper(Element elt)
   {
     this.elt = elt;
@@ -44,6 +57,14 @@ public class DOMElementHelper
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the content of all text nodes underneath a specified <CODE>Element</CODE>, concatenated
+   * together into a single string.
+   *
+   * @param e The <CODE>Element</CODE> to extract text from.
+   * @return The text content under this <CODE>Element</CODE> node.  If the specified <CODE>Element</CODE>
+   *         has no text nodes underneath it, returns <CODE>null.</CODE>
+   */
   private static String getTextOfElement(Element e)
   {
     NodeList kids = e.getChildNodes();
@@ -78,12 +99,25 @@ public class DOMElementHelper
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the <CODE>Element</CODE> wrapped by this object.
+   *
+   * @return See above.
+   */
   public Element getElement()
   {
     return elt;
 
   } // end getElement
 
+  /**
+   * Searches for the first sub-element of the wrapped <CODE>Element</CODE> with the given name.
+   *
+   * @param name Name of the sub-element to search for.
+   * @return The first sub-element of the wrapped <CODE>Element</CODE> with the specified name.
+   *         If the <CODE>Element</CODE> has no child <CODE>Elements</CODE> with the given name,
+   *         the method returns <CODE>null</CODE>.
+   */
   public Element getSubElement(String name)
   {
     NodeList kids = elt.getChildNodes();
@@ -101,12 +135,28 @@ public class DOMElementHelper
 
   } // end getSubElement
 
+  /**
+   * Returns the content of all text nodes underneath the wrapped <CODE>Element</CODE>, concatenated
+   * together into a single string.
+   *
+   * @return The text content under the wrapped <CODE>Element</CODE> node.  If the wrapped <CODE>Element</CODE>
+   *         has not text nodes underneath it, returns <CODE>null.</CODE>
+   */
   public String getElementText()
   {
     return getTextOfElement(elt);
 
   } // end getElementText
 
+  /**
+   * Returns the content of all text nodes underneath the first sub-element of the wrapped
+   * <CODE>Element</CODE>, with the given name, concatenated together into a single string.
+   *
+   * @param name The name of the sub-element to search for.
+   * @return The text content under the specified sub-element of the wrapped <CODE>Element</CODE> node.
+   *         If the wrapped <CODE>Element</CODE> does not have a sub-element with the given name, or
+   *         that sub-element has no text nodes underneath it, returns <CODE>null.</CODE>
+   */
   public String getSubElementText(String name)
   {
     Element se = getSubElement(name);
@@ -117,6 +167,13 @@ public class DOMElementHelper
 
   } // end getSubElementText
 
+  /**
+   * Determines whether the wrapped <CODE>Element</CODE> has a sub-element with the given name.
+   *
+   * @param name Name of the sub-element to search for.
+   * @return <CODE>true</CODE> if the wrapped <CODE>Element</CODE> has a sub-element with the
+   *         specified name, <CODE>false</CODE> if not.
+   */
   public boolean hasChildElement(String name)
   {
     Element tmp = getSubElement(name);
@@ -124,12 +181,28 @@ public class DOMElementHelper
 
   } // end hasChildElement
 
+  /**
+   * Determines whether the wrapped <CODE>Element</CODE> has an attribute with the given name.
+   *
+   * @param name Name of the attribute to search for.
+   * @return <CODE>true</CODE> if the wrapped <CODE>Element</CODE> has an attribute with the
+   *         specified name, <CODE>false</CODE> if not.
+   */
   public boolean hasAttribute(String name)
   {
     return !(StringUtil.isStringEmpty(elt.getAttribute(name)));
 
   } // end hasAttribute
 
+  /**
+   * Returns the value of a specified attribute of the wrapped <CODE>Element</CODE>, expressed as
+   * an integer.
+   *
+   * @param name Name of the attribute to search for.
+   * @return An <CODE>Integer</CODE> object containing the value of the specified attribute.  If
+   *         the wrapped <CODE>Element</CODE> has no such attribute, or if the attribute's value
+   *         cannot be expressed as an integer, returns <CODE>null</CODE>.
+   */
   public Integer getAttributeInt(String name)
   {
     String tmp = elt.getAttribute(name);

src/com/silverwrist/util/IOUtil.java

@@ -47,6 +47,7 @@ public class IOUtil
    * Closes an input stream cleanly, without throwing an exception.
    *
    * @param stm The stream to be closed.
+   * @see java.io.InputStream#close()
    */
   public static void shutdown(InputStream stm)
   {
@@ -65,6 +66,7 @@ public class IOUtil
    * Closes an output stream cleanly, without throwing an exception.
    *
    * @param stm The stream to be closed.
+   * @see java.io.OutputStream#close()
    */
   public static void shutdown(OutputStream stm)
   {
@@ -83,6 +85,7 @@ public class IOUtil
    * Closes an input reader cleanly, without throwing an exception.
    *
    * @param stm The stream to be closed.
+   * @see java.io.Reader#close()
    */
   public static void shutdown(Reader rdr)
   {
@@ -101,6 +104,7 @@ public class IOUtil
    * Closes an output reader cleanly, without throwing an exception.
    *
    * @param stm The stream to be closed.
+   * @see java.io.Writer#close()
    */
   public static void shutdown(Writer wr)
   {

src/com/silverwrist/util/LocaleFactory.java

@@ -19,6 +19,15 @@ package com.silverwrist.util;
 
 import java.util.*;
 
+/**
+ * A utility class which creates <CODE>Locale</CODE> objects from standard descriptor strings.
+ * The descriptor strings are of the form returned by <CODE>Locale.toString()</CODE>.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ * @see java.util.Locale
+ * @see java.util.Locale#toString()
+ */
 public class LocaleFactory
 {
   /*--------------------------------------------------------------------------------
@@ -35,27 +44,34 @@ public class LocaleFactory
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Creates a <CODE>Locale</CODE> from a standard descriptor string.
+   *
+   * @param streq The string equivalent of the Locale to be created.
+   * @return The corresponding <CODE>Locale</CODE>, or the default <CODE>Locale</CODE> if the parameter is
+   *         <CODE>null</CODE> or the empty string.
+   */
   public static Locale createLocale(String streq)
   {
     if ((streq==null) || (streq.length()==0))
-      return Locale.getDefault();
+      return Locale.getDefault();  // no locale
     int p1 = streq.indexOf('_');
     if (p1<0)
-      return new Locale(streq,"");
+      return new Locale(streq,"");  // language but no country specified
     String x_lang = streq.substring(0,p1);
     int p2 = streq.indexOf('_',p1+1);
     if (p2<0)
     { // there's only one underscore - figure out what part the last part is
       String lastpart = streq.substring(p1+1);
       if (lastpart.length()==2)
-	return new Locale(streq.substring(0,p1),lastpart);
+	return new Locale(x_lang,lastpart);  // language + country
       else
-	return new Locale(streq.substring(0,p1),"",lastpart);
+	return new Locale(x_lang,"",lastpart); // language + country(null) + variant
 
     } // end if
 
     // do all three variants
-    return new Locale(streq.substring(0,p1),streq.substring(p1+1,p2),streq.substring(p2+1));
+    return new Locale(x_lang,streq.substring(p1+1,p2),streq.substring(p2+1));
 
   } // end createLocale
 

src/com/silverwrist/util/OptionSet.java

@@ -19,6 +19,14 @@ package com.silverwrist.util;
 
 import java.util.BitSet;
 
+/**
+ * A variant of the <CODE>BitSet</CODE> that can express itself as a character string, where each
+ * character represents a flag that is "set."  Up to 91 flags can be specified pre <CODE>OptionSet</CODE>.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ * @see java.util.BitSet
+ */
 public class OptionSet extends BitSet
 {
   /*--------------------------------------------------------------------------------
@@ -26,6 +34,7 @@ public class OptionSet extends BitSet
    *--------------------------------------------------------------------------------
    */
 
+  // The alphabet to use to store individual flags.
   private static final String ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
                                     + "!#$%&()*+,-./:;<=>?@[]^_`{|}~";
 
@@ -34,18 +43,34 @@ public class OptionSet extends BitSet
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Creates a new <CODE>OptionSet</CODE>.  All bits are initially <CODE>false</CODE>.
+   */
   public OptionSet()
   {
     super();
 
   } // end constructor
 
+  /**
+   * Creates an <CODE>OptionSet</CODE> whose initial size is large enough to explicitly represent bits with
+   * indices in the range 0 through nbits-1. All bits are initially <CODE>false</CODE>.  The maximum
+   * size of the <CODE>OptionSet</CODE> is 91.
+   *
+   * @param nbits The initial size of the bit set.
+   * @exception java.lang.NegativeArraySizeException If the specified initial size is negative.
+   */
   public OptionSet(int nbits)
   {
     super(Math.min(nbits,ALPHA.length()));
 
   } // end constructor
 
+  /**
+   * Creates an <CODE>OptionSet</CODE> from an array of characters representing "set" options.
+   *
+   * @param options The options to be set in the new <CODE>OptionSet</CODE>.
+   */
   public OptionSet(char[] options)
   {
     super();  // initialize all bits to 0
@@ -59,12 +84,28 @@ public class OptionSet extends BitSet
 
   } // end constructor
 
+  /**
+   * Creates an <CODE>OptionSet</CODE> from a string of characters representing "set" options.
+   *
+   * @param options The options to be set in the new <CODE>OptionSet</CODE>.
+   */
   public OptionSet(String options)
   {
     this(options.toCharArray());
 
   } // end constructor
 
+  /*--------------------------------------------------------------------------------
+   * Internal functions
+   *--------------------------------------------------------------------------------
+   */
+
+  /**
+   * Returns a <CODE>StringBuffer</CODE> representing the current state of this <CODE>OptionSet</CODE>,
+   * with one character in it for each bit that is set.
+   *
+   * @return A <CODE>StringBuffer</CODE> containing the current state of the <CODE>OptionSet</CODE>.
+   */
   private StringBuffer asStringBuffer()
   {
     StringBuffer b = new StringBuffer();
@@ -80,6 +121,13 @@ public class OptionSet extends BitSet
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Sets the bit specified by the index to <CODE>false</CODE>.
+   *
+   * @param bitIndex The index of the bit to be cleared.
+   * @exception java.lang.IndexOutOfBoundsException - If the specified index is negative or greater than the
+   *            maximum option for an <CODE>OptionSet</CODE>.
+   */
   public void clear(int bitIndex)
   {
     if (bitIndex>=ALPHA.length())
@@ -88,6 +136,16 @@ public class OptionSet extends BitSet
 
   } // end clear
 
+  /**
+   * Returns the value of the bit with the specified index. The value is <CODE>true</CODE> if the bit with
+   * the index <CODE>bitIndex</CODE> is currently set in this <CODE>OptionSet</CODE>; otherwise, the result
+   * is <CODE>false</CODE>.
+   *
+   * @param bitIndex The bit index.
+   * @return The value of the bit with the specified index.
+   * @exception java.lang.IndexOutOfBoundsException - If the specified index is negative or greater than the
+   *            maximum option for an <CODE>OptionSet</CODE>.
+   */
   public boolean get(int bitIndex)
   {
     if (bitIndex>=ALPHA.length())
@@ -96,6 +154,13 @@ public class OptionSet extends BitSet
 
   } // end get
 
+  /**
+   * Sets the bit specified by the index to <CODE>true</CODE>.
+   *
+   * @param bitIndex The index of the bit to be set.
+   * @exception java.lang.IndexOutOfBoundsException - If the specified index is negative or greater than the
+   *            maximum option for an <CODE>OptionSet</CODE>.
+   */
   public void set(int bitIndex)
   {
     if (bitIndex>=ALPHA.length())
@@ -109,6 +174,17 @@ public class OptionSet extends BitSet
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Sets the value of the specified bit in the <CODE>OptionSet</CODE> to a specified Boolean
+   * value, and returns an indication of whether that value was changed.
+   *
+   * @param ndx The index of the bit to be assigned.
+   * @param val <CODE>true</CODE> to set the corresponding bit, <CODE>false</CODE> to clear it.
+   * @return <CODE>true</CODE> if the value of the bit in the <CODE>OptionSet</CODE> was changed by this
+   *         operation, <CODE>false</CODE> if not.
+   * @exception java.lang.IndexOutOfBoundsException - If the specified index is negative or greater than the
+   *            maximum option for an <CODE>OptionSet</CODE>.
+   */
   public boolean assign(int ndx, boolean val)
   {
     if (ndx>=ALPHA.length())
@@ -122,6 +198,12 @@ public class OptionSet extends BitSet
 
   } // end assign
 
+  /**
+   * Resets the state of this <CODE>OptionSet</CODE> from an array of characters representing "set" options.
+   *
+   * @param options The options to be set in the new <CODE>OptionSet</CODE>.  All options not specified will
+   *                be cleared.
+   */
   public void assign(char[] options)
   {
     int i;
@@ -138,6 +220,12 @@ public class OptionSet extends BitSet
 
   } // end assign
 
+  /**
+   * Resets the state of this <CODE>OptionSet</CODE> from a string of characters representing "set" options.
+   *
+   * @param options The options to be set in the new <CODE>OptionSet</CODE>.  All options not specified will
+   *                be cleared.
+   */
   public void assign(String options)
   {
     if (options!=null)
@@ -145,12 +233,24 @@ public class OptionSet extends BitSet
 
   } // end assign
 
+  /**
+   * Returns a character array representing the current state of this <CODE>OptionSet</CODE>,
+   * with one character in it for each bit that is set.
+   *
+   * @return A character array containing the current state of the <CODE>OptionSet</CODE>.
+   */
   public char[] asCharArray()
   {
     return asStringBuffer().toString().toCharArray();
 
   } // end asCharArray
 
+  /**
+   * Returns a string representing the current state of this <CODE>OptionSet</CODE>,
+   * with one character in it for each bit that is set.
+   *
+   * @return A string containing the current state of the <CODE>OptionSet</CODE>.
+   */
   public String asString()
   {
     return asStringBuffer().toString();

src/com/silverwrist/util/ParallelRunQueue.java

@@ -19,6 +19,15 @@ package com.silverwrist.util;
 
 import java.util.Vector;
 
+/**
+ * A class which takes any number of <CODE>Runnable</CODE> objects, and executes them in parallel on
+ * multiple threads insofar as possible.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ * @see java.lang.Runnable
+ * @see java.lang.Thread
+ */
 public class ParallelRunQueue implements Runnable
 {
   /*--------------------------------------------------------------------------------
@@ -26,22 +35,27 @@ public class ParallelRunQueue implements Runnable
    *--------------------------------------------------------------------------------
    */
 
-  private Thread[] thrds;
+  private Thread[] thrds;    // the current threads
-  private Vector queue;
+  private Vector queue;      // the queue of Runnables to be run
-  private int priority;
+  private int priority;      // the priority to use for all these threads
 
   /*--------------------------------------------------------------------------------
    * Constructor
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Creates a new <CODE>ParallelRunQueue</CODE>.
+   *
+   * @param nthread Number of threads to be executed in parallel with the current one by this run queue.
+   */
   public ParallelRunQueue(int nthread)
   {
     thrds = new Thread[nthread];
     for (int i=0; i<nthread; i++)
-      thrds[i] = null;
+      thrds[i] = null;  // no threads to start with
     queue = new Vector();
-    priority = Thread.currentThread().getPriority();
+    priority = Thread.currentThread().getPriority();  // default the priority
 
   } // end constructor
 
@@ -50,6 +64,11 @@ public class ParallelRunQueue implements Runnable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Executes all <CODE>Runnable</CODE> objects currently queued.  When this method returns, the run queue
+   * is empty.  The objects are executed on one of the internal worker threads, or on the current thread
+   * if no other threads are available.
+   */
   public void run()
   {
     while (queue.size()>0)
@@ -72,6 +91,8 @@ public class ParallelRunQueue implements Runnable
 
     } // end while
 
+    work();  // GC any further dead threads
+
   } // end run
 
   /*--------------------------------------------------------------------------------
@@ -79,6 +100,12 @@ public class ParallelRunQueue implements Runnable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Enqueues a new <CODE>Runnable</CODE> object onto the queue.  If a worker thread is available, the
+   * new object is started running immediately.
+   *
+   * @param r The <CODE>Runnable</CODE> object to enqueue.
+   */
   public void queue(Runnable r)
   {
     for (int i=0; i<thrds.length; i++)
@@ -88,6 +115,7 @@ public class ParallelRunQueue implements Runnable
 	thrds[i] = new Thread(r);
 	thrds[i].setPriority(priority);
 	thrds[i].start();
+	work();
 	return;
 
       } // end if
@@ -98,4 +126,29 @@ public class ParallelRunQueue implements Runnable
 
   } // end queue
 
+  /**
+   * If any threads in the run queue are dead, replaces them with live threads running fresh elements out
+   * of the queue.  If no more <CODE>Runnable</CODE> objects remain, then dead threads are nulled out to
+   * garbage-collect them.
+   */
+  public void work()
+  {
+    for (int i=0; i<thrds.length; i++)
+      if ((thrds[i]==null) || !(thrds[i].isAlive()))
+      { // found an empty slot or dead thread to replace
+	if (queue.size()==0)
+	  thrds[i] = null;  // let the dead thread be garbage-collected
+	else
+	{ // get the next Runnable and enqueue it
+	  Runnable r = (Runnable)(queue.remove(0));
+	  thrds[i] = new Thread(r);
+	  thrds[i].setPriority(priority);
+	  thrds[i].start();
+
+	} // end else
+
+      } // end if and for
+
+  } // end work
+
 } // end class ParallelRunQueue

src/com/silverwrist/util/ServletMultipartException.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.util;
 
+import java.io.PrintStream;
+import java.io.PrintWriter;
+
+/**
+ * An exception thrown by <CODE>ServletMultipartHandler</CODE> in certain circumstances.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ * @see ServletMultipartHandler
+ */
 public class ServletMultipartException 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>ServletMultipartException</CODE>.
+   */
   public ServletMultipartException()
   {
     super();
 
   } // end constructor
 
+  /**
+   * Constructs a new <CODE>ServletMultipartException</CODE> with a text message.
+   *
+   * @param msg The message to set in this exception.
+   */
   public ServletMultipartException(String msg)
   {
     super(msg);
 
   } // end constructor
 
-  public ServletMultipartException(Exception e)
+  /**
+   * Constructs a new <CODE>ServletMultipartException</CODE> wrapping another exception.
+   *
+   * @param inner The exception wrapped by this one.
+   */
+  public ServletMultipartException(Throwable inner)
   {
-    super(e.getMessage());
+    super(inner.getMessage());
-    this.e = e;
+    this.inner = inner;
 
   } // end constructor
 
-  public ServletMultipartException(String msg, Exception e)
+  /**
+   * Constructs a new <CODE>ServletMultipartException</CODE> wrapping another exception.
+   *
+   * @param msg The message to set in this exception.
+   * @param inner The exception wrapped by this one.
+   */
+  public ServletMultipartException(String msg, Throwable inner)
   {
     super(msg);
-    this.e = e;
+    this.inner = inner;
 
   } // end constructor
 
-  protected void finalize() throws Throwable
+  /*--------------------------------------------------------------------------------
-  {
+   * Overrides from class Throwable
-    e = null;
+   *--------------------------------------------------------------------------------
-    super.finalize();
+   */
 
-  } // end finalize
+  /**
-
+   * Prints this exception and its backtrace to the standard error stream.  Also prints the backtrace
-  public Exception getException()
+   * 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
 

src/com/silverwrist/util/ServletMultipartHandler.java

@@ -31,6 +31,22 @@ import org.apache.log4j.*;
 // a bunch of APIs in ways that their designers would never have anticipated.  It's
 // absolutely bodge-tastic!
 
+/**
+ * A class which parses servlet request data of the MIME type <CODE>multipart/form-data</CODE>.  This is
+ * necessary because the standard Java Servlets API only handles the standard form data type of
+ * <CODE>application/x-www-form-urlencoded</CODE>, yet the <CODE>multipart/form-data</CODE> form
+ * data type is the only way to upload files using a standard Web browser (at least one that implements
+ * RFC 1867, as most modern browsers do).<P>
+ * When using this code, do <EM>not</EM> use the standard <CODE>ServletRequest.getParameter</CODE> API!
+ * Instead, if the datatype returned by <CODE>ServletRequest.getContentType</CODE> is "multipart/form-data",
+ * pass the request to the constructor of this class, and then use the methods of this class to extract both
+ * file and non-file parameters.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ * @see ServletMultipartException
+ * @see javax.servlet.ServletRequest
+ */
 public class ServletMultipartHandler
 {
   /*--------------------------------------------------------------------------------
@@ -338,6 +354,13 @@ public class ServletMultipartHandler
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Constructs a new <CODE>ServletMultipartHandler</CODE>.
+   *
+   * @param request The <CODE>ServletRequest</CODE> which contains the request data of type
+   *                <CODE>multipart/form-data</CODE>.
+   * @exception com.silverwrist.util.ServletMultipartException The request could not be correctly parsed.
+   */
   public ServletMultipartHandler(ServletRequest request) throws ServletMultipartException
   {
     try
@@ -398,6 +421,13 @@ public class ServletMultipartHandler
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns an <CODE>Enumeration</CODE> of all parameter names in this request.
+   *
+   * @return See above.
+   * @see #getParamNames()
+   * @see java.util.Enumeration
+   */
   public Enumeration getNames()
   {
     ArrayList tmp_v = new ArrayList();
@@ -413,6 +443,14 @@ public class ServletMultipartHandler
 
   } // end getNames
 
+  /**
+   * Returns an <CODE>Iterator</CODE> over all parameter names in this request.  This <CODE>Iterator</CODE>
+   * must be considered read-only.
+   *
+   * @return See above.
+   * @see #getNames()
+   * @see java.util.Iterator
+   */
   public Iterator getParamNames()
   {
     ArrayList tmp_v = new ArrayList();
@@ -428,6 +466,13 @@ public class ServletMultipartHandler
     
   } // end getParamNames
 
+  /**
+   * Returns whether or not the parameter with the specified name is a file parameter.
+   *
+   * @param name Name of the parameter to test.
+   * @return <CODE>true</CODE> if the specified parameter is a file parameter, <CODE>false</CODE> of not.
+   *         If no parameter by this name exists in the request, the method returns <CODE>false</CODE>.
+   */
   public boolean isFileParam(String name)
   {
     MultipartParameter parm = (MultipartParameter)(param_byname.get(name));
@@ -442,6 +487,14 @@ public class ServletMultipartHandler
 
   } // end isFileParam
 
+  /**
+   * Returns the value of the parameter with the specified name.  In the case of file parameters, returns
+   * the name of the file that was uploaded.
+   *
+   * @param name Name of the parameter to return.
+   * @return Value of the parameter, which is a filename if this parameter is a file.  If no parameter by
+   *         this name exists in the request, the method returns <CODE>null</CODE>.
+   */
   public String getValue(String name)
   {
     MultipartParameter parm = (MultipartParameter)(param_byname.get(name));
@@ -456,6 +509,14 @@ public class ServletMultipartHandler
 
   } // end getValue
 
+  /**
+   * Returns the MIME type of the file parameter with the specified name.  Ordinary text parameters return
+   * the MIME type <CODE>text/plain</CODE>.
+   *
+   * @param name Name of the parameter to return.
+   * @return Content type of the parameter.  If no parameter by this name exists in the request, the method
+   *         returns <CODE>null</CODE>.
+   */
   public String getContentType(String name)
   {
     MultipartParameter parm = (MultipartParameter)(param_byname.get(name));
@@ -470,6 +531,14 @@ public class ServletMultipartHandler
 
   } // end getContentType
 
+  /**
+   * Returns the size in bytes of the file parameter with the specified name.  For ordinary text parameters,
+   * the return value is meaningless.
+   *
+   * @param name Name of the parameter to return.
+   * @return Size in bytes of the parameter.  If no parameter by this name exists in the request, the method
+   *         returns -1.
+   */
   public int getContentSize(String name)
   {
     MultipartParameter parm = (MultipartParameter)(param_byname.get(name));
@@ -484,6 +553,16 @@ public class ServletMultipartHandler
 
   } // end getContentSize
 
+  /**
+   * Returns the contents of the specified file parameter expressed as a <CODE>Blob</CODE>.
+   *
+   * @param name Name of the parameter to return.
+   * @return <CODE>Blob</CODE> containing the file parameter data.  If this parameter does not
+   *         exist in the request or is not a file parameter, the method returns <CODE>null</CODE>.
+   * @exception com.silverwrist.util.ServletMultipartException Unable to prepare the file parameter data.
+   * @see #getFileContentStream()
+   * @see java.sql.Blob
+   */
   public Blob getFileContentBlob(String name) throws ServletMultipartException
   {
     MultipartParameter parm = (MultipartParameter)(param_byname.get(name));
@@ -498,6 +577,16 @@ public class ServletMultipartHandler
 
   } // end getFileContentBlob
 
+  /**
+   * Returns the contents of the specified file parameter expressed as an <CODE>InputStream</CODE>.
+   *
+   * @param name Name of the parameter to return.
+   * @return <CODE>InputStream</CODE> containing the file parameter data.  If this parameter does not
+   *         exist in the request or is not a file parameter, the method returns <CODE>null</CODE>.
+   * @exception com.silverwrist.util.ServletMultipartException Unable to prepare the file parameter data.
+   * @see #getFileContentBlob()
+   * @see java.io.InputStream
+   */
   public InputStream getFileContentStream(String name) throws ServletMultipartException
   {
     MultipartParameter parm = (MultipartParameter)(param_byname.get(name));
@@ -509,7 +598,7 @@ public class ServletMultipartHandler
     } // end if
 
     MultipartDataValue val = parm.getContent();
-    return val.getBinaryStream();
+    return ((val==null) ? null : val.getBinaryStream());
 
   } // end getFileContentStream
 

src/com/silverwrist/util/image/ImageLengthPair.java

@@ -19,6 +19,14 @@ package com.silverwrist.util.image;
 
 import java.io.InputStream;
 
+/**
+ * A class used to return both an image's length in bytes and an <CODE>InputStream</CODE> containing
+ * its data.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ * @see ImageNormalizer
+ */
 public final class ImageLengthPair
 {
   /*--------------------------------------------------------------------------------
@@ -26,14 +34,21 @@ public final class ImageLengthPair
    *--------------------------------------------------------------------------------
    */
 
-  private int length;
+  private int length;              // image length
-  private InputStream data;
+  private InputStream data;        // image data
 
   /*--------------------------------------------------------------------------------
    * Constructor
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Constructs a new object; usually called upon return from the <CODE>ImageNormalizer</CODE>.
+   *
+   * @param length Image length to be returned.
+   * @param data Image data to be returned.
+   * @see java.io.InputStream
+   */
   public ImageLengthPair(int length, InputStream data)
   {
     this.length = length;
@@ -46,12 +61,23 @@ public final class ImageLengthPair
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the length of the image data.
+   *
+   * @return See above.
+   */
   public final int getLength()
   {
     return length;
 
   } // end getLength
 
+  /**
+   * Returns the iage data expressed as an <CODE>InputStream</CODE>.
+   *
+   * @return See above.
+   * @see java.io.InputStream
+   */
   public final InputStream getData()
   {
     return data;

src/com/silverwrist/util/image/ImageNormalizer.java

@@ -24,6 +24,15 @@ import java.io.*;
 import javax.media.jai.*;
 import com.sun.media.jai.codec.*;
 
+/**
+ * A class that performs "normalization" on an image to fit within a bounding box of a specified pixel
+ * size.  "Normalized" images are scaled down proportionally to fit the bounding box, then centered over
+ * a black backdrop (so the image will be "letterboxed" if it has a larger H:V aspect ratio than the bounding
+ * box, or "pillarboxed" if it has a smaller H:V aspect ratio than the bounding box).
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ */
 public class ImageNormalizer
 {
   /*--------------------------------------------------------------------------------
@@ -31,10 +40,26 @@ public class ImageNormalizer
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * "Normalizes" an image to fit within a bounding box of a specified pixel size.  "Normalized" images are
+   * scaled down proportionally to fit the bounding box, then centered over a black backdrop (so the image
+   * will be "letterboxed" if it has a larger H:V aspect ratio than the bounding box, or "pillarboxed" if it
+   * has a smaller H:V aspect ratio than the bounding box).
+   *
+   * @param raw_data Raw image data from the input, in any JAI-recognized format.
+   * @param width The width of the bounding box to use to normalize the image.
+   * @param height The height of the bounding box to use to normalize the image.
+   * @param out_format The desired format for output (such as "JPEG").
+   * @return The normalized image data and its length, as an <CODE>ImageLengthPair</CODE>.
+   * @exception com.silverwrist.util.image.ImageNormalizerException An error occurred in the image data or
+   *            the image transformation process.
+   * @see ImageLengthPair
+   * @see ImageNormalizerException
+   */
   public static ImageLengthPair normalizeImage(InputStream raw_data, int width, int height, String out_format)
       throws ImageNormalizerException
   {
-    PlanarImage img1;
+    PlanarImage img1;  // the "initial" image we're loading
     try
     { // Start by loading the image we're working with.
       SeekableStream istm = new ForwardSeekableStream(raw_data);
@@ -75,7 +100,7 @@ public class ImageNormalizer
 	scale = scale_height;
 
       // If we need to scale the image now, do so.
-      PlanarImage img2;
+      PlanarImage img2;   // image post-scaling
       if (scale!=null)
       { // scale the image down!
 	ParameterBlock pb1 = new ParameterBlock();
@@ -96,7 +121,7 @@ public class ImageNormalizer
       int offset_y = (height - img2.getHeight()) / 2;
 
       // If we need to translate the image now, do so.
-      PlanarImage img3;
+      PlanarImage img3;    // image after scaling and translation
       if ((offset_x!=0) || (offset_y!=0))
       { // set up a translation to move the image to the right location
 	ParameterBlock pb2 = new ParameterBlock();
@@ -143,6 +168,21 @@ public class ImageNormalizer
 
   } // end normalizeImage
 
+  /**
+   * "Normalizes" an image to fit within a bounding box of a specified pixel size.  "Normalized" images are
+   * scaled down proportionally to fit the bounding box, then centered over a black backdrop (so the image
+   * will be "letterboxed" if it has a larger H:V aspect ratio than the bounding box, or "pillarboxed" if it
+   * has a smaller H:V aspect ratio than the bounding box).
+   *
+   * @param raw_data Raw image data from the input, in any JAI-recognized format.
+   * @param dim The dimensions of the bounding box to use to normalize the image.
+   * @param out_format The desired format for output (such as "JPEG").
+   * @return The normalized image data and its length, as an <CODE>ImageLengthPair</CODE>.
+   * @exception com.silverwrist.util.image.ImageNormalizerException An error occurred in the image data or
+   *            the image transformation process.
+   * @see ImageLengthPair
+   * @see ImageNormalizerException
+   */
   public static ImageLengthPair normalizeImage(InputStream raw_data, Dimension dim, String out_format)
       throws ImageNormalizerException
   {

src/com/silverwrist/util/image/ImageNormalizerException.java

@@ -20,6 +20,14 @@ package com.silverwrist.util.image;
 import java.io.PrintStream;
 import java.io.PrintWriter;
 
+/**
+ * An exception thrown by <CODE>ImageNormalizer</CODE> when the normalizer encounters an error in
+ * its input image.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ * @see ImageNormalizer
+ */
 public class ImageNormalizerException extends Exception
 {
   /*--------------------------------------------------------------------------------
@@ -34,18 +42,31 @@ public class ImageNormalizerException extends Exception
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Constructs a new <CODE>ImageNormalizerException</CODE>.
+   */
   public ImageNormalizerException()
   {
     super();
 
   } // end constructor
 
+  /**
+   * Constructs a new <CODE>ImageNormalizerException</CODE> with a text message.
+   *
+   * @param msg The message to set in this exception.
+   */
   public ImageNormalizerException(String msg)
   {
     super(msg);
 
   } // end constructor
 
+  /**
+   * Constructs a new <CODE>ImageNormalizerException</CODE> wrapping another exception.
+   *
+   * @param t The exception wrapped by this one.
+   */
   public ImageNormalizerException(Throwable t)
   {
     super(t.getMessage());
@@ -53,6 +74,12 @@ public class ImageNormalizerException extends Exception
 
   } // end constructor
 
+  /**
+   * Constructs a new <CODE>ImageNormalizerException</CODE> wrapping another exception.
+   *
+   * @param msg The message to set in this exception.
+   * @param t The exception wrapped by this one.
+   */
   public ImageNormalizerException(String msg, Throwable t)
   {
     super(msg);
@@ -65,12 +92,24 @@ public class ImageNormalizerException extends Exception
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * 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()
   {
     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);
@@ -83,6 +122,12 @@ public class ImageNormalizerException extends Exception
 
   } // 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);
@@ -100,6 +145,11 @@ public class ImageNormalizerException extends Exception
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the exception wrapped by this exception, or <CODE>null</CODE> if there is none.
+   *
+   * @return See above.
+   */
   public Throwable getException()
   {
     return inner;

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());
+    super(inner.getMessage());
-    this.e = e;
+    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
+  /*--------------------------------------------------------------------------------
-  {
+   * Overrides from class Throwable
-    e = null;
+   *--------------------------------------------------------------------------------
-    super.finalize();
+   */
 
-  } // end finalize
+  /**
-
+   * Prints this exception and its backtrace to the standard error stream.  Also prints the backtrace
-  public Exception getException()
+   * 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