From 556f6d5861da11f7ab177a88267936de45635caf Mon Sep 17 00:00:00 2001 From: "Eric J. Bowersox" Date: Tue, 13 Nov 2001 04:53:26 +0000 Subject: [PATCH] some more javadoc work on the util and util.image packages --- src/com/silverwrist/util/AnyCharMatcher.java | 4 +- .../silverwrist/util/DOMElementHelper.java | 73 ++++++++++ src/com/silverwrist/util/IOUtil.java | 4 + src/com/silverwrist/util/LocaleFactory.java | 26 +++- src/com/silverwrist/util/OptionSet.java | 100 ++++++++++++++ .../silverwrist/util/ParallelRunQueue.java | 63 ++++++++- .../util/ServletMultipartException.java | 126 +++++++++++++++--- .../util/ServletMultipartHandler.java | 91 ++++++++++++- .../util/image/ImageLengthPair.java | 30 ++++- .../util/image/ImageNormalizer.java | 46 ++++++- .../util/image/ImageNormalizerException.java | 50 +++++++ .../silverwrist/venice/VeniceException.java | 126 +++++++++++++++--- 12 files changed, 689 insertions(+), 50 deletions(-) diff --git a/src/com/silverwrist/util/AnyCharMatcher.java b/src/com/silverwrist/util/AnyCharMatcher.java index 8cac779..4302e8d 100644 --- a/src/com/silverwrist/util/AnyCharMatcher.java +++ b/src/com/silverwrist/util/AnyCharMatcher.java @@ -34,8 +34,8 @@ public final class AnyCharMatcher *-------------------------------------------------------------------------------- */ - private char[] charset; - private int[] locs; + private char[] charset; // the set of characters to look for + private int[] locs; // a temporary array used for locations /*-------------------------------------------------------------------------------- * Constructors diff --git a/src/com/silverwrist/util/DOMElementHelper.java b/src/com/silverwrist/util/DOMElementHelper.java index 9808443..0d59a4c 100644 --- a/src/com/silverwrist/util/DOMElementHelper.java +++ b/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 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 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 Runnable 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; iRunnable objects remain, then dead threads are nulled out to + * garbage-collect them. + */ + public void work() + { + for (int i=0; i, * 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 ServletMultipartHandler 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 , * 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 <erbo@silcom.com> + * @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 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