org.apache.commons.fileupload
Class FileUploadBase

java.lang.Object
  extended by org.apache.commons.fileupload.FileUploadBase
Direct Known Subclasses:
DiskFileUpload, FileUpload

public abstract class FileUploadBase
extends 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.

How the data for individual parts is stored is determined by the factory used to create them; a given part may be in memory, on disk, or somewhere else.

Version:
$Id: FileUploadBase.java 963609 2010-07-13 06:56:47Z jochen $
Author:
Rafal Krzewski, Daniel Rall, Jason van Zyl, John McNally, Martin Cooper, Sean C. Sullivan

Nested Class Summary
static class FileUploadBase.FileSizeLimitExceededException
          Thrown to indicate that A files size exceeds the configured maximum.
static class FileUploadBase.FileUploadIOException
          This exception is thrown for hiding an inner FileUploadException in an IOException.
static class FileUploadBase.InvalidContentTypeException
          Thrown to indicate that the request is not a multipart request.
static class FileUploadBase.IOFileUploadException
          Thrown to indicate an IOException.
protected static class FileUploadBase.SizeException
          This exception is thrown, if a requests permitted size is exceeded.
static class FileUploadBase.SizeLimitExceededException
          Thrown to indicate that the request size exceeds the configured maximum.
static class FileUploadBase.UnknownSizeException
          Deprecated. As of commons-fileupload 1.2, the presence of a content-length header is no longer required.
 
Field Summary
static String ATTACHMENT
          Content-disposition value for file attachment.
static String CONTENT_DISPOSITION
          HTTP content disposition header name.
static String CONTENT_LENGTH
          HTTP content length header name.
static String CONTENT_TYPE
          HTTP content type header name.
static String FORM_DATA
          Content-disposition value for form data.
static int MAX_HEADER_SIZE
          Deprecated. This constant is no longer used. As of commons-fileupload 1.2, the only applicable limit is the total size of a parts headers, MultipartStream.HEADER_PART_SIZE_MAX.
static String MULTIPART
          Part of HTTP content type header.
static String MULTIPART_FORM_DATA
          HTTP content type header for multipart forms.
static String MULTIPART_MIXED
          HTTP content type header for multiple uploads.
 
Constructor Summary
FileUploadBase()
           
 
Method Summary
protected  FileItem createItem(Map headers, boolean isFormField)
          Deprecated. This method is no longer used in favour of internally created instances of FileItem.
protected  byte[] getBoundary(String contentType)
          Retrieves the boundary from the Content-type header.
protected  String getFieldName(FileItemHeaders headers)
          Retrieves the field name from the Content-disposition header.
protected  String getFieldName(Map headers)
          Deprecated. Use getFieldName(FileItemHeaders).
abstract  FileItemFactory getFileItemFactory()
          Returns the factory class used when creating file items.
protected  String getFileName(FileItemHeaders headers)
          Retrieves the file name from the Content-disposition header.
protected  String getFileName(Map headers)
          Deprecated. Use getFileName(FileItemHeaders).
 long getFileSizeMax()
          Returns the maximum allowed size of a single uploaded file, as opposed to getSizeMax().
protected  String getHeader(Map headers, String name)
          Deprecated. Use FileItemHeaders.getHeader(String).
 String getHeaderEncoding()
          Retrieves the character encoding used when reading the headers of an individual part.
 FileItemIterator getItemIterator(RequestContext ctx)
          Processes an RFC 1867 compliant multipart/form-data stream.
protected  FileItemHeaders getParsedHeaders(String headerPart)
           Parses the header-part and returns as key/value pairs.
 ProgressListener getProgressListener()
          Returns the progress listener.
 long getSizeMax()
          Returns the maximum allowed size of a complete request, as opposed to getFileSizeMax().
static boolean isMultipartContent(javax.servlet.http.HttpServletRequest req)
          Deprecated. Use the method on ServletFileUpload instead.
