com.instantbank.lettertemplate.control.web.handlers
Class MultipartRequest

java.lang.Object
  |
  +--com.instantbank.lettertemplate.control.web.handlers.MultipartRequest

public class MultipartRequest
extends java.lang.Object

A utility class to handle multipart/form-data requests, the kind of requests that support file uploads. This class can receive arbitrarily large files (up to an artificial limit you can set), and fairly efficiently too. It cannot handle nested data (multipart content within multipart content) or internationalized content (such as non Latin-1 filenames).

It's used like this:

 MultipartRequest multi = new MultipartRequest(req, ".");
  
 out.println("Params:");
 Enumeration params = multi.getParameterNames();
 while (params.hasMoreElements()) {
   String name = (String)params.nextElement();
   String value = multi.getParameter(name);
   out.println(name + " = " + value);
 }
 out.println();
  
 out.println("Files:");
 Enumeration files = multi.getFileNames();
 while (files.hasMoreElements()) {
   String name = (String)files.nextElement();
   String filename = multi.getFilesystemName(name);
   String type = multi.getContentType(name);
   File f = multi.getFile(name);
   out.println("name: " + name);
   out.println("filename: " + filename);
   out.println("type: " + type);
   if (f != null) {
     out.println("f.toString(): " + f.toString());
     out.println("f.getName(): " + f.getName());
     out.println("f.exists(): " + f.exists());
     out.println("f.length(): " + f.length());
     out.println();
   }
 }
 
A client can upload files using an HTML form with the following structure. Note that not all browsers support file uploads.
 <FORM ACTION="/servlet/Handler" METHOD=POST
          ENCTYPE="multipart/form-data">
 What is your name? <INPUT TYPE=TEXT NAME=submitter> <BR>
 Which file to upload? <INPUT TYPE=FILE NAME=file> <BR>
 <INPUT TYPE=SUBMIT>
 </FORM>
 

The full file upload specification is contained in experimental RFC 1867, available at http://www.ietf.org/rfc/rfc1867.txt .

Version:
1.6, 00/03/19, better WebSphere 2.x/3.x content type workaround
Author:
Jason Hunter , Copyright © 1998-1999

Field Summary
private static int DEFAULT_MAX_POST_SIZE
           
private  java.io.File dir
           
private  java.util.Hashtable files
           
private  int maxSize
           
private static java.lang.String NO_FILE
           
private  java.util.Hashtable parameters
           
private  javax.servlet.http.HttpServletRequest req
           
 
Constructor Summary
MultipartRequest(javax.servlet.http.HttpServletRequest request, java.lang.String saveDirectory)
          Constructs a new MultipartRequest to handle the specified request, saving any uploaded files to the given directory, and limiting the upload size to 1 Megabyte.
MultipartRequest(javax.servlet.http.HttpServletRequest request, java.lang.String saveDirectory, int maxPostSize)
          Constructs a new MultipartRequest to handle the specified request, saving any uploaded files to the given directory, and limiting the upload size to the specified length.
MultipartRequest(javax.servlet.ServletRequest request, java.lang.String saveDirectory)
          Constructor with an old signature, kept for backward compatibility.
MultipartRequest(javax.servlet.ServletRequest request, java.lang.String saveDirectory, int maxPostSize)
          Constructor with an old signature, kept for backward compatibility.
 
Method Summary
private  java.lang.String extractBoundary(java.lang.String line)
          Extracts and returns the boundary token from a line.
private  java.lang.String extractContentType(java.lang.String line)
          Extracts and returns the content type from a line, or null if the line was empty.
private  java.lang.String[] extractDispositionInfo(java.lang.String line)
          Extracts and returns disposition info from a line, as a String array with elements: disposition, name, filename.
 java.lang.String getContentType(java.lang.String name)
          Returns the content type of the specified file (as supplied by the client browser), or null if the file was not included in the upload.
 java.io.File getFile(java.lang.String name)
          Returns a File object for the specified file saved on the server's filesystem, or null if the file was not included in the upload.
 java.util.Enumeration getFileNames()
          Returns the names of all the uploaded files as an Enumeration of Strings.
 java.lang.String getFilesystemName(java.lang.String name)
          Returns the filesystem name of the specified file, or null if the file was not included in the upload.
 java.lang.String getParameter(java.lang.String name)
          Returns the value of the named parameter as a String, or null if the parameter was not sent or was sent without a value.
 java.util.Enumeration getParameterNames()
          Returns the names of all the parameters as an Enumeration of Strings.
 java.lang.String[] getParameterValues(java.lang.String name)
          Returns the values of the named parameter as a String array, or null if the parameter was not sent.
