http.utils.multipartrequest

Class MultipartRequest

Known Direct Subclasses:
CgiMultipartRequest, 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-2003 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

Field Summary

static int
ABORT_IF_MAX_BYES_EXCEEDED
Mode
static int
CONTENTS
static int
CONTENT_TYPE
static String
DEF_ENCODING
static int
FILENAME
Define the array indexes for the htFiles Object array.
static int
IGNORE_FILES_IF_MAX_BYES_EXCEEDED
static int
MAX_READ_BYTES
Prevent a denial of service by defining this, will never read more data.
static int
RAW_FILENAME
static int
READ_LINE_BLOCK
Defines the number of bytes to read per readLine call.
static int
SIZE
static int
TMP_FILENAME

Constructor Summary

MultipartRequest(PrintWriter debug, String strContentTypeText, int intContentLength, InputStream in, String strSaveDirectory)
Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, String, int, boolean, String)
MultipartRequest(PrintWriter debug, String strContentTypeText, int intContentLength, InputStream in, String strSaveDirectory, int intMaxReadBytes)
Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, String, int, boolean, String)
MultipartRequest(PrintWriter debug, String strContentTypeText, int intContentLength, InputStream in, String strSaveDirectory, int intMaxReadBytes, String encoding)
Standard Constructor
MultipartRequest(PrintWriter debug, String strContentTypeText, int intContentLength, InputStream in, String strSaveDirectory, int intMaxReadBytes, int maxBytesExceededMode, String encoding)
Standard Constructor
MultipartRequest(PrintWriter debug, String strContentTypeText, int intContentLength, InputStream in, int intMaxReadBytes)
Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, int, boolean, String)
MultipartRequest(PrintWriter debug, String strContentTypeText, int intContentLength, InputStream in, int intMaxReadBytes, String encoding)
Memory Constructor
MultipartRequest(PrintWriter debug, String strContentTypeText, int intContentLength, InputStream in, int intMaxReadBytes, int maxBytesExceededMode, String encoding)
Memory Constructor
MultipartRequest(String strContentTypeText, int intContentLength, InputStream in, String strSaveDirectory)
Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, String, int, boolean, String)
MultipartRequest(String strContentTypeText, int intContentLength, InputStream in, String strSaveDirectory, int intMaxReadBytes)
Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, String, int, boolean, String)

Method Summary

protected void
debug(String x)
Use when debugging this object.
String
getBaseFilename(String strName)
Get the uploaded file basename.
String
getContentType(String strName)
Returns the Content-Type of a file.
String
getEncoding()
Returns the current encoding method.
File
getFile(String strName)
Returns a File reference to the uploaded file.
InputStream
getFileContents(String strName)
If files were uploaded into memory, this method will retrieve the contents of the file as a InputStream.
Object
getFileParameter(String strName, int type)
Access an attribute of a file upload parameter record.
Enumeration
getFileParameterNames()
This enumeration will return all INPUT TYPE=FILE parameter NAMES as encountered during the upload.
long
getFileSize(String strName)
Returns the File Size of a uploaded file.
String
getFileSystemName(String strName)
Deprecated. Replaced by getBaseFilename(String)
String
getHtmlTable()
For debugging.
Enumeration
getParameterNames()
An enumeration of all URL Parameters for the current HTTP Request.
String
getRawFilename(String strName)
Get the uploaded file basename.
String
getURLParameter(String strName)
Return the value of the strName URLParameter.
Enumeration
getURLParameters(String strName)
Return an enumeration of all values for the strName parameter.
boolean
isMaxBytesExceeded()
If this class was constructed with a maxBytesExceeded mode of MultipartRequest.IGNORE_FILES_IF_MAX_BYES_EXCEEDED, this method will indicate whether the process is ignoring file content because the content-length was exceeded.
void
setEncoding(String enc)
Sets up the encoding for this instance of multipartrequest.

Field Details

ABORT_IF_MAX_BYES_EXCEEDED

public static final int ABORT_IF_MAX_BYES_EXCEEDED
Mode
Field Value:
100

CONTENTS

public static final int CONTENTS
Field Value:
3

CONTENT_TYPE

public static final int CONTENT_TYPE
Field Value:
1

DEF_ENCODING

public static final String DEF_ENCODING

FILENAME

public static final int FILENAME
Define the array indexes for the htFiles Object array.
Field Value:
0

IGNORE_FILES_IF_MAX_BYES_EXCEEDED

public static final int IGNORE_FILES_IF_MAX_BYES_EXCEEDED
Field Value:
101

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.
Field Value:
2097152

RAW_FILENAME

public static final int RAW_FILENAME
Field Value:
5

READ_LINE_BLOCK

public static final int READ_LINE_BLOCK
Defines the number of bytes to read per readLine call. 128K
Field Value:
131072

SIZE

public static final int SIZE
Field Value:
2

TMP_FILENAME

public static final int TMP_FILENAME
Field Value:
4

Constructor Details

MultipartRequest

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

Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, String, int, boolean, String)

Standard 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.

MultipartRequest

public MultipartRequest(PrintWriter debug,
                        String strContentTypeText,
                        int intContentLength,
                        InputStream in,
                        String strSaveDirectory,
                        int intMaxReadBytes)
            throws IllegalArgumentException,
                   IOException,
                   UnsupportedEncodingException

Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, String, int, boolean, String)

Standard 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.

MultipartRequest

public MultipartRequest(PrintWriter debug,
                        String strContentTypeText,
                        int intContentLength,
                        InputStream in,
                        String strSaveDirectory,
                        int intMaxReadBytes,
                        String encoding)
            throws IllegalArgumentException,
                   IOException,
                   UnsupportedEncodingException
