CommonsFileUploadSupport (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web.multipart.commons

## Class CommonsFileUploadSupport

- java.lang.Object
- - org.springframework.web.multipart.commons.CommonsFileUploadSupport

- Direct Known Subclasses:
    CommonsMultipartResolver, CommonsPortletMultipartResolver

      public abstract class CommonsFileUploadSupport
      extends Object

  Base class for multipart resolvers that use Jakarta Commons FileUpload 1.2 or above.

  Provides common configuration properties and parsing functionality for multipart requests, using a Map of Spring CommonsMultipartFile instances as representation of uploaded files and a String-based parameter Map as representation of uploaded form fields.

  Subclasses implement concrete resolution strategies for Servlet or Portlet environments: see CommonsMultipartResolver and CommonsPortletMultipartResolver, respectively. This base class is not tied to either of those APIs, factoring out common functionality.

  Since:
    2.0
  Author:
    Juergen Hoeller
  See Also:
    `CommonsMultipartFile`, `CommonsMultipartResolver`, `CommonsPortletMultipartResolver`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `CommonsFileUploadSupport.MultipartParsingResult` Holder for a Map of Spring MultipartFiles and a Map of multipart parameters.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Log` | `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommonsFileUploadSupport()` Instantiate a new CommonsFileUploadSupport with its corresponding FileItemFactory and FileUpload instances.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `cleanupFileItems(MultiValueMap<String,MultipartFile> multipartFiles)` Cleanup the Spring MultipartFiles created during multipart parsing, potentially holding temporary data on disk.
    `protected String` | `getDefaultEncoding()`
    `org.apache.commons.fileupload.disk.DiskFileItemFactory` | `getFileItemFactory()` Return the underlying `org.apache.commons.fileupload.disk.DiskFileItemFactory` instance.
    `org.apache.commons.fileupload.FileUpload` | `getFileUpload()` Return the underlying `org.apache.commons.fileupload.FileUpload` instance.
    `protected boolean` | `isUploadTempDirSpecified()`
    `protected org.apache.commons.fileupload.disk.DiskFileItemFactory` | `newFileItemFactory()` Factory method for a Commons DiskFileItemFactory instance.
    `protected abstract org.apache.commons.fileupload.FileUpload` | `newFileUpload(org.apache.commons.fileupload.FileItemFactory fileItemFactory)` Factory method for a Commons FileUpload instance.
    `protected CommonsFileUploadSupport.MultipartParsingResult` | `parseFileItems(List<org.apache.commons.fileupload.FileItem> fileItems, String encoding)` Parse the given List of Commons FileItems into a Spring MultipartParsingResult, containing Spring MultipartFile instances and a Map of multipart parameter.
    `protected org.apache.commons.fileupload.FileUpload` | `prepareFileUpload(String encoding)` Determine an appropriate FileUpload instance for the given encoding.
    `void` | `setDefaultEncoding(String defaultEncoding)` Set the default character encoding to use for parsing requests, to be applied to headers of individual parts and to form fields.
    `void` | `setMaxInMemorySize(int maxInMemorySize)` Set the maximum allowed size (in bytes) before uploads are written to disk.
    `void` | `setMaxUploadSize(long maxUploadSize)` Set the maximum allowed size (in bytes) before uploads are refused.
    `void` | `setUploadTempDir(Resource uploadTempDir)` Set the temporary directory where uploaded files get stored.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### logger

          protected final Log logger

  - ### Constructor Detail

    - #### CommonsFileUploadSupport

          public CommonsFileUploadSupport()

      Instantiate a new CommonsFileUploadSupport with its corresponding FileItemFactory and FileUpload instances.
      See Also:
        `newFileItemFactory()`, `newFileUpload(org.apache.commons.fileupload.FileItemFactory)`

  - ### Method Detail

    - #### getFileItemFactory

          public org.apache.commons.fileupload.disk.DiskFileItemFactory getFileItemFactory()

      Return the underlying `org.apache.commons.fileupload.disk.DiskFileItemFactory` instance. There is hardly any need to access this.
      Returns:
        the underlying DiskFileItemFactory instance

    - #### getFileUpload

          public org.apache.commons.fileupload.FileUpload getFileUpload()

      Return the underlying `org.apache.commons.fileupload.FileUpload` instance. There is hardly any need to access this.
      Returns:
        the underlying FileUpload instance

    - #### setMaxUploadSize

          public void setMaxUploadSize(long maxUploadSize)

      Set the maximum allowed size (in bytes) before uploads are refused. -1 indicates no limit (the default).
      Parameters:
        `maxUploadSize` - the maximum upload size allowed
      See Also:
        `FileUploadBase.setSizeMax(long)`

    - #### setMaxInMemorySize

          public void setMaxInMemorySize(int maxInMemorySize)

      Set the maximum allowed size (in bytes) before uploads are written to disk. Uploaded files will still be received past this amount, but they will not be stored in memory. Default is 10240, according to Commons FileUpload.
      Parameters:
        `maxInMemorySize` - the maximum in memory size allowed
      See Also:
        `DiskFileItemFactory.setSizeThreshold(int)`

    - #### setDefaultEncoding

          public void setDefaultEncoding(String defaultEncoding)

      Set the default character encoding to use for parsing requests, to be applied to headers of individual parts and to form fields. Default is ISO-8859-1, according to the Servlet spec.

      If the request specifies a character encoding itself, the request encoding will override this setting. This also allows for generically overriding the character encoding in a filter that invokes the `ServletRequest.setCharacterEncoding` method.

      Parameters:
        `defaultEncoding` - the character encoding to use
      See Also:
        `ServletRequest.getCharacterEncoding()`, `ServletRequest.setCharacterEncoding(java.lang.String)`, `WebUtils.DEFAULT_CHARACTER_ENCODING`, `FileUploadBase.setHeaderEncoding(java.lang.String)`

    - #### getDefaultEncoding

          protected String getDefaultEncoding()

    - #### setUploadTempDir

          public void setUploadTempDir(Resource uploadTempDir)
                                throws IOException

      Set the temporary directory where uploaded files get stored. Default is the servlet container's temporary directory for the web application.
      Throws:
        `IOException`
      See Also:
        `WebUtils.TEMP_DIR_CONTEXT_ATTRIBUTE`

    - #### isUploadTempDirSpecified

          protected boolean isUploadTempDirSpecified()

    - #### newFileItemFactory

          protected org.apache.commons.fileupload.disk.DiskFileItemFactory newFileItemFactory()

      Factory method for a Commons DiskFileItemFactory instance.

      Default implementation returns a standard DiskFileItemFactory. Can be overridden to use a custom subclass, e.g. for testing purposes.

      Returns:
        the new DiskFileItemFactory instance

    - #### newFileUpload

          protected abstract org.apache.commons.fileupload.FileUpload newFileUpload(org.apache.commons.fileupload.FileItemFactory fileItemFactory)

      Factory method for a Commons FileUpload instance.

      To be implemented by subclasses.

      Parameters:
        `fileItemFactory` - the Commons FileItemFactory to build upon
      Returns:
        the Commons FileUpload instance

    - #### prepareFileUpload

          protected org.apache.commons.fileupload.FileUpload prepareFileUpload(String encoding)

      Determine an appropriate FileUpload instance for the given encoding.

      Default implementation returns the shared FileUpload instance if the encoding matches, else creates a new FileUpload instance with the same configuration other than the desired encoding.

      Parameters:
        `encoding` - the character encoding to use
      Returns:
        an appropriate FileUpload instance.

    - #### parseFileItems

          protected CommonsFileUploadSupport.MultipartParsingResult parseFileItems(List<org.apache.commons.fileupload.FileItem> fileItems,
                                                                       String encoding)

      Parse the given List of Commons FileItems into a Spring MultipartParsingResult, containing Spring MultipartFile instances and a Map of multipart parameter.
      Parameters:
        `fileItems` - the Commons FileIterms to parse
        `encoding` - the encoding to use for form fields
      Returns:
        the Spring MultipartParsingResult
      See Also:
        `CommonsMultipartFile.CommonsMultipartFile(org.apache.commons.fileupload.FileItem)`

    - #### cleanupFileItems

          protected void cleanupFileItems(MultiValueMap<String,MultipartFile> multipartFiles)

      Cleanup the Spring MultipartFiles created during multipart parsing, potentially holding temporary data on disk.

      Deletes the underlying Commons FileItem instances.

      Parameters:
        `multipartFiles` - Collection of MultipartFile instances
      See Also:
        `FileItem.delete()`