Element class, providing some
+ * additional functionality.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ * @see org.w3c.dom.Element
+ */
public class DOMElementHelper
{
/*--------------------------------------------------------------------------------
@@ -33,6 +41,11 @@ public class DOMElementHelper
*--------------------------------------------------------------------------------
*/
+ /**
+ * Constructs a new DOMElementHelper to wrap a specific Element.
+ *
+ * @param elt The Element 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 Element, concatenated
+ * together into a single string.
+ *
+ * @param e The Element to extract text from.
+ * @return The text content under this Element node. If the specified Element
+ * has no text nodes underneath it, returns null.
+ */
private static String getTextOfElement(Element e)
{
NodeList kids = e.getChildNodes();
@@ -78,12 +99,25 @@ public class DOMElementHelper
*--------------------------------------------------------------------------------
*/
+ /**
+ * Returns the Element wrapped by this object.
+ *
+ * @return See above.
+ */
public Element getElement()
{
return elt;
} // end getElement
+ /**
+ * Searches for the first sub-element of the wrapped Element with the given name.
+ *
+ * @param name Name of the sub-element to search for.
+ * @return The first sub-element of the wrapped Element with the specified name.
+ * If the Element has no child Elements with the given name,
+ * the method returns null.
+ */
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 Element, concatenated
+ * together into a single string.
+ *
+ * @return The text content under the wrapped Element node. If the wrapped Element
+ * has not text nodes underneath it, returns null.
+ */
public String getElementText()
{
return getTextOfElement(elt);
} // end getElementText
+ /**
+ * Returns the content of all text nodes underneath the first sub-element of the wrapped
+ * Element, 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 Element node.
+ * If the wrapped Element does not have a sub-element with the given name, or
+ * that sub-element has no text nodes underneath it, returns null.
+ */
public String getSubElementText(String name)
{
Element se = getSubElement(name);
@@ -117,6 +167,13 @@ public class DOMElementHelper
} // end getSubElementText
+ /**
+ * Determines whether the wrapped Element has a sub-element with the given name.
+ *
+ * @param name Name of the sub-element to search for.
+ * @return true if the wrapped Element has a sub-element with the
+ * specified name, false if not.
+ */
public boolean hasChildElement(String name)
{
Element tmp = getSubElement(name);
@@ -124,12 +181,28 @@ public class DOMElementHelper
} // end hasChildElement
+ /**
+ * Determines whether the wrapped Element has an attribute with the given name.
+ *
+ * @param name Name of the attribute to search for.
+ * @return true if the wrapped Element has an attribute with the
+ * specified name, false 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 Element, expressed as
+ * an integer.
+ *
+ * @param name Name of the attribute to search for.
+ * @return An Integer object containing the value of the specified attribute. If
+ * the wrapped Element has no such attribute, or if the attribute's value
+ * cannot be expressed as an integer, returns null.
+ */
public Integer getAttributeInt(String name)
{
String tmp = elt.getAttribute(name);
diff --git a/src/com/silverwrist/util/IOUtil.java b/src/com/silverwrist/util/IOUtil.java
index 74fd12b..d622e09 100644
--- a/src/com/silverwrist/util/IOUtil.java
+++ b/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)
{
diff --git a/src/com/silverwrist/util/LocaleFactory.java b/src/com/silverwrist/util/LocaleFactory.java
index c72482b..9cec309 100644
--- a/src/com/silverwrist/util/LocaleFactory.java
+++ b/src/com/silverwrist/util/LocaleFactory.java
@@ -19,6 +19,15 @@ package com.silverwrist.util;
import java.util.*;
+/**
+ * A utility class which creates Locale objects from standard descriptor strings.
+ * The descriptor strings are of the form returned by Locale.toString().
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ * @see java.util.Locale
+ * @see java.util.Locale#toString()
+ */
public class LocaleFactory
{
/*--------------------------------------------------------------------------------
@@ -35,27 +44,34 @@ public class LocaleFactory
*--------------------------------------------------------------------------------
*/
+ /**
+ * Creates a Locale from a standard descriptor string.
+ *
+ * @param streq The string equivalent of the Locale to be created.
+ * @return The corresponding Locale, or the default Locale if the parameter is
+ * null 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
diff --git a/src/com/silverwrist/util/OptionSet.java b/src/com/silverwrist/util/OptionSet.java
index bf43b73..f15bc56 100644
--- a/src/com/silverwrist/util/OptionSet.java
+++ b/src/com/silverwrist/util/OptionSet.java
@@ -19,6 +19,14 @@ package com.silverwrist.util;
import java.util.BitSet;
+/**
+ * A variant of the BitSet 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 OptionSet.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @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 OptionSet. All bits are initially false.
+ */
public OptionSet()
{
super();
} // end constructor
+ /**
+ * Creates an OptionSet whose initial size is large enough to explicitly represent bits with
+ * indices in the range 0 through nbits-1. All bits are initially false. The maximum
+ * size of the OptionSet 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 OptionSet from an array of characters representing "set" options.
+ *
+ * @param options The options to be set in the new OptionSet.
+ */
public OptionSet(char[] options)
{
super(); // initialize all bits to 0
@@ -59,12 +84,28 @@ public class OptionSet extends BitSet
} // end constructor
+ /**
+ * Creates an OptionSet from a string of characters representing "set" options.
+ *
+ * @param options The options to be set in the new OptionSet.
+ */
public OptionSet(String options)
{
this(options.toCharArray());
} // end constructor
+ /*--------------------------------------------------------------------------------
+ * Internal functions
+ *--------------------------------------------------------------------------------
+ */
+
+ /**
+ * Returns a StringBuffer representing the current state of this OptionSet,
+ * with one character in it for each bit that is set.
+ *
+ * @return A StringBuffer containing the current state of the OptionSet.
+ */
private StringBuffer asStringBuffer()
{
StringBuffer b = new StringBuffer();
@@ -80,6 +121,13 @@ public class OptionSet extends BitSet
*--------------------------------------------------------------------------------
*/
+ /**
+ * Sets the bit specified by the index to false.
+ *
+ * @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 OptionSet.
+ */
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 true if the bit with
+ * the index bitIndex is currently set in this OptionSet; otherwise, the result
+ * is false.
+ *
+ * @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 OptionSet.
+ */
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 true.
+ *
+ * @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 OptionSet.
+ */
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 OptionSet 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 true to set the corresponding bit, false to clear it.
+ * @return true if the value of the bit in the OptionSet was changed by this
+ * operation, false if not.
+ * @exception java.lang.IndexOutOfBoundsException - If the specified index is negative or greater than the
+ * maximum option for an OptionSet.
+ */
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 OptionSet from an array of characters representing "set" options.
+ *
+ * @param options The options to be set in the new OptionSet. 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 OptionSet from a string of characters representing "set" options.
+ *
+ * @param options The options to be set in the new OptionSet. 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 OptionSet,
+ * with one character in it for each bit that is set.
+ *
+ * @return A character array containing the current state of the OptionSet.
+ */
public char[] asCharArray()
{
return asStringBuffer().toString().toCharArray();
} // end asCharArray
+ /**
+ * Returns a string representing the current state of this OptionSet,
+ * with one character in it for each bit that is set.
+ *
+ * @return A string containing the current state of the OptionSet.
+ */
public String asString()
{
return asStringBuffer().toString();
diff --git a/src/com/silverwrist/util/ParallelRunQueue.java b/src/com/silverwrist/util/ParallelRunQueue.java
index 3baa597..0e29672 100644
--- a/src/com/silverwrist/util/ParallelRunQueue.java
+++ b/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 Runnable objects, and executes them in parallel on
+ * multiple threads insofar as possible.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @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 Vector queue;
- private int priority;
+ private Thread[] thrds; // the current threads
+ private Vector queue; // the queue of Runnables to be run
+ private int priority; // the priority to use for all these threads
/*--------------------------------------------------------------------------------
* Constructor
*--------------------------------------------------------------------------------
*/
+ /**
+ * Creates a new ParallelRunQueue.
+ *
+ * @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; iRunnable object onto the queue. If a worker thread is available, the
+ * new object is started running immediately.
+ *
+ * @param r The Runnable object to enqueue.
+ */
public void queue(Runnable r)
{
for (int i=0; iServletMultipartHandler in certain circumstances.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @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 ServletMultipartException.
+ */
public ServletMultipartException()
{
super();
} // end constructor
+ /**
+ * Constructs a new ServletMultipartException 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 ServletMultipartException wrapping another exception.
+ *
+ * @param inner The exception wrapped by this one.
+ */
+ public ServletMultipartException(Throwable inner)
{
- super(e.getMessage());
- this.e = e;
+ super(inner.getMessage());
+ this.inner = inner;
} // end constructor
- public ServletMultipartException(String msg, Exception e)
+ /**
+ * Constructs a new ServletMultipartException 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
- {
- 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 PrintStream. Also prints the
+ * backtrace of any "wrapped" exception.
+ *
+ * @param s PrintStream 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 PrintWriter. Also prints the
+ * backtrace of any "wrapped" exception.
+ *
+ * @param s PrintWriter 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 null if there is none.
+ *
+ * @return See above.
+ */
+ public Throwable getException()
+ {
+ return inner;
} // end getException
diff --git a/src/com/silverwrist/util/ServletMultipartHandler.java b/src/com/silverwrist/util/ServletMultipartHandler.java
index d0e631f..365b8cd 100644
--- a/src/com/silverwrist/util/ServletMultipartHandler.java
+++ b/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 multipart/form-data. This is
+ * necessary because the standard Java Servlets API only handles the standard form data type of
+ * application/x-www-form-urlencoded, yet the multipart/form-data 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).
+ * When using this code, do not use the standard ServletRequest.getParameter API!
+ * Instead, if the datatype returned by ServletRequest.getContentType 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 <erbo@silcom.com>
+ * @version X
+ * @see ServletMultipartException
+ * @see javax.servlet.ServletRequest
+ */
public class ServletMultipartHandler
{
/*--------------------------------------------------------------------------------
@@ -338,6 +354,13 @@ public class ServletMultipartHandler
*--------------------------------------------------------------------------------
*/
+ /**
+ * Constructs a new ServletMultipartHandler.
+ *
+ * @param request The ServletRequest which contains the request data of type
+ * multipart/form-data.
+ * @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 Enumeration 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 Iterator over all parameter names in this request. This Iterator
+ * 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 true if the specified parameter is a file parameter, false of not.
+ * If no parameter by this name exists in the request, the method returns false.
+ */
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 null.
+ */
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 text/plain.
+ *
+ * @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 null.
+ */
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 Blob.
+ *
+ * @param name Name of the parameter to return.
+ * @return Blob containing the file parameter data. If this parameter does not
+ * exist in the request or is not a file parameter, the method returns null.
+ * @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 InputStream.
+ *
+ * @param name Name of the parameter to return.
+ * @return InputStream containing the file parameter data. If this parameter does not
+ * exist in the request or is not a file parameter, the method returns null.
+ * @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
diff --git a/src/com/silverwrist/util/image/ImageLengthPair.java b/src/com/silverwrist/util/image/ImageLengthPair.java
index c2b9e28..b535e48 100644
--- a/src/com/silverwrist/util/image/ImageLengthPair.java
+++ b/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 InputStream containing
+ * its data.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ * @see ImageNormalizer
+ */
public final class ImageLengthPair
{
/*--------------------------------------------------------------------------------
@@ -26,14 +34,21 @@ public final class ImageLengthPair
*--------------------------------------------------------------------------------
*/
- private int length;
- private InputStream data;
+ private int length; // image length
+ private InputStream data; // image data
/*--------------------------------------------------------------------------------
* Constructor
*--------------------------------------------------------------------------------
*/
+ /**
+ * Constructs a new object; usually called upon return from the ImageNormalizer.
+ *
+ * @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 InputStream.
+ *
+ * @return See above.
+ * @see java.io.InputStream
+ */
public final InputStream getData()
{
return data;
diff --git a/src/com/silverwrist/util/image/ImageNormalizer.java b/src/com/silverwrist/util/image/ImageNormalizer.java
index f151d01..57d06e0 100644
--- a/src/com/silverwrist/util/image/ImageNormalizer.java
+++ b/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 ImageLengthPair.
+ * @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 ImageLengthPair.
+ * @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
{
diff --git a/src/com/silverwrist/util/image/ImageNormalizerException.java b/src/com/silverwrist/util/image/ImageNormalizerException.java
index 5e6b740..9c8b146 100644
--- a/src/com/silverwrist/util/image/ImageNormalizerException.java
+++ b/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 ImageNormalizer when the normalizer encounters an error in
+ * its input image.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ * @see ImageNormalizer
+ */
public class ImageNormalizerException extends Exception
{
/*--------------------------------------------------------------------------------
@@ -34,18 +42,31 @@ public class ImageNormalizerException extends Exception
*--------------------------------------------------------------------------------
*/
+ /**
+ * Constructs a new ImageNormalizerException.
+ */
public ImageNormalizerException()
{
super();
} // end constructor
+ /**
+ * Constructs a new ImageNormalizerException with a text message.
+ *
+ * @param msg The message to set in this exception.
+ */
public ImageNormalizerException(String msg)
{
super(msg);
} // end constructor
+ /**
+ * Constructs a new ImageNormalizerException 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 ImageNormalizerException 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 PrintStream. Also prints the
+ * backtrace of any "wrapped" exception.
+ *
+ * @param s PrintStream 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 PrintWriter. Also prints the
+ * backtrace of any "wrapped" exception.
+ *
+ * @param s PrintWriter 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 null if there is none.
+ *
+ * @return See above.
+ */
public Throwable getException()
{
return inner;
diff --git a/src/com/silverwrist/venice/VeniceException.java b/src/com/silverwrist/venice/VeniceException.java
index f57a300..95db37a 100644
--- a/src/com/silverwrist/venice/VeniceException.java
+++ b/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 VeniceException.
+ */
public VeniceException()
{
super();
} // end constructor
+ /**
+ * Constructs a new VeniceException 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 VeniceException 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 VeniceException 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 PrintStream. Also prints the
+ * backtrace of any "wrapped" exception.
+ *
+ * @param s PrintStream 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 PrintWriter. Also prints the
+ * backtrace of any "wrapped" exception.
+ *
+ * @param s PrintWriter 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 null if there is none.
+ *
+ * @return See above.
+ */
+ public Throwable getException()
+ {
+ return inner;
} // end getException