static boolean isMultipartContent(RequestContext ctx)
          Utility method that determines whether the request contains multipart content.
protected  FileItemHeadersImpl newFileItemHeaders()
          Creates a new instance of FileItemHeaders.
protected  Map parseHeaders(String headerPart)
          Deprecated. Use getParsedHeaders(String)
 List parseRequest(javax.servlet.http.HttpServletRequest req)
          Deprecated. Use the method in ServletFileUpload instead.
 List parseRequest(RequestContext ctx)
          Processes an RFC 1867 compliant multipart/form-data stream.
abstract  void setFileItemFactory(FileItemFactory factory)
          Sets the factory class to use when creating file items.
 void setFileSizeMax(long fileSizeMax)
          Sets the maximum allowed size of a single uploaded file, as opposed to getSizeMax().
 void setHeaderEncoding(String encoding)
          Specifies the character encoding to be used when reading the headers of individual part.
 void setProgressListener(ProgressListener pListener)
          Sets the progress listener.
 void setSizeMax(long sizeMax)
          Sets the maximum allowed size of a complete request, as opposed to setFileSizeMax(long).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CONTENT_TYPE

public static final String CONTENT_TYPE
HTTP content type header name.

See Also:
Constant Field Values

CONTENT_DISPOSITION

public static final String CONTENT_DISPOSITION
HTTP content disposition header name.

See Also:
Constant Field Values

CONTENT_LENGTH

public static final String CONTENT_LENGTH
HTTP content length header name.

See Also:
Constant Field Values

FORM_DATA

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

See Also:
Constant Field Values

ATTACHMENT

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

See Also:
Constant Field Values

MULTIPART

public static final String MULTIPART
Part of HTTP content type header.

See Also:
Constant Field Values

MULTIPART_FORM_DATA

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

See Also:
Constant Field Values

MULTIPART_MIXED

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

See Also:
Constant Field Values

MAX_HEADER_SIZE

public static final int MAX_HEADER_SIZE
Deprecated. This constant is no longer used. As of commons-fileupload 1.2, the only applicable limit is the total size of a parts headers, MultipartStream.HEADER_PART_SIZE_MAX.
The maximum length of a single header line that will be parsed (1024 bytes).

See Also:
Constant Field Values
Constructor Detail

FileUploadBase

public FileUploadBase()
Method Detail

isMultipartContent

public static final boolean isMultipartContent(RequestContext ctx)

Utility method that determines whether the request contains multipart content.

NOTE:This method will be moved to the ServletFileUpload class after the FileUpload 1.1 release. Unfortunately, since this method is static, it is not possible to provide its replacement until this method is removed.

Parameters:
ctx - The request context to be evaluated. Must be non-null.
Returns:
true if the request is multipart; false otherwise.

isMultipartContent

public static boolean isMultipartContent(javax.servlet.http.HttpServletRequest req)
Deprecated. Use the method on ServletFileUpload instead.

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.

getFileItemFactory

public abstract FileItemFactory getFileItemFactory()
Returns the factory class used when creating file items.

Returns:
The factory class for new file items.

setFileItemFactory

public abstract void setFileItemFactory(FileItemFactory factory)
Sets the factory class to use when creating file items.

Parameters:
factory - The factory class for new file items.

getSizeMax

public long getSizeMax()
Returns the maximum allowed size of a complete request, as opposed to getFileSizeMax().

Returns:
The maximum allowed size, in bytes. The default value of -1 indicates, that there is no limit.
See Also:
setSizeMax(long)

setSizeMax

public void setSizeMax(long sizeMax)
Sets the maximum allowed size of a complete request, as opposed to setFileSizeMax(long).

Parameters:
sizeMax - The maximum allowed size, in bytes. The default value of -1 indicates, that there is no limit.
See Also:
getSizeMax()

getFileSizeMax

public long getFileSizeMax()
Returns the maximum allowed size of a single uploaded file, as opposed to getSizeMax().

