org.apache.commons.fileupload
Class FileUpload

java.lang.Object
  |
  +--org.apache.commons.fileupload.FileUpload

public class FileUpload
extends java.lang.Object

High level API for processing file uploads.

This class handles multiple files per single HTML widget, sent using multipart/mixed encoding type, as specified by RFC 1867. Use parseRequest(HttpServletRequest) to acquire a list of FileItems associated with a given HTML widget.

Files will be stored in temporary disk storage or in memory, depending on request size, and will be available as FileItems.

Version:
$Id: FileUpload.java,v 1.15 2002/12/25 04:05:07 martinc Exp $
Author:
Rafal Krzewski, Daniel Rall, Jason van Zyl, John McNally, Martin Cooper, Sean C. Sullivan

Field Summary
static java.lang.String ATTACHMENT
          Content-disposition value for file attachment.
static java.lang.String CONTENT_DISPOSITION
          HTTP content disposition header name.
static java.lang.String CONTENT_TYPE
          HTTP content type header name.
private  java.lang.String fileItemClassName
          The name of the class to use for FileItems.
static java.lang.String FORM_DATA
          Content-disposition value for form data.
static int MAX_HEADER_SIZE
          The maximum length of a single header line that will be parsed (1024 bytes).
private static java.lang.String MULTIPART
          Part of HTTP content type header.
static java.lang.String MULTIPART_FORM_DATA
          HTTP content type header for multipart forms.
static java.lang.String MULTIPART_MIXED
          HTTP content type header for multiple uploads.
private  java.lang.reflect.Method newInstanceMethod
          The cached method for obtaining a new FileItem instance.
private  java.lang.String repositoryPath
          The path to which uploaded files will be stored, if stored on disk.
private  int sizeMax
          The maximum size permitted for an uploaded file.
private  int sizeThreshold
          The threshold above which uploads will be stored on disk.
 
Constructor Summary
FileUpload()
           
 
Method Summary
protected  FileItem createItem(int sizeThreshold, java.lang.String path, java.util.Map headers, int requestSize)
          Creates a new FileItem instance.
protected  java.lang.String getFieldName(java.util.Map headers)
          Retrieves the field name from the Content-disposition header.
 java.lang.String getFileItemClassName()
          Returns the fully qualified name of the class which will be used to instantiate FileItem instances when a request is parsed.
protected  java.lang.String getFileName(java.util.Map headers)
          Retrieves the file name from the Content-disposition header.
protected  java.lang.String getHeader(java.util.Map headers, java.lang.String name)
          Returns the header with the specified name from the supplied map.
protected  java.lang.reflect.Method getNewInstanceMethod()
           Returns the Method object to be used to obtain a new FileItem instance.
 java.lang.String getRepositoryPath()
          Returns the location used to temporarily store files that are larger than the configured size threshold.
 int getSizeMax()
          Returns the maximum allowed upload size.
 int getSizeThreshold()
          Returns the size threshold beyond which files are written directly to disk.
static boolean isMultipartContent(javax.servlet.http.HttpServletRequest req)
          Utility method that determines whether the request contains multipart content.
protected  java.util.Map parseHeaders(java.lang.String headerPart)
           Parses the header-part and returns as key/value pairs.
 java.util.List parseRequest(javax.servlet.http.HttpServletRequest req)
          Processes an RFC 1867 compliant multipart/form-data stream.
 java.util.List parseRequest(javax.servlet.http.HttpServletRequest req, int sizeThreshold, int sizeMax, java.lang.String path)
          Processes an RFC 1867 compliant multipart/form-data stream.
 void setFileItemClassName(java.lang.String fileItemClassName)
          Sets the fully qualified name of the class which will be used to instantiate FileItem instances when a request is parsed.
 void setRepositoryPath(java.lang.String repositoryPath)
          Sets the location used to temporarily store files that are larger than the configured size threshold.
 void setSizeMax(int sizeMax)
          Sets the maximum allowed upload size.
 void setSizeThreshold(int sizeThreshold)
          Sets the size threshold beyond which files are written directly to disk.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

CONTENT_TYPE

public static final java.lang.String CONTENT_TYPE
HTTP content type header name.

CONTENT_DISPOSITION

public static final java.lang.String CONTENT_DISPOSITION
HTTP content disposition header name.

FORM_DATA

public static final java.lang.String FORM_DATA
Content-disposition value for form data.

ATTACHMENT

public static final java.lang.String ATTACHMENT
Content-disposition value for file attachment.

MULTIPART

private static final java.lang.String MULTIPART
Part of HTTP content type header.

MULTIPART_FORM_DATA

public static final java.lang.String MULTIPART_FORM_DATA
HTTP content type header for multipart forms.

MULTIPART_MIXED

public static final java.lang.String MULTIPART_MIXED
HTTP content type header for multiple uploads.

MAX_HEADER_SIZE

public static final int MAX_HEADER_SIZE
The maximum length of a single header line that will be parsed (1024 bytes).

sizeMax

private int sizeMax
The maximum size permitted for an uploaded file.

sizeThreshold

private int sizeThreshold
The threshold above which uploads will be stored on disk.

repositoryPath

private java.lang.String repositoryPath
The path to which uploaded files will be stored, if stored on disk.

fileItemClassName

private java.lang.String fileItemClassName
The name of the class to use for FileItems.

newInstanceMethod

private java.lang.reflect.Method newInstanceMethod
The cached method for obtaining a new FileItem instance.
Constructor Detail

