Package org.apache.commons.fileupload2.core

# Class AbstractFileUpload<R,I extends FileItem<I>,F extends FileItemFactory<I>>

java.lang.Object
org.apache.commons.fileupload2.core.AbstractFileUpload<R,I,F>

Type Parameters:
  `R` - The request context type.
  `I` - The FileItem type.
  `F` - the FileItemFactory type.

public abstract class AbstractFileUpload<R,I extends FileItem<I>,F extends FileItemFactory<I>> 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.

- ## 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 String`
  `FORM_DATA`
  Content-disposition value for form data.
  `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.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractFileUpload()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `byte[]`
  `getBoundary(String contentType)`
  Gets the boundary from the `Content-type` header.
  `String`
  `getFieldName(FileItemHeaders headers)`
  Gets the field name from the `Content-disposition` header.
  `long`
  `getFileCountMax()`
  Gets the maximum number of files allowed in a single request.
  `F`
  `getFileItemFactory()`
  Gets the factory class used when creating file items.
  `String`
  `getFileName(FileItemHeaders headers)`
  Gets the file name from the `Content-disposition` header.
  `long`
  `getFileSizeMax()`
  Gets the maximum allowed size of a single uploaded file, as opposed to `getSizeMax()`.
  `Charset`
  `getHeaderCharset()`
  Gets the character encoding used when reading the headers of an individual part.
  `FileItemInputIterator`
  `getItemIterator(RequestContext requestContext)`
  Gets an RFC 1867 compliant `multipart/form-data` stream.
  `abstract FileItemInputIterator`
  `getItemIterator(R request)`
  Gets a file item iterator.
  `FileItemHeaders`
  `getParsedHeaders(String headerPart)`
  Parses the `header-part` and returns as key/value pairs.
  `ProgressListener`
  `getProgressListener()`
  Gets the progress listener.
  `long`
  `getSizeMax()`
  Gets the maximum allowed size of a complete request, as opposed to `getFileSizeMax()`.
  `static final boolean`
  `isMultipartContent(RequestContext ctx)`
  Utility method that determines whether the request contains multipart content.
  `protected FileItemHeaders`
  `newFileItemHeaders()`
  Creates a new instance of `FileItemHeaders`.
  `Map<String,List<I>>`
  `parseParameterMap(RequestContext ctx)`
  Parses an RFC 1867 compliant `multipart/form-data` stream.
  `abstract Map<String,List<I>>`
  `parseParameterMap(R request)`
  Parses an RFC 1867 compliant `multipart/form-data` stream.
  `List<I>`
  `parseRequest(RequestContext requestContext)`
  Parses an RFC 1867 compliant `multipart/form-data` stream.
  `abstract List<I>`
  `parseRequest(R request)`
  Parses an RFC 1867 compliant `multipart/form-data` stream.
  `void`
  `setFileCountMax(long fileCountMax)`
  Sets the maximum number of files allowed per request.
  `void`
  `setFileItemFactory(F 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`
  `setHeaderCharset(Charset headerCharset)`
  Specifies the character encoding to be used when reading the headers of individual part.
  `void`
  `setProgressListener(ProgressListener progressListener)`
  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

- ## Constructor Details

  - ### AbstractFileUpload

    public AbstractFileUpload()

- ## Method Details

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

  - ### getBoundary

    public 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

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

  - ### getFileCountMax

    public long getFileCountMax()
    Gets the maximum number of files allowed in a single request.
    Returns:
      The maximum number of files allowed in a single request.

  - ### getFileItemFactory

    public F getFileItemFactory()
    Gets the factory class used when creating file items.
    Returns:
      The factory class for new file items.

  - ### getFileName

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

  - ### getFileSizeMax

    public long getFileSizeMax()
    Gets 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)`

  - ### getHeaderCharset

    public Charset getHeaderCharset()
    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 abstract FileItemInputIterator getItemIterator(R request) throws FileUploadException, IOException
    Gets a file item iterator.
    Parameters:
      `request` - The servlet request to be parsed.
    Returns:
      An iterator to instances of `FileItemInput` 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.

  - ### getItemIterator

    public FileItemInputIterator getItemIterator(RequestContext requestContext) throws FileUploadException, IOException
    Gets an RFC 1867 compliant `multipart/form-data` stream.
    Parameters:
      `requestContext` - The context for the request to be parsed.
    Returns:
      An iterator to instances of `FileItemInput` 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

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

  - ### getProgressListener

    public ProgressListener getProgressListener()
    Gets the progress listener.
    Returns:
      The progress listener, if any, or null.

  - ### getSizeMax

    public long getSizeMax()
    Gets 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 FileItemHeaders newFileItemHeaders()
    Creates a new instance of `FileItemHeaders`.
    Returns:
      The new instance.

  - ### parseParameterMap

    public abstract Map<String,List<I>> parseParameterMap(R request) throws FileUploadException
    Parses an RFC 1867 compliant `multipart/form-data` stream.
    Parameters:
      `request` - The servlet 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.

  - ### parseParameterMap

    public Map<String,List<I>> parseParameterMap(RequestContext ctx) throws FileUploadException
    Parses 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.

  - ### parseRequest

    public abstract List<I> parseRequest(R request) throws FileUploadException
    Parses an RFC 1867 compliant `multipart/form-data` stream.
    Parameters:
      `request` - 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<I> parseRequest(RequestContext requestContext) throws FileUploadException
    Parses an RFC 1867 compliant `multipart/form-data` stream.
    Parameters:
      `requestContext` - 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 void setFileItemFactory(F 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()`

  - ### setHeaderCharset

    public void setHeaderCharset(Charset headerCharset)
    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:
      `headerCharset` - The encoding used to read part headers.

  - ### setProgressListener

    public void setProgressListener(ProgressListener progressListener)
    Sets the progress listener.
    Parameters:
      `progressListener` - 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()`