Standard 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.
encoding - Sets the encoding to use. If null, ISO-8859-1 will be used.

MultipartRequest

public MultipartRequest(PrintWriter debug,
                        String strContentTypeText,
                        int intContentLength,
                        InputStream in,
                        String strSaveDirectory,
                        int intMaxReadBytes,
                        int maxBytesExceededMode,
                        String encoding)
            throws IllegalArgumentException,
                   IOException,
                   UnsupportedEncodingException
Standard 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.
maxBytesExceededMode - This controls how the parser will process a request which is in excess of the intMaxReadBytes parameter. The possible modes are:
  • MultipartRequest.ABORT_IF_MAX_BYES_EXCEEDED - The parser will throw a MaxBytesReadException
  • MultipartRequest.IGNORE_FILES_IF_MAX_BYES_EXCEEDED - All parameters will be processed, but any file content will be discarded. Be warned that there is still potential for Denial-of-Service, if an attacker decided to send megabytes of non-file form data.
    encoding - Sets the encoding to use. If null, ISO-8859-1 will be used.

    MultipartRequest

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

    Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, int, boolean, String)

    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.

    MultipartRequest

    public MultipartRequest(PrintWriter debug,
                            String strContentTypeText,
                            int intContentLength,
                            InputStream in,
                            int intMaxReadBytes,
                            String encoding)
                throws IllegalArgumentException,
                       IOException,
                       UnsupportedEncodingException
    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.
    encoding - Sets the encoding to use. If null, ISO-8859-1 will be used.

    MultipartRequest

    public MultipartRequest(PrintWriter debug,
                            String strContentTypeText,
                            int intContentLength,
                            InputStream in,
                            int intMaxReadBytes,
                            int maxBytesExceededMode,
                            String encoding)
                throws IllegalArgumentException,
                       IOException,
                       UnsupportedEncodingException
    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.
    maxBytesExceededMode - This controls how the parser will process a request which is in excess of the intMaxReadBytes parameter. The possible modes are:
    • MultipartRequest.ABORT_IF_MAX_BYES_EXCEEDED - The parser will throw a MaxBytesReadException
    • MultipartRequest.IGNORE_FILES_IF_MAX_BYES_EXCEEDED - All parameters will be processed, but any file content will be discarded. WARNING: There is still potential for a Denial-of-Service. For instance, an attacker can send many megabytes of non-file form data.
      encoding - Sets the encoding to use. If null, ISO-8859-1 will be used.

      MultipartRequest

      public MultipartRequest(String strContentTypeText,
                              int intContentLength,
                              InputStream in,
                              String strSaveDirectory)
                  throws IllegalArgumentException,
                         IOException

      Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, String, int, boolean, String)

      Standard 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

      MultipartRequest

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

      Deprecated. Replaced by MultipartRequest(PrintWriter, String, int, InputStream, String, int, boolean, String)

      Standard 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.

      Method Details

      debug

      protected void debug(String x)
      Use when debugging this object.

      getBaseFilename

      public String getBaseFilename(String strName)
      Get the uploaded file basename. This is the basename of the file which was provided by the browser itself when the file was chosen using the 'Browse...' button of the <input type=file ...> input field.
      Returns:
      null if strName not found.
      See Also:
      getFileParameter(java.lang.String, int)

      getContentType

      public String getContentType(String strName)
      Returns the Content-Type of a file.
      See Also:
      getFileParameter(java.lang.String, int)

      getEncoding

      public String getEncoding()
      Returns the current encoding method.

      getFile

      public File getFile(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)

      getFileContents

      public InputStream getFileContents(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)

      getFileParameter

      public Object getFileParameter(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,
      MultipartRequest.TMP_FILENAME
      MultipartRequest.RAW_FILENAME
      

      The getBaseFilename(),getFile(),getFileSize(),getContentType(),getContents() 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), getFile(java.lang.String), getBaseFilename(java.lang.String)

      getFileParameterNames

      public Enumeration getFileParameterNames()
      This enumeration will return all INPUT TYPE=FILE parameter NAMES as encountered during the upload.

      getFileSize

      public long getFileSize(String strName)
      Returns the File Size of a uploaded file.
      Returns:
      -1 if file size not defined.
      See Also:
      getFileParameter(java.lang.String, int)

      getFileSystemName

      public String getFileSystemName(String strName)

      Deprecated. Replaced by getBaseFilename(String)


      getHtmlTable

      public String getHtmlTable()
      For debugging. Be aware that if you have a form with multiple FILE input types of the same name, only the first one will actually be returned from the getFileParameter(...) method, which all the file access methods call. So if your upload file was actually uploaded against the second file input field, then it will not be accessible, via the methods.

      getParameterNames

      public Enumeration getParameterNames()
      An enumeration of all URL Parameters for the current HTTP Request.

      getRawFilename

      public String getRawFilename(String strName)
      Get the uploaded file basename. This is the file which was provided by the browser itself when the file was chosen using the 'Browse...' button of the <input type=file ...> input field.
      Returns:
      null if strName not found.
      See Also:
      getFileParameter(java.lang.String, int)

      getURLParameter

      public String getURLParameter(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 Enumeration getURLParameters(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 not value was encountered for strName or it is an invalid parameter name.

      isMaxBytesExceeded

      public boolean isMaxBytesExceeded()
      If this class was constructed with a maxBytesExceeded mode of MultipartRequest.IGNORE_FILES_IF_MAX_BYES_EXCEEDED, this method will indicate whether the process is ignoring file content because the content-length was exceeded.

      setEncoding

      public void setEncoding(String enc)
                  throws UnsupportedEncodingException
      Sets up the encoding for this instance 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.