com.opmath.util.http
Class MultiForm

java.lang.Object
  |
  +--com.opmath.util.http.MultiForm

public class MultiForm

extends Object

A framework for extraction of data from an HTTP "multipart/form-data" POST operation.

In these scenarios, the browser uploads any text or binary file type to the server. The HTML form should look like:

<FORM METHOD="POST" ACTION="http://sun.local:8080/test/servlet/upload" ENCTYPE="multipart/form-data">

<INPUT TYPE="file" NAME="USERFILE" SIZE="40" MAXLENGTH="128">
<INPUT TYPE="input" NAME="TEXT" SIZE="40" MAXLENGTH="128">
<INPUT TYPE="submit" VALUE="Upload">

</FORM>

NOTE: Because MultiForm is required to stream the data from the HTTP request to the server-side file output, it cannot provide random access to the request parameters. An example of the correct use of MultiForm is as follows:

pMF = new MultiForm(req);
for (int i = 0; i < params.length; i++) {

switch (paramIndex(pMF.getNextParam()))
{

case PARAM_FILE:

outStrm = new FileOutputStream(IMG_PATH + pMF.getParamFilename());
pMF.writeParamValue(outStrm);
outStrm.close();
uploadSet.appendTo("imageFile", pMF.getParamFilename());
break;

case PARAM_TEXT:

uploadSet.appendTo("text", pMF.getParamValue());
break;

default:

throw new Exception("unknown parameter: [" + pMF.getParamName() + "]");

}

}

out.println(uploadDMLDoc.toString(uploadSet));

It is the programer's responsibility to ensure that MultiForm methods are invoked in the appropriate order. In particular, writeParamValue() should follow the identification of the file name parameter, and getParamValue() should follow other paramerer names.

NOTE: This code is loosely based on on the techniques described in [Williamson, Alan R., "Java Servlets by Example", Manning, 1999]. However, we would advise against using the multipart code described in that book, since it contains a number of serious bugs.

Copyright: (c) 2002 The Open Math Company Limited

The Terms of Distribution of this software are stipulated in the javadoc Overview for this project.

Since:

J2SE 1.3

Version:

utilities-v011

Author:

Bruno Beloff bruno.beloff@opmath.com

See Also:

MultiFormException

Constructor Summary

MultiForm(HttpServletRequest req)
Constructs a MultiForm instance.

Method Summary

String	getNextParam() Used to identify the next parameter returned by the Web browser in the input stream.
String	getParamFilename() Returns the name of the file which was uploaded via the Web browser.
String	getParamName() Returns the name of the most recent parameter in the input stream - as encountered by getNextParam().
String	getParamValue() Returns the value of the most recent parameter in the input stream - as encountered by getNextParam().
void	writeParamValue(OutputStream outStrm) Used to write the uploaded file's contents to a file on the server.

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MultiForm

public MultiForm(HttpServletRequest req)
          throws MultiFormException

Constructs a MultiForm instance. The constructor attempts to establish an input stream using the request object. A MultiFormException is thrown if this cannot be done.

Parameters:

req - the javax.servlet.ServletRequest for the input stream.

Throws:

MultiFormException - An exception thrown if the ServletRequest was ill-formed.

Since:

J2SE 1.3

Method Detail

getParamFilename

public String getParamFilename()

Returns the name of the file which was uploaded via the Web browser. The file name is that given on the browser's local filesystem. If a file path was sent by the Web browser, it is removed (paths are not normally sent in any case).

NOTE: If the file has not yet been identified by the MultiPart (typically because the file parameter has not yet been encountered in the stream) then getParamFilename() returns null.

Returns:

a String containing the client's name for the file being uploaded.

Since:

J2SE 1.3

getParamName

public String getParamName()

Returns the name of the most recent parameter in the input stream - as encountered by getNextParam().

NOTE: If getNextParam() has not been invoked, then getParamName() returns null.

Returns:

a String containing the name of the most recently encountered parameter.

Since:

J2SE 1.3

getParamValue

public String getParamValue()
                     throws MultiFormException

Returns the value of the most recent parameter in the input stream - as encountered by getNextParam().

NOTE 1: Involking getParamValue() before getNextParam() will put the input stream out of sync, and is likely to have disasterous consequences.

NOTE 2: Do not use getParamValue() to access the uploaded file itself. This method is useful for accessing only the "conventional", single part parameters which may have been sent by the Web browser.

Returns:

a String containing the value of the most recently encountered parameter.

Throws:

MultiFormException - An exception thrown if the ServletRequest was ill-formed.

Since:

J2SE 1.3

getNextParam

public String getNextParam()
                    throws MultiFormException

Used to identify the next parameter returned by the Web browser in the input stream. If the parameter identifies the name of the uploaded file, then any path information is stripped away.

NOTE: getNextParam() has a side-effect of stepping through the input stream.

Returns:

a String containing the name of the most recently encountered parameter.

Throws:

MultiFormException - An exception thrown if the ServletRequest was ill-formed.

Since:

J2SE 1.3

writeParamValue

public void writeParamValue(OutputStream outStrm)
                     throws MultiFormException

Used to write the uploaded file's contents to a file on the server. It is the responsibilty of the programmer to ensure that this method is only invoked at the appropriate time, in other words when the name of the uploaded file has just been encountered. See the example code, above.

Parameters:

outStrm - the OutputStream for the file contents.

Throws:

MultiFormException - An exception thrown if the ServletRequest was ill-formed.

Since:

J2SE 1.3