protected  void readAndSaveFile(MultipartInputStreamHandler in, java.lang.String boundary, java.lang.String filename, java.lang.String contentType)
          A utility method that reads a single part of the multipart request that represents a file, and saves the file to the given directory.
protected  boolean readNextPart(MultipartInputStreamHandler in, java.lang.String boundary)
          A utility method that reads an individual part.
protected  java.lang.String readParameter(MultipartInputStreamHandler in, java.lang.String boundary)
          A utility method that reads a single part of the multipart request that represents a parameter.
protected  void readRequest()
          The workhorse method that actually parses the request.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

DEFAULT_MAX_POST_SIZE

private static final int DEFAULT_MAX_POST_SIZE

NO_FILE

private static final java.lang.String NO_FILE

req

private javax.servlet.http.HttpServletRequest req

dir

private java.io.File dir

maxSize

private int maxSize

parameters

private java.util.Hashtable parameters

files

private java.util.Hashtable files
Constructor Detail

MultipartRequest

public MultipartRequest(javax.servlet.http.HttpServletRequest request,
                        java.lang.String saveDirectory)
                 throws java.io.IOException
Constructs a new MultipartRequest to handle the specified request, saving any uploaded files to the given directory, and limiting the upload size to 1 Megabyte. If the content is too large, an IOException is thrown. This constructor actually parses the multipart/form-data and throws an IOException if there's any problem reading or parsing the request.
Parameters:
request - the servlet request
saveDirectory - the directory in which to save any uploaded files
Throws:
java.io.IOException - Description of the Exception

MultipartRequest

public MultipartRequest(javax.servlet.http.HttpServletRequest request,
                        java.lang.String saveDirectory,
                        int maxPostSize)
                 throws java.io.IOException
Constructs a new MultipartRequest to handle the specified request, saving any uploaded files to the given directory, and limiting the upload size to the specified length. If the content is too large, an IOException is thrown. This constructor actually parses the multipart/form-data and throws an IOException if there's any problem reading or parsing the request.
Parameters:
request - the servlet request
saveDirectory - the directory in which to save any uploaded files
maxPostSize - the maximum size of the POST content
Throws:
java.io.IOException - Description of the Exception

MultipartRequest

public MultipartRequest(javax.servlet.ServletRequest request,
                        java.lang.String saveDirectory)
                 throws java.io.IOException
Constructor with an old signature, kept for backward compatibility. Without this constructor, a servlet compiled against a previous version of this class (pre 1.4) would have to be recompiled to link with this version. This constructor supports the linking via the old signature. Callers must simply be careful to pass in an HttpServletRequest.
Parameters:
request - Description of the Parameter
saveDirectory - Description of the Parameter
Throws:
java.io.IOException - Description of the Exception

MultipartRequest

public MultipartRequest(javax.servlet.ServletRequest request,
                        java.lang.String saveDirectory,
                        int maxPostSize)
                 throws java.io.IOException
Constructor with an old signature, kept for backward compatibility. Without this constructor, a servlet compiled against a previous version of this class (pre 1.4) would have to be recompiled to link with this version. This constructor supports the linking via the old signature. Callers must simply be careful to pass in an HttpServletRequest.
Parameters:
request - Description of the Parameter
saveDirectory - Description of the Parameter
maxPostSize - Description of the Parameter
Throws:
java.io.IOException - Description of the Exception
Method Detail

getParameterNames

public java.util.Enumeration getParameterNames()
Returns the names of all the parameters as an Enumeration of Strings. It returns an empty Enumeration if there are no parameters.
Returns:
the names of all the parameters as an Enumeration of Strings

getFileNames

public java.util.Enumeration getFileNames()
Returns the names of all the uploaded files as an Enumeration of Strings. It returns an empty Enumeration if there are no uploaded files. Each file name is the name specified by the form, not by the user.
Returns:
the names of all the uploaded files as an Enumeration of Strings

