org.millstone.webadapter
Class MultipartRequest

java.lang.Object
  |
  +--org.millstone.webadapter.MultipartRequest

Direct Known Subclasses:

ServletMultipartRequest

public class MultipartRequest

extends java.lang.Object

A Multipart form data parser. Parses an input stream and writes out any files found, making available a hashtable of other url parameters. As of version 1.17 the files can be saved to memory, and optionally written to a database, etc.

Copyright (C)2001 Jason Pell.

        This library is free software; you can redistribute it and/or
        modify it under the terms of the GNU Lesser General Public
        License as published by the Free Software Foundation; either
        version 2.1 of the License, or (at your option) any later version.
        

        This library is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
        Lesser General Public License for more details.
        

        You should have received a copy of the GNU Lesser General Public
        License along with this library; if not, write to the Free Software
        Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
        
	
        Email: 	jasonpell@hotmail.com
        Url:	http://www.geocities.com/jasonpell
        

Version:

1.18 Fixed some serious bugs. A new method readAndWrite(InputStream in, OutputStream out) which now does the generic processing in common for readAndWriteFile and readFile. The differences are that now the two extra bytes at the end of a file upload are processed once, instead of after each line. Also if an empty file is encountered, an outputstream is opened, but then deleted if no data written to it. The getCharArray() method has been removed. Replaced by the new String(bytes, encoding) method using a specific encoding (Defaults to ISO-8859-1) to ensure that extended characters are supported. All strings are processed using this encoding. The addition of static methods setEncoding(String) and getEncoding() to allow the use of MultipartRequest with a specific encoding type. All instances of MultipartRequest will utilise the static charEncoding variable value, that the setEncoding() method can be used to set. Started to introduce support for multiple file uploads with the same form field name, but not completed for v1.18. 26/06/2001, 1.17 A few _very_ minor fixes. Plus a cool new feature added. The ability to save files into memory. Thanks to Mark Latham for the idea and some of the code. 11/04/2001, 1.16 Added support for multiple parameter values. Also fixed getCharArray(...) method to support parameters with non-english ascii values (ascii above 127). Thanks to Stefan Schmidt & Michael Elvers for this. (No fix yet for reported problems with Tomcat 3.2 or a single extra byte appended to uploads of certain files). By 1.17 hopefully will have a resolution for the second problem. 14/03/2001, 1.15 A new parameter added, intMaxReadBytes, to allow arbitrary length files. Released under the LGPL (Lesser General Public License). 03/02/2001, 1.14 Fix for IE problem with filename being empty. This is because IE includes a default Content-Type even when no file is uploaded. 16/02/2001, 1.13 If an upload directory is not specified, then all file contents are sent into oblivion, but the rest of the parsing works as normal., 1.12 Fix, was allowing zero length files. Will not even create the output file until there is something to write. getFile(String) now returns null, if a zero length file was specified. 06/11/2000, 1.11 Fix, in case Content-type is not specified., 1.1 Removed dependence on Servlets. Now passes in a generic InputStream instead. "Borrowed" readLine from Tomcat 3.1 ServletInputStream class, so we can remove some of the dependencies on ServletInputStream. Fixed bug where a empty INPUT TYPE="FILE" value, would cause an exception., 1.0 Initial Release.

Author:

Jason Pell

Field Summary

static int	CONTENT_TYPE Type constant for the File CONTENT_TYPE.
static int	CONTENTS Type constant for the File CONTENTS.
static int	FILENAME Type constant for File FILENAME.
static int	MAX_READ_BYTES Prevent a denial of service by defining this, will never read more data.
static int	READ_LINE_BLOCK Defines the number of bytes to read per readLine call. 128K
static int	SIZE Type constant for the File SIZE.

Constructor Summary

MultipartRequest(java.io.PrintWriter debug, java.lang.String strContentTypeText, int intContentLength, java.io.InputStream in, int intMaxReadBytes)
Constructor - load into memory constructor

MultipartRequest(java.io.PrintWriter debug, java.lang.String strContentTypeText, int intContentLength, java.io.InputStream in, java.lang.String strSaveDirectory)
Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, int) You can specify MultipartRequest.MAX_READ_BYTES for the intMaxReadBytes parameter