FileUpload

public FileUpload()
Method Detail

isMultipartContent

public static final boolean isMultipartContent(javax.servlet.http.HttpServletRequest req)
Utility method that determines whether the request contains multipart content.
Parameters:
req - The servlet request to be evaluated. Must be non-null.
Returns:
true if the request is multipart; false otherwise.

getSizeMax

public int getSizeMax()
Returns the maximum allowed upload size.
Returns:
The maximum allowed size, in bytes.
See Also:
setSizeMax(int)

setSizeMax

public void setSizeMax(int sizeMax)
Sets the maximum allowed upload size. If negative, there is no maximum.
Parameters:
sizeMax - The maximum allowed size, in bytes, or -1 for no maximum.
See Also:
getSizeMax()

getSizeThreshold

public int getSizeThreshold()
Returns the size threshold beyond which files are written directly to disk. The default value is 1024 bytes.
Returns:
The size threshold, in bytes.
See Also:
setSizeThreshold(int)

setSizeThreshold

public void setSizeThreshold(int sizeThreshold)
Sets the size threshold beyond which files are written directly to disk.
Parameters:
sizeThreshold - The size threshold, in bytes.
See Also:
getSizeThreshold()

getRepositoryPath

public java.lang.String getRepositoryPath()
Returns the location used to temporarily store files that are larger than the configured size threshold.
Returns:
The path to the temporary file location.
See Also:
setRepositoryPath(String)

setRepositoryPath

public void setRepositoryPath(java.lang.String repositoryPath)
Sets the location used to temporarily store files that are larger than the configured size threshold.
Parameters:
repositoryPath - The path to the temporary file location.
See Also:
getRepositoryPath()

getFileItemClassName

public java.lang.String getFileItemClassName()
Returns the fully qualified name of the class which will be used to instantiate FileItem instances when a request is parsed.
Returns:
The fully qualified name of the Java class.
See Also:
setFileItemClassName(String)

setFileItemClassName

public void setFileItemClassName(java.lang.String fileItemClassName)
Sets the fully qualified name of the class which will be used to instantiate FileItem instances when a request is parsed.
Parameters:
fileItemClassName - The fully qualified name of the Java class.
See Also:
getFileItemClassName()

parseRequest

public java.util.List parseRequest(javax.servlet.http.HttpServletRequest req)
                            throws FileUploadException
Processes an RFC 1867 compliant multipart/form-data stream. If files are stored on disk, the path is given by getRepositoryPath().
Parameters:
req - The servlet request to be parsed.
Returns:
A list of FileItem instances parsed from the request, in the order that they were transmitted.
Throws:
FileUploadException - if there are problems reading/parsing the request or storing files.

parseRequest

public java.util.List parseRequest(javax.servlet.http.HttpServletRequest req,
                                   int sizeThreshold,
                                   int sizeMax,
                                   java.lang.String path)
                            throws FileUploadException
Processes an RFC 1867 compliant multipart/form-data stream. If files are stored on disk, the path is given by getRepositoryPath().
Parameters:
req - The servlet request to be parsed. Must be non-null.
sizeThreshold - The max size in bytes to be stored in memory.
sizeMax - The maximum allowed upload size, in bytes.
path - The location where the files should be stored.
Returns:
A list of FileItem instances parsed from the request, in the order that they were transmitted.
Throws:
FileUploadException - if there are problems reading/parsing the request or storing files.

getFileName

protected java.lang.String getFileName(java.util.Map headers)
Retrieves the file name from the Content-disposition header.
Parameters:
headers - A Map containing the HTTP request headers.
Returns:
The file name for the current encapsulation.

getFieldName

protected java.lang.String getFieldName(java.util.Map headers)
Retrieves the field name from the Content-disposition header.
Parameters:
headers - A Map containing the HTTP request headers.
Returns:
The field name for the current encapsulation.

createItem

protected FileItem createItem(int sizeThreshold,
                              java.lang.String path,
                              java.util.Map headers,
                              int requestSize)
                       throws FileUploadException
Creates a new FileItem instance.
Parameters:
sizeThreshold - The max size in bytes to be stored in memory.
path - The path for the FileItem.
headers - A Map containing the HTTP request headers.
requestSize - The total size of the request, in bytes.
Returns:
A newly created FileItem instance.
Throws:
FileUploadException - if an error occurs.

getNewInstanceMethod

protected java.lang.reflect.Method getNewInstanceMethod()
                                                 throws FileUploadException

Returns the Method object to be used to obtain a new FileItem instance.

For performance reasons, we cache the method once it has been looked up, since method lookup is one of the more expensive aspects of reflection.

Returns:
The newInstance() method to be invoked.
Throws:
FileUploadException - if an error occurs.

parseHeaders

protected java.util.Map parseHeaders(java.lang.String headerPart)

Parses the header-part and returns as key/value pairs.

If there are multiple headers of the same names, the name will map to a comma-separated list containing the values.

Parameters:
headerPart - The header-part of the current encapsulation.
Returns:
A Map containing the parsed HTTP request headers.

getHeader

protected final java.lang.String getHeader(java.util.Map headers,
                                           java.lang.String name)
Returns the header with the specified name from the supplied map. The header lookup is case-insensitive.
Parameters:
headers - A Map containing the HTTP request headers.
name - The name of the header to return.
Returns:
The value of specified header, or a comma-separated list if there were multiple headers of that name.