getParameter

public java.lang.String getParameter(java.lang.String name)
Returns the value of the named parameter as a String, or null if the parameter was not sent or was sent without a value. The value is guaranteed to be in its normal, decoded form. If the parameter has multiple values, only the last one is returned (for backward compatibility). For parameters with multiple values, it's possible the last "value" may be null.
Parameters:
name - the parameter name
Returns:
the parameter value

getParameterValues

public java.lang.String[] getParameterValues(java.lang.String name)
Returns the values of the named parameter as a String array, or null if the parameter was not sent. The array has one entry for each parameter field sent. If any field was sent without a value that entry is stored in the array as a null. The values are guaranteed to be in their normal, decoded form. A single value is returned as a one-element array.
Parameters:
name - the parameter name
Returns:
the parameter values

getFilesystemName

public java.lang.String getFilesystemName(java.lang.String name)
Returns the filesystem name of the specified file, or null if the file was not included in the upload. A filesystem name is the name specified by the user. It is also the name under which the file is actually saved.
Parameters:
name - the file name
Returns:
the filesystem name of the file

getContentType

public java.lang.String getContentType(java.lang.String name)
Returns the content type of the specified file (as supplied by the client browser), or null if the file was not included in the upload.
Parameters:
name - the file name
Returns:
the content type of the file

getFile

public java.io.File getFile(java.lang.String name)
Returns a File object for the specified file saved on the server's filesystem, or null if the file was not included in the upload.
Parameters:
name - the file name
Returns:
a File object for the named file

readRequest

protected void readRequest()
                    throws java.io.IOException
The workhorse method that actually parses the request. A subclass can override this method for a better optimized or differently behaved implementation.
Throws:
java.io.IOException - if the uploaded content is larger than maxSize or there's a problem parsing the request

readNextPart

protected boolean readNextPart(MultipartInputStreamHandler in,
                               java.lang.String boundary)
                        throws java.io.IOException
A utility method that reads an individual part. Dispatches to readParameter() and readAndSaveFile() methods to do the actual work.

A subclass can override this method for a better optimized or differently behaved implementation.

Parameters:
in - the stream from which to read the part
boundary - the boundary separating parts
Returns:
a flag indicating whether this is the last part
Throws:
java.io.IOException - if there's a problem reading or parsing the request.

readParameter

protected java.lang.String readParameter(MultipartInputStreamHandler in,
                                         java.lang.String boundary)
                                  throws java.io.IOException
A utility method that reads a single part of the multipart request that represents a parameter. A subclass can override this method for a better optimized or differently behaved implementation.
Parameters:
in - the stream from which to read the parameter information
boundary - the boundary signifying the end of this part
Returns:
the parameter value
Throws:
java.io.IOException - if there's a problem reading or parsing the request

readAndSaveFile

protected void readAndSaveFile(MultipartInputStreamHandler in,
                               java.lang.String boundary,
                               java.lang.String filename,
                               java.lang.String contentType)
                        throws java.io.IOException
A utility method that reads a single part of the multipart request that represents a file, and saves the file to the given directory. A subclass can override this method for a better optimized or differently behaved implementation.
Parameters:
in - the stream from which to read the file
boundary - the boundary signifying the end of this part
filename - the name under which to save the uploaded file
contentType - Description of the Parameter
Throws:
java.io.IOException - if there's a problem reading or parsing the request

extractBoundary

private java.lang.String extractBoundary(java.lang.String line)
Extracts and returns the boundary token from a line.
Parameters:
line - Description of the Parameter
Returns:
Description of the Return Value

extractDispositionInfo

private java.lang.String[] extractDispositionInfo(java.lang.String line)
                                           throws java.io.IOException
Extracts and returns disposition info from a line, as a String array with elements: disposition, name, filename. Throws an IOException if the line is malformatted.
Parameters:
line - Description of the Parameter
Returns:
Description of the Return Value
Throws:
java.io.IOException - Description of the Exception

extractContentType

private java.lang.String extractContentType(java.lang.String line)
                                     throws java.io.IOException
Extracts and returns the content type from a line, or null if the line was empty. Throws an IOException if the line is malformatted.
Parameters:
line - Description of the Parameter
Returns:
Description of the Return Value
Throws:
java.io.IOException - Description of the Exception