MultipartRequest(java.io.PrintWriter debug, java.lang.String strContentTypeText, int intContentLength, java.io.InputStream in, java.lang.String strSaveDirectory, int intMaxReadBytes)
Constructor.

MultipartRequest(java.lang.String strContentTypeText, int intContentLength, java.io.InputStream in, java.lang.String strSaveDirectory)
Constructor.

MultipartRequest(java.lang.String strContentTypeText, int intContentLength, java.io.InputStream in, java.lang.String strSaveDirectory, int intMaxReadBytes)
Constructor.

Method Summary

protected void	debug(java.lang.String x) Use when debugging this object.
java.lang.String	getContentType(java.lang.String strName) Returns the Content-Type of a file.
java.lang.String	getEncoding() Returns the current encoding method.
java.io.File	getFile(java.lang.String strName) Returns a File reference to the uploaded file.
java.io.InputStream	getFileContents(java.lang.String strName) If files were uploaded into memory, this method will retrieve the contents of the file as a InputStream.
java.lang.Object	getFileParameter(java.lang.String strName, int type) Access an attribute of a file upload parameter record.
java.util.Enumeration	getFileParameterNames() This enumeration will return all INPUT TYPE=FILE parameter NAMES as encountered during the upload.
long	getFileSize(java.lang.String strName) Returns the File Size of a uploaded file.
java.lang.String	getFileSystemName(java.lang.String strName) Get the file system basename of an uploaded file.
java.lang.String	getHtmlTable() For debugging.
java.util.Enumeration	getParameterNames() An enumeration of all URL Parameters for the current HTTP Request.
java.lang.String	getURLParameter(java.lang.String strName) Return the value of the strName URLParameter.
java.util.Enumeration	getURLParameters(java.lang.String strName) Return an enumeration of all values for the strName parameter.
void	setEncoding(java.lang.String enc) This method should be called on the MultipartRequest itself, not on any instances of MultipartRequest, because this sets up the encoding for all instances of multipartrequest.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_READ_BYTES

public static final int MAX_READ_BYTES

Prevent a denial of service by defining this, will never read more data. If Content-Length is specified to be more than this, will throw an exception. This limits the maximum number of bytes to the value of an int, which is 2 Gigabytes.

See Also:

Constant Field Values

READ_LINE_BLOCK

public static final int READ_LINE_BLOCK

Defines the number of bytes to read per readLine call. 128K

See Also:

Constant Field Values

FILENAME

public static final int FILENAME

Type constant for File FILENAME.

See Also:

Constant Field Values

CONTENT_TYPE

public static final int CONTENT_TYPE

Type constant for the File CONTENT_TYPE.

See Also:

Constant Field Values

SIZE

public static final int SIZE

Type constant for the File SIZE.

See Also:

Constant Field Values

CONTENTS

public static final int CONTENTS

Type constant for the File CONTENTS. Note: Only used for file upload to memory.

See Also:

Constant Field Values

Constructor Detail

MultipartRequest

public MultipartRequest(java.lang.String strContentTypeText,
                        int intContentLength,
                        java.io.InputStream in,
                        java.lang.String strSaveDirectory)
                 throws java.lang.IllegalArgumentException,
                        java.io.IOException

Constructor.

Parameters:

strContentTypeText - The "Content-Type" HTTP header value.

intContentLength - The "Content-Length" HTTP header value.

in - The InputStream to read and parse.

strSaveDirectory - The temporary directory to save the file from where they can then be moved to wherever by the calling process. If you specify null for this parameter, then any files uploaded will be silently ignored.

Throws:

java.lang.IllegalArgumentException - If the strContentTypeText does not contain a Content-Type of "multipart/form-data" or the boundary is not found.

java.io.IOException - If the intContentLength is higher than MAX_READ_BYTES or strSaveDirectory is invalid or cannot be written to.

See Also:

MAX_READ_BYTES

MultipartRequest

public MultipartRequest(java.lang.String strContentTypeText,
                        int intContentLength,
                        java.io.InputStream in,
                        java.lang.String strSaveDirectory,
                        int intMaxReadBytes)
                 throws java.lang.IllegalArgumentException,
                        java.io.IOException

