oracle.clex.util
Class MultipartRequest

java.lang.Object
  |
  +--oracle.clex.util.MultipartRequest

All Implemented Interfaces:

java.io.Serializable

public class MultipartRequest

extends java.lang.Object

implements java.io.Serializable

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://ds.internic.net/rfc/rfc1867.txt.

See Also:

Serialized Form

Field Summary

protected static int

DEFAULT_MAX_POST_SIZE

Constructor Summary

MultipartRequest()
Empty constructor

MultipartRequest(javax.servlet.ServletRequest 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.ServletRequest 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.

Method Summary

protected void	addFile(java.lang.Object fileKey, java.lang.Object file) Add a file to the file Hashtable.
protected void	addParam(java.lang.Object paramKey, java.lang.Object paramValue) Add to the parameters hashtable
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.
protected java.util.Hashtable	getFilesHashtable() Returns the files Hashtable so that subclasses can access it if methods that populates this hashtable is overridden
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.
protected int	getMaxPostSize() Returns the max post size setting
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 given.
java.util.Enumeration	getParameterNames() Returns the names of all the parameters as an Enumeration of Strings.
protected java.util.Hashtable	getParametersHashtable() Returns the parameters Hashtable so that subclasses can access it if methods that populates this hashtable is overridden
protected javax.servlet.ServletRequest	getServletRequest() Returns the servlet request that contains the multipart request
protected java.lang.String	getSessionId() Returns a String representing the id of the session associated with the servletRequest attribute.
protected java.io.File	getUploadDirectory() Returns the upload directory
java.lang.String	makeUnique(java.lang.String aString) Returns a unique string version of the specified string by prepending the session id to it.
protected void	readAndSaveFile(oracle.clex.util.MultipartInputStreamHandler in, java.lang.String boundary, java.lang.String filename) 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(oracle.clex.util.MultipartInputStreamHandler in, java.lang.String boundary) A utility method that reads an individual part.
protected java.lang.String	readParameter(oracle.clex.util.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.
protected void	removeFile(java.lang.Object fileKey) Removes the file from the hashtable
protected void	removeParam(java.lang.Object paramKey) Removes the parameter with the key from the parameters hashtable
protected void	setMaxPostSize(int maxPostSize) Sets the max post size
void	setServletRequest(javax.servlet.ServletRequest request) Sets the servlet request that contains the multipart request
protected void	setUploadDirectory(java.io.File uploadDirectory) Sets the upload directory

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MAX_POST_SIZE

protected static final int DEFAULT_MAX_POST_SIZE

Constructor Detail

MultipartRequest

public MultipartRequest()

Empty constructor

MultipartRequest

public MultipartRequest(javax.servlet.ServletRequest 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 - if the uploaded content is larger than 1 Megabyte or there's a problem reading or parsing the request

MultipartRequest

public MultipartRequest(javax.servlet.ServletRequest 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 - if the uploaded content is larger than maxPostSize or there's a problem reading or parsing the request

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 given. The value is guaranteed to be in its normal, decoded form. If the parameter has multiple values, only the last one is returned.

Parameters:

name - the parameter name

Returns:

the parameter value

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

setServletRequest

public void setServletRequest(javax.servlet.ServletRequest request)

Sets the servlet request that contains the multipart request

Parameters:

request - The servlet request

getServletRequest

protected javax.servlet.ServletRequest getServletRequest()

Returns the servlet request that contains the multipart request

Returns:

ServletRequest The servlet request that contains the multipart request

setMaxPostSize

protected void setMaxPostSize(int maxPostSize)

Sets the max post size

Parameters:

maxPostSize - The max post size allowed

getMaxPostSize

protected int getMaxPostSize()

Returns the max post size setting

Returns:

int The max post size setting

setUploadDirectory

protected void setUploadDirectory(java.io.File uploadDirectory)

Sets the upload directory

Parameters:

The - upload directory

getUploadDirectory

protected java.io.File getUploadDirectory()

Returns the upload directory

Returns:

File The upload directory

addParam

protected void addParam(java.lang.Object paramKey,
                        java.lang.Object paramValue)

Add to the parameters hashtable

Parameters:

paramKey - The key of the parameter

paramValue - The parameter value to be added

removeParam

protected void removeParam(java.lang.Object paramKey)

Removes the parameter with the key from the parameters hashtable

Parameters:

paramKey - The key of the parameter to be removed

getParametersHashtable

protected java.util.Hashtable getParametersHashtable()

Returns the parameters Hashtable so that subclasses can access it if methods that populates this hashtable is overridden

Returns:

Hashtable The parameters hashtable

addFile

protected void addFile(java.lang.Object fileKey,
                       java.lang.Object file)

Add a file to the file Hashtable. If not overriding the standard multipartrequest processing, the object to be added must be of UploadedFile class.

Parameters:

fileKey - The key for the file to be added

file - The file to be added -- must b UploadedFile if not not overriding the standard mutlipartrequest processing

removeFile

protected void removeFile(java.lang.Object fileKey)

Removes the file from the hashtable

Parameters:

fileKey - The key of the file to be removed

getFilesHashtable

protected java.util.Hashtable getFilesHashtable()

Returns the files Hashtable so that subclasses can access it if methods that populates this hashtable is overridden

Returns:

Hashtable The files hashable

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(oracle.clex.util.MultipartInputStreamHandler in,
                               java.lang.String boundary)
                        throws java.io.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:

java.io.IOException - if there's a problem reading or parsing the request

See Also:

readParameter(oracle.clex.util.MultipartInputStreamHandler, java.lang.String), readAndSaveFile(oracle.clex.util.MultipartInputStreamHandler, java.lang.String, java.lang.String)

readParameter

protected java.lang.String readParameter(oracle.clex.util.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(oracle.clex.util.MultipartInputStreamHandler in,
                               java.lang.String boundary,
                               java.lang.String filename)
                        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

dir - the directory in which to save the uploaded file

filename - the name under which to save the uploaded file

Throws:

java.io.IOException - if there's a problem reading or parsing the request

getSessionId

protected java.lang.String getSessionId()

Returns a String representing the id of the session associated with the servletRequest attribute.

makeUnique

public java.lang.String makeUnique(java.lang.String aString)

Returns a unique string version of the specified string by prepending the session id to it.