org.apache.commons.fileupload

Class FileUploadBase

java.lang.Object

org.apache.commons.fileupload.FileUploadBase

Direct Known Subclasses:

DiskFileUpload, FileUpload

public abstract class FileUploadBase
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(RequestContext) 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FileUploadBase.FileSizeLimitExceededException Thrown to indicate that A files size exceeds the configured maximum.
static class	FileUploadBase.FileUploadIOException Signals that a FileUpload I/O exception of some sort has occurred.
static class	FileUploadBase.InvalidContentTypeException Thrown to indicate that the request is not a multipart request.
static class	FileUploadBase.IOFileUploadException Thrown to indicate an IOException.
static class	FileUploadBase.SizeLimitExceededException Thrown to indicate that the request size exceeds the configured maximum.
static class	FileUploadBase.UnknownSizeException Deprecated. 1.2 As of commons-fileupload 1.2, the presence of a content-length header is no longer required.

Field Summary

Fields

Modifier and Type	Field and Description
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_LENGTH HTTP content length header name.
static java.lang.String	CONTENT_TYPE HTTP content type header name.
static int	DEFAULT_PART_HEADER_SIZE_MAX Default per part header size limit in bytes.
static java.lang.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.6, the applicable limit is the total size of a single part's headers, getPartHeaderSizeMax() in bytes.
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.
static java.lang.String	MULTIPART_RELATED HTTP content type header for multiple related data.

Constructor Summary

Constructors

Constructor and Description
FileUploadBase() Constructs a new instance.

Method Summary

Modifier and Type	Method and Description
long	getFileCountMax() Returns the maximum number of files allowed in a single request.
abstract FileItemFactory	getFileItemFactory() Returns the factory class used when creating file items.
long	getFileSizeMax() Returns the maximum allowed size of a single uploaded file, as opposed to getSizeMax().
java.lang.String	getHeaderEncoding() Gets 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.
int	getPartHeaderSizeMax() Obtain the per part size limit for headers.
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. 1.1 Use the method on ServletFileUpload instead.
static boolean	isMultipartContent(RequestContext ctx) Utility method that determines whether the request contains multipart content.
java.util.Map<java.lang.String,java.util.List<FileItem>>	parseParameterMap(RequestContext ctx) Processes an RFC 1867 compliant multipart/form-data stream.
java.util.List<FileItem>	parseRequest(javax.servlet.http.HttpServletRequest req) Deprecated. 1.1 Use ServletFileUpload.parseRequest(HttpServletRequest) instead.
java.util.List<FileItem>	parseRequest(RequestContext ctx) Processes an RFC 1867 compliant multipart/form-data stream.
void	setFileCountMax(long fileCountMax) Sets the maximum number of files allowed per request.
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(java.lang.String encoding) Specifies the character encoding to be used when reading the headers of individual part.
void	setPartHeaderSizeMax(int partHeaderSizeMax) Sets the per part size limit for headers.
void	setProgressListener(ProgressListener listener) 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

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

Field Detail

CONTENT_TYPE

public static final java.lang.String CONTENT_TYPE

HTTP content type header name.

See Also:

Constant Field Values

CONTENT_DISPOSITION

public static final java.lang.String CONTENT_DISPOSITION

HTTP content disposition header name.

See Also:

Constant Field Values

CONTENT_LENGTH

public static final java.lang.String CONTENT_LENGTH

HTTP content length header name.

See Also:

Constant Field Values

FORM_DATA

public static final java.lang.String FORM_DATA

Content-disposition value for form data.

See Also:

Constant Field Values

ATTACHMENT

public static final java.lang.String ATTACHMENT

Content-disposition value for file attachment.

See Also:

Constant Field Values

MULTIPART

public static final java.lang.String MULTIPART

Part of HTTP content type header.

See Also:

Constant Field Values

MULTIPART_FORM_DATA

public static final java.lang.String MULTIPART_FORM_DATA

HTTP content type header for multipart forms.

See Also:

Constant Field Values

MULTIPART_MIXED

public static final java.lang.String MULTIPART_MIXED

HTTP content type header for multiple uploads.

See Also:

Constant Field Values

MULTIPART_RELATED

public static final java.lang.String MULTIPART_RELATED

HTTP content type header for multiple related data.

Since:

1.6.0

See Also:

Constant Field Values

MAX_HEADER_SIZE

@Deprecated
public static final int MAX_HEADER_SIZE

Deprecated. This constant is no longer used. As of commons-fileupload 1.6, the applicable limit is the total size of a single part's headers, getPartHeaderSizeMax() in bytes.

The maximum length of a single header line that will be parsed (1024 bytes).

See Also:

Constant Field Values

DEFAULT_PART_HEADER_SIZE_MAX

public static final int DEFAULT_PART_HEADER_SIZE_MAX

Default per part header size limit in bytes.

Since:

1.6.0

See Also:

Constant Field Values

Constructor Detail

FileUploadBase

public FileUploadBase()

Constructs a new instance.

Method Detail

isMultipartContent

@Deprecated
public static boolean isMultipartContent(javax.servlet.http.HttpServletRequest req)

Deprecated. 1.1 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.

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.

getFileCountMax

public long getFileCountMax()

Returns the maximum number of files allowed in a single request.

Returns:

The maximum number of files allowed in a single request.

getFileItemFactory

public abstract FileItemFactory getFileItemFactory()

Returns the factory class used when creating file items.

Returns:

The factory class for new file items.

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)

getHeaderEncoding

public java.lang.String getHeaderEncoding()

Gets 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.

getItemIterator

public FileItemIterator getItemIterator(RequestContext ctx)
                                 throws FileUploadException,
                                        java.io.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.

java.io.IOException - An I/O error occurred. This may be a network error while communicating with the client or a problem while storing the uploaded content.

getPartHeaderSizeMax

public int getPartHeaderSizeMax()

Obtain the per part size limit for headers.

Returns:

The maximum size of the headers for a single part in bytes.

Since:

1.6.0

getProgressListener

public ProgressListener getProgressListener()

Returns the progress listener.

Returns:

The progress listener, if any, or null.

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)

parseParameterMap

public java.util.Map<java.lang.String,java.util.List<FileItem>> parseParameterMap(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 map of FileItem instances parsed from the request.

Throws:

FileUploadException - if there are problems reading/parsing the request or storing files.

Since:

1.3

parseRequest

@Deprecated
public java.util.List<FileItem> parseRequest(javax.servlet.http.HttpServletRequest req)
                                                  throws FileUploadException

Deprecated. 1.1 Use ServletFileUpload.parseRequest(HttpServletRequest) 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.

parseRequest

public java.util.List<FileItem> 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.

setFileCountMax

public void setFileCountMax(long fileCountMax)

Sets the maximum number of files allowed per request.

Parameters:

fileCountMax - The new limit. -1 means no limit.

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.

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()

setHeaderEncoding

public void setHeaderEncoding(java.lang.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.

setPartHeaderSizeMax

public void setPartHeaderSizeMax(int partHeaderSizeMax)

Sets the per part size limit for headers.

Parameters:

partHeaderSizeMax - The maximum size of the headers in bytes.

Since:

1.6.0

setProgressListener

public void setProgressListener(ProgressListener listener)

Sets the progress listener.

Parameters:

listener - The progress listener, if any. Defaults to null.

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()