Constructor.

Parameters:

strContentTypeText - The "Content-Type" HTTP header value.

intContentLength - The "Content-Length" HTTP header value.

in - The InputStream to read and parse.

strSaveDirectory - The temporary directory to save the file from where they can then be moved to wherever by the calling process. If you specify null for this parameter, then any files uploaded will be silently ignored.

intMaxReadBytes - Overrides the MAX_BYTES_READ value, to allow arbitrarily long files.

Throws:

java.lang.IllegalArgumentException - If the strContentTypeText does not contain a Content-Type of "multipart/form-data" or the boundary is not found.

java.io.IOException - If the intContentLength is higher than MAX_READ_BYTES or strSaveDirectory is invalid or cannot be written to.

See Also:

MAX_READ_BYTES

MultipartRequest

public MultipartRequest(java.io.PrintWriter debug,
                        java.lang.String strContentTypeText,
                        int intContentLength,
                        java.io.InputStream in,
                        java.lang.String strSaveDirectory)
                 throws java.lang.IllegalArgumentException,
                        java.io.IOException

Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, int) You can specify MultipartRequest.MAX_READ_BYTES for the intMaxReadBytes parameter

Constructor.

Parameters:

debug - A PrintWriter that can be used for debugging.

strContentTypeText - The "Content-Type" HTTP header value.

intContentLength - The "Content-Length" HTTP header value.

in - The InputStream to read and parse.

strSaveDirectory - The temporary directory to save the file from where they can then be moved to wherever by the calling process. If you specify null for this parameter, then any files uploaded will be silently ignored.

Throws:

java.lang.IllegalArgumentException - If the strContentTypeText does not contain a Content-Type of "multipart/form-data" or the boundary is not found.

java.io.IOException - If the intContentLength is higher than MAX_READ_BYTES or strSaveDirectory is invalid or cannot be written to.

See Also:

MAX_READ_BYTES

MultipartRequest

public MultipartRequest(java.io.PrintWriter debug,
                        java.lang.String strContentTypeText,
                        int intContentLength,
                        java.io.InputStream in,
                        int intMaxReadBytes)
                 throws java.lang.IllegalArgumentException,
                        java.io.IOException

Constructor - load into memory constructor

Parameters:

debug - A PrintWriter that can be used for debugging.

strContentTypeText - The "Content-Type" HTTP header value.

intContentLength - The "Content-Length" HTTP header value.

in - The InputStream to read and parse.

intMaxReadBytes - Overrides the MAX_BYTES_READ value, to allow arbitrarily long files.

Throws:

java.lang.IllegalArgumentException - If the strContentTypeText does not contain a Content-Type of "multipart/form-data" or the boundary is not found.

java.io.IOException - If the intContentLength is higher than MAX_READ_BYTES or strSaveDirectory is invalid or cannot be written to.

See Also:

MAX_READ_BYTES

MultipartRequest

public MultipartRequest(java.io.PrintWriter debug,
                        java.lang.String strContentTypeText,
                        int intContentLength,
                        java.io.InputStream in,
                        java.lang.String strSaveDirectory,
                        int intMaxReadBytes)
                 throws java.lang.IllegalArgumentException,
                        java.io.IOException

Constructor.

Parameters:

debug - A PrintWriter that can be used for debugging.

strContentTypeText - The "Content-Type" HTTP header value.

intContentLength - The "Content-Length" HTTP header value.

in - The InputStream to read and parse.

strSaveDirectory - The temporary directory to save the file from where they can then be moved to wherever by the calling process. If you specify null for this parameter, then any files uploaded will be silently ignored.

intMaxReadBytes - Overrides the MAX_BYTES_READ value, to allow arbitrarily long files.

Throws:

java.lang.IllegalArgumentException - If the strContentTypeText does not contain a Content-Type of "multipart/form-data" or the boundary is not found.

java.io.IOException - If the intContentLength is higher than MAX_READ_BYTES or strSaveDirectory is invalid or cannot be written to.

See Also:

MAX_READ_BYTES

