amy/venice-main-classic
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

Browse Source
This commit is contained in:
Eric J. Bowersox 2001-11-13 04:53:26 +00:00
parent 7e42aa391c
commit 556f6d5861
12 changed files with 689 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/com/silverwrist/util/AnyCharMatcher.java
View File

@ -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

73
src/com/silverwrist/util/DOMElementHelper.java
View File

@ -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);

4
src/com/silverwrist/util/IOUtil.java
View File

@ -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)
{

26
src/com/silverwrist/util/LocaleFactory.java
View File

@ -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

100
src/com/silverwrist/util/OptionSet.java
View File

@ -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();

63
src/com/silverwrist/util/ParallelRunQueue.java
View File

@ -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 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 <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

126
src/com/silverwrist/util/ServletMultipartException.java
View File

@ -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());
this.e = e;
super(inner.getMessage());
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
{
e = null;
super.finalize();
/*--------------------------------------------------------------------------------
* Overrides from class Throwable
*--------------------------------------------------------------------------------
*/
} // end finalize
public Exception getException()
/**
* Prints this exception and its backtrace to the standard error stream. Also prints the backtrace
* of any "wrapped" exception.
*
* @see java.lang.System#err
*/
public void printStackTrace()
{
return e;
this.printStackTrace(System.err);
} // end printStackTrace
/**
* Prints this exception and its backtrace to the specified <CODE>PrintStream</CODE>. Also prints the
* backtrace of any "wrapped" exception.
*
* @param s <CODE>PrintStream</CODE> to use for output.
*/
public void printStackTrace(PrintStream s)
{
super.printStackTrace(s);
if (inner!=null)
{ // print the inner stack trace
s.print("Root cause: ");
inner.printStackTrace(s);
} // end if
} // end printStackTrace
/**
* Prints this exception and its backtrace to the specified <CODE>PrintWriter</CODE>. Also prints the
* backtrace of any "wrapped" exception.
*
* @param s <CODE>PrintWriter</CODE> to use for output.
*/
public void printStackTrace(PrintWriter s)
{
super.printStackTrace(s);
if (inner!=null)
{ // print the inner stack trace
s.print("Root cause: ");
inner.printStackTrace(s);
} // end if
} // end printStackTrace
/*--------------------------------------------------------------------------------
* External operations
*--------------------------------------------------------------------------------
*/
/**
* Returns the exception wrapped by this exception, or <CODE>null</CODE> if there is none.
*
* @return See above.
*/
public Throwable getException()
{
return inner;
} // end getException

91
src/com/silverwrist/util/ServletMultipartHandler.java
View File

@ -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

30
src/com/silverwrist/util/image/ImageLengthPair.java
View File

@ -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 InputStream data;
private int length; // image length
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;

46
src/com/silverwrist/util/image/ImageNormalizer.java
View File

@ -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 &lt;erbo@silcom.com&gt;
* @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
{

50
src/com/silverwrist/util/image/ImageNormalizerException.java
View File

@ -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;

126
src/com/silverwrist/venice/VeniceException.java
View File

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