Package org.apache.commons.fileupload

# Class FileUploadBase

java.lang.Object
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(RequestContext)` to acquire a list of `FileItem`s 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
  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.
  `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.
  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
  Description
  `static final String`
  `ATTACHMENT`
  Content-disposition value for file attachment.
  `static final String`
  `CONTENT_DISPOSITION`
  HTTP content disposition header name.
  `static final String`
  `CONTENT_LENGTH`
  HTTP content length header name.
  `static final String`
  `CONTENT_TYPE`
  HTTP content type header name.
  `static final int`
  `DEFAULT_PART_HEADER_SIZE_MAX`
  Default per part header size limit in bytes.
  `static final String`
  `FORM_DATA`
  Content-disposition value for form data.
  `static final int`
  `MAX_HEADER_SIZE`
  Deprecated.
  This constant is no longer used.
  `static final String`
  `MULTIPART`
  Part of HTTP content type header.
  `static final String`
  `MULTIPART_FORM_DATA`
  HTTP content type header for multipart forms.
  `static final String`
  `MULTIPART_MIXED`
  HTTP content type header for multiple uploads.
  `static final String`
  `MULTIPART_RELATED`
  HTTP content type header for multiple related data.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FileUploadBase()`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected FileItem`
  `createItem(Map<String,String> headers, boolean isFormField)`
  Deprecated.
  1.2 This method is no longer used in favor of internally created instances of `FileItem`.
  `protected byte[]`
  `getBoundary(String contentType)`
  Gets the boundary from the `Content-type` header.
  `protected String`
  `getFieldName(Map<String,String> headers)`
  Deprecated.
  1.2.1 Use `getFieldName(FileItemHeaders)`.
  `protected String`
  `getFieldName(FileItemHeaders headers)`
  Gets the field name from the `Content-disposition` header.
  `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.
  `protected String`
  `getFileName(Map<String,String> headers)`
  Deprecated.
  1.2.1 Use `getFileName(FileItemHeaders)`.
  `protected String`
  `getFileName(FileItemHeaders headers)`
  Gets the file name from the `Content-disposition` header.
  `long`
  `getFileSizeMax()`
  Returns the maximum allowed size of a single uploaded file, as opposed to `getSizeMax()`.
  `protected final String`
  `getHeader(Map<String,String> headers, String name)`
  Deprecated.
  1.2.1 Use `FileItemHeaders.getHeader(String)`.
  `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.
  `protected FileItemHeaders`
  `getParsedHeaders(String headerPart)`
  Parses the `header-part` and returns as key/value pairs.
  `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(HttpServletRequest req)`
  Deprecated.
  1.1 Use the method on `ServletFileUpload` instead.
  `static final 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<String,String>`
  `parseHeaders(String headerPart)`
  Deprecated.
  1.2.1 Use `getParsedHeaders(String)`
  `Map<String,List<FileItem>>`
  `parseParameterMap(RequestContext ctx)`
  Processes an RFC 1867 compliant `multipart/form-data` stream.
  `List<FileItem>`
  `parseRequest(HttpServletRequest req)`
  Deprecated.
  1.1 Use `ServletFileUpload.parseRequest(HttpServletRequest)` instead.
  `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(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

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

- ## Field Details

  - ### 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

  - ### MULTIPART_RELATED

    public static final 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 Details

  - ### FileUploadBase

    public FileUploadBase()
    Constructs a new instance.

- ## Method Details

  - ### isMultipartContent

    @Deprecated public static boolean isMultipartContent(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.

  - ### createItem

    @Deprecated protected FileItem createItem(Map<String,String> headers, boolean isFormField)
    Deprecated.
    1.2 This method is no longer used in favor 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.

  - ### getBoundary

    protected byte[] getBoundary(String contentType)
    Gets 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.

  - ### getFieldName

    protected String getFieldName(FileItemHeaders headers)
    Gets 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

    @Deprecated protected String getFieldName(Map<String,String> headers)
    Deprecated.
    1.2.1 Use `getFieldName(FileItemHeaders)`.
    Gets 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`.

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

  - ### getFileName

    protected String getFileName(FileItemHeaders headers)
    Gets the file name from the `Content-disposition` header.
    Parameters:
      `headers` - The HTTP headers object.
    Returns:
      The file name for the current `encapsulation`.

  - ### getFileName

    @Deprecated protected String getFileName(Map<String,String> headers)
    Deprecated.
    1.2.1 Use `getFileName(FileItemHeaders)`.
    Gets 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`.

  - ### 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)`

  - ### getHeader

    @Deprecated protected final String getHeader(Map<String,String> headers, String name)
    Deprecated.
    1.2.1 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.

  - ### getHeaderEncoding

    public 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, 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.
      `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.

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

  - ### 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)`

  - ### newFileItemHeaders

    protected FileItemHeadersImpl newFileItemHeaders()
    Creates a new instance of `FileItemHeaders`.
    Returns:
      The new instance.

  - ### parseHeaders

    @Deprecated protected Map<String,String> parseHeaders(String headerPart)
    Deprecated.
    1.2.1 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.

  - ### parseParameterMap

    public Map<String,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 List<FileItem> parseRequest(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 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(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()`