Returns:
Maximum size of a single uploaded file.
See Also:
setFileSizeMax(long)

setFileSizeMax

public void setFileSizeMax(long fileSizeMax)
Sets the maximum allowed size of a single uploaded file, as opposed to getSizeMax().

Parameters:
fileSizeMax - Maximum size of a single uploaded file.
See Also:
getFileSizeMax()

getHeaderEncoding

public String getHeaderEncoding()
Retrieves the character encoding used when reading the headers of an individual part. When not specified, or null, the request encoding is used. If that is also not specified, or null, the platform default encoding is used.

Returns:
The encoding used to read part headers.

setHeaderEncoding

public void setHeaderEncoding(String encoding)
Specifies the character encoding to be used when reading the headers of individual part. When not specified, or null, the request encoding is used. If that is also not specified, or null, the platform default encoding is used.

Parameters:
encoding - The encoding used to read part headers.

parseRequest

public List parseRequest(javax.servlet.http.HttpServletRequest req)
                  throws FileUploadException
Deprecated. Use the method in ServletFileUpload instead.

Processes an RFC 1867 compliant multipart/form-data stream.

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.

getItemIterator

public FileItemIterator getItemIterator(RequestContext ctx)
                                 throws FileUploadException,
                                        IOException
Processes an RFC 1867 compliant multipart/form-data stream.

Parameters:
ctx - The context for the request to be parsed.
Returns:
An iterator to instances of FileItemStream parsed from the request, in the order that they were transmitted.
Throws:
FileUploadException - if there are problems reading/parsing the request or storing files.
FileUploadBase.FileUploadIOException - An I/O error occurred. This may be a network error while communicating with the client or a problem while storing the uploaded content.
IOException

parseRequest

public List parseRequest(RequestContext ctx)
                  throws FileUploadException
Processes an RFC 1867 compliant multipart/form-data stream.

Parameters:
ctx - The context for the 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.

getBoundary

protected byte[] getBoundary(String contentType)
Retrieves the boundary from the Content-type header.

Parameters:
contentType - The value of the content type header from which to extract the boundary value.
Returns:
The boundary, as a byte array.

getFileName

protected String getFileName(Map headers)
Deprecated. Use getFileName(FileItemHeaders).

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.

getFileName

protected String getFileName(FileItemHeaders headers)
Retrieves the file name from the Content-disposition header.

Parameters:
headers - The HTTP headers object.
Returns:
The file name for the current encapsulation.

getFieldName

protected String getFieldName(FileItemHeaders 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.

getFieldName

protected String getFieldName(Map headers)
Deprecated. Use getFieldName(FileItemHeaders).

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(Map headers,
                              boolean isFormField)
                       throws FileUploadException
Deprecated. This method is no longer used in favour of internally created instances of FileItem.

Creates a new FileItem instance.

Parameters:
headers - A Map containing the HTTP request headers.
isFormField - Whether or not this item is a form field, as opposed to a file.
Returns:
A newly created FileItem instance.
Throws:
FileUploadException - if an error occurs.

getParsedHeaders

protected FileItemHeaders getParsedHeaders(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.

newFileItemHeaders

protected FileItemHeadersImpl newFileItemHeaders()
Creates a new instance of FileItemHeaders.

Returns:
The new instance.

parseHeaders

protected Map parseHeaders(String headerPart)
Deprecated. Use getParsedHeaders(String)

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 String getHeader(Map headers,
                                 String name)
Deprecated. Use FileItemHeaders.getHeader(String).

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.

getProgressListener

public ProgressListener getProgressListener()
Returns the progress listener.

Returns:
The progress listener, if any, or null.

setProgressListener

public void setProgressListener(ProgressListener pListener)
Sets the progress listener.

Parameters:
pListener - The progress listener, if any. Defaults to null.


Copyright © 2002-2010 The Apache Software Foundation. All Rights Reserved.