Method Detail

setEncoding

public void setEncoding(java.lang.String enc)
                 throws java.io.UnsupportedEncodingException

This method should be called on the MultipartRequest itself, not on any instances of MultipartRequest, because this sets up the encoding for all instances of multipartrequest. You can set the encoding to null, in which case the default encoding will be applied. The default encoding if this method is not called has been set to ISO-8859-1, which seems to offer the best hope of support for international characters, such as german "Umlaut" characters.

Warning: In multithreaded environments it is the responsibility of the implementer to make sure that this method is not called while another instance is being constructed. When an instance of MultipartRequest is constructed, it parses the input data, and uses the result of getEncoding() to convert between bytes and strings. If setEncoding() is called by another thread, while the private parse() is executing, the method will utilise this new encoding, which may cause serious problems.

java.io.UnsupportedEncodingException

getEncoding

public java.lang.String getEncoding()

Returns the current encoding method.

getURLParameter

public java.lang.String getURLParameter(java.lang.String strName)

Return the value of the strName URLParameter. If more than one value for a particular Parameter, will return the first. If an error occurs will return null.

getURLParameters

public java.util.Enumeration getURLParameters(java.lang.String strName)

Return an enumeration of all values for the strName parameter. Even if a single value for, will always return an enumeration, although it may actually be empty if no value was encountered for strName or it is an invalid parameter name.

getParameterNames

public java.util.Enumeration getParameterNames()

An enumeration of all URL Parameters for the current HTTP Request.

getFileParameterNames

public java.util.Enumeration getFileParameterNames()

This enumeration will return all INPUT TYPE=FILE parameter NAMES as encountered during the upload.

getContentType

public java.lang.String getContentType(java.lang.String strName)

Returns the Content-Type of a file.

See Also:

getFileParameter(java.lang.String, int)

getFileContents

public java.io.InputStream getFileContents(java.lang.String strName)

If files were uploaded into memory, this method will retrieve the contents of the file as a InputStream.

Returns:

the contents of the file as a InputStream, or null if not file uploaded, or file uploaded to file system directory.

See Also:

getFileParameter(java.lang.String, int)

getFile

public java.io.File getFile(java.lang.String strName)

Returns a File reference to the uploaded file. This reference is to the files uploaded location, and allows you to read/move/delete the file. This method is only of use, if files were uploaded to the file system. Will return null if uploaded to memory, in which case you should use getFileContents(strName) instead.

Returns:

Returns a null file reference if a call to getFileSize(strName) returns zero or files were uploaded to memory.

See Also:

getFileSize(java.lang.String), getFileContents(java.lang.String), getFileSystemName(java.lang.String)

getFileSystemName

public java.lang.String getFileSystemName(java.lang.String strName)

Get the file system basename of an uploaded file.

Returns:

null if strName not found.

See Also:

getFileParameter(java.lang.String, int)

getFileSize

public long getFileSize(java.lang.String strName)

Returns the File Size of a uploaded file.

Returns:

-1 if file size not defined.

See Also:

getFileParameter(java.lang.String, int)

getFileParameter

public java.lang.Object getFileParameter(java.lang.String strName,
                                         int type)

Access an attribute of a file upload parameter record.

Parameters:

strName - is the form field name, used to upload the file. This identifies the formfield location in the storage facility.

type - What attribute you want from the File Parameter. The following types are supported: MultipartRequest.FILENAME, MultipartRequest.CONTENT_TYPE, MultipartRequest.SIZE, MultipartRequest.CONTENTS

The getFileSystemName(String strName),getFileSize(String strName),getContentType(String strName), getContents(String strName) methods all use this method passing in a different type argument.

Note: This class has been changed to provide for future functionality where you will be able to access all files uploaded, even if they are uploaded using the same form field name. At this point however, only the first file uploaded via a form field name is accessible.

See Also:

getContentType(java.lang.String), getFileSize(java.lang.String), getFileContents(java.lang.String), getFileSystemName(java.lang.String)

debug

protected void debug(java.lang.String x)

Use when debugging this object.

getHtmlTable

public java.lang.String getHtmlTable()

For debugging.