All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class util.MultipartRequest 

java.lang.Object
   |
   +----util.MultipartRequest
public class MultipartRequest
extends 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.

Constructor Index

o MultipartRequest(HttpServletRequest, String)
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.
o MultipartRequest(HttpServletRequest, String, int)
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.
o MultipartRequest(ServletRequest, String)
Constructor with an old signature, kept for backward compatibility.
o MultipartRequest(ServletRequest, String, int)
Constructor with an old signature, kept for backward compatibility.

Method Index

o getContentType(String)
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.
o getFile(String)
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.
o getFileNames()
Returns the names of all the uploaded files as an Enumeration of Strings.
o getFilesystemName(String)
Returns the filesystem name of the specified file, or null if the file was not included in the upload.
o getParameter(String)
Returns the value of the named parameter as a String, or null if the parameter was not sent or was sent without a value.
o getParameterNames()
Returns the names of all the parameters as an Enumeration of Strings.
o getParameterValues(String)
Returns the values of the named parameter as a String array, or null if the parameter was not sent.
o readAndSaveFile(MultipartInputStreamHandler, String, String, String)
A utility method that reads a single part of the multipart request that represents a file, and saves the file to the given directory.
o readNextPart(MultipartInputStreamHandler, String)
A utility method that reads an individual part.
o readParameter(MultipartInputStreamHandler, String)
A utility method that reads a single part of the multipart request that represents a parameter.
o readRequest()
The workhorse method that actually parses the request.

Constructors

o MultipartRequest 
 public MultipartRequest(HttpServletRequest request,
                         String saveDirectory) throws 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: IOException
if the uploaded content is larger than 1 Megabyte or there's a problem reading or parsing the request
o MultipartRequest 
 public MultipartRequest(HttpServletRequest request,
                         String saveDirectory,
                         int maxPostSize) throws 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: IOException
if the uploaded content is larger than maxPostSize or there's a problem reading or parsing the request
o MultipartRequest 
 public MultipartRequest(ServletRequest request,
                         String saveDirectory) throws 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.

o MultipartRequest 
 public MultipartRequest(ServletRequest request,
                         String saveDirectory,
                         int maxPostSize) throws 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.

Methods

o getParameterNames 
 public 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
o getFileNames 
 public 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
o getParameter 
 public String getParameter(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
o getParameterValues 
 public String[] getParameterValues(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
o getFilesystemName 
 public String getFilesystemName(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
o getContentType 
 public String getContentType(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
o getFile 
 public File getFile(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
o readRequest 
 protected void readRequest() throws IOException
The workhorse method that actually parses the request. A subclass can override this method for a better optimized or differently behaved implementation.

Throws: IOException
if the uploaded content is larger than maxSize or there's a problem parsing the request
o readNextPart 
 protected boolean readNextPart(MultipartInputStreamHandler in,
                                String boundary) throws IOException
A utility method that reads an individual part. Dispatches to readParameter() and readAndSaveFile() 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: IOException
if there's a problem reading or parsing the request
See Also:
readParameter, readAndSaveFile
o readParameter 
 protected String readParameter(MultipartInputStreamHandler in,
                                String boundary) throws 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: IOException
if there's a problem reading or parsing the request
o readAndSaveFile 
 protected void readAndSaveFile(MultipartInputStreamHandler in,
                                String boundary,
                                String filename,
                                String contentType) throws 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
dir - the directory in which to save the uploaded file
filename - the name under which to save the uploaded file
Throws: IOException
if there's a problem reading or parsing the request 
All Packages  Class Hierarchy  This Package  Previous  Next  Index