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.

  Version:
    $Id$

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

    Constructors
    Constructor and Description
    `FileUploadBase()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected FileItem` | `createItem(Map<String,String> headers, boolean isFormField)` Deprecated. 1.2 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<String,String> headers)` Deprecated. 1.2.1 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<String,String> headers)` Deprecated. 1.2.1 Use `getFileName(FileItemHeaders)`.
    `long` | `getFileSizeMax()` Returns the maximum allowed size of a single uploaded file, as opposed to `getSizeMax()`.
    `protected String` | `getHeader(Map<String,String> headers, String name)` Deprecated. 1.2.1 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(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.
    `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.
    `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

          @Deprecated
          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

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

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

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

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

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

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

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

          @Deprecated
          protected String getFileName(Map<String,String> headers)

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

          @Deprecated
          protected String getFieldName(Map<String,String> headers)

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

          @Deprecated
          protected FileItem createItem(Map<String,String> headers,
                                                    boolean isFormField)
                                             throws FileUploadException

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

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

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

    - #### 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–2017 The Apache Software Foundation. All rights reserved.