org.springframework.web.multipart.commons

## Class CommonsMultipartFile

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

- All Implemented Interfaces:
    Serializable, InputStreamSource, MultipartFile

      public class CommonsMultipartFile
      extends Object
      implements MultipartFile, Serializable

  `MultipartFile` implementation for Apache Commons FileUpload.
  Since:
    29.09.2003
  Author:
    Trevor D. Cook, Juergen Hoeller
  See Also:
    `CommonsMultipartResolver`, Serialized Form

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommonsMultipartFile(org.apache.commons.fileupload.FileItem fileItem)` Create an instance wrapping the given FileItem.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `byte[]` | `getBytes()` Return the contents of the file as an array of bytes.
    `String` | `getContentType()` Return the content type of the file.
    `org.apache.commons.fileupload.FileItem` | `getFileItem()` Return the underlying `org.apache.commons.fileupload.FileItem` instance.
    `InputStream` | `getInputStream()` Return an InputStream to read the contents of the file from.
    `String` | `getName()` Return the name of the parameter in the multipart form.
    `String` | `getOriginalFilename()` Return the original filename in the client's filesystem.
    `long` | `getSize()` Return the size of the file in bytes.
    `String` | `getStorageDescription()` Return a description for the storage location of the multipart content.
    `protected boolean` | `isAvailable()` Determine whether the multipart content is still available.
    `boolean` | `isEmpty()` Return whether the uploaded file is empty, that is, either no file has been chosen in the multipart form or the chosen file has no content.
    `void` | `setPreserveFilename(boolean preserveFilename)` Set whether to preserve the filename as sent by the client, not stripping off path information in `getOriginalFilename()`.
    `String` | `toString()`
    `void` | `transferTo(File dest)` Transfer the received file to the given destination file.
    `void` | `transferTo(Path dest)` Transfer the received file to the given destination file.

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

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

    - ### Methods inherited from interface org.springframework.web.multipart.MultipartFile

      `getResource`

- - ### Field Detail

    - #### logger

          protected static final Log logger

  - ### Constructor Detail

    - #### CommonsMultipartFile

          public CommonsMultipartFile(org.apache.commons.fileupload.FileItem fileItem)

      Create an instance wrapping the given FileItem.
      Parameters:
        `fileItem` - the FileItem to wrap

  - ### Method Detail

    - #### getFileItem

          public final org.apache.commons.fileupload.FileItem getFileItem()

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

    - #### setPreserveFilename

          public void setPreserveFilename(boolean preserveFilename)

      Set whether to preserve the filename as sent by the client, not stripping off path information in `getOriginalFilename()`.

      Default is "false", stripping off path information that may prefix the actual filename e.g. from Opera. Switch this to "true" for preserving the client-specified filename as-is, including potential path separators.

      Since:
        4.3.5
      See Also:
        `getOriginalFilename()`, `CommonsFileUploadSupport.setPreserveFilename(boolean)`

    - #### getName

          public String getName()

      Description copied from interface: `MultipartFile`
      Return the name of the parameter in the multipart form.
      Specified by:
        `getName` in interface `MultipartFile`
      Returns:
        the name of the parameter (never `null` or empty)

    - #### getOriginalFilename

          public String getOriginalFilename()

      Description copied from interface: `MultipartFile`
      Return the original filename in the client's filesystem.

      This may contain path information depending on the browser used, but it typically will not with any other than Opera.

      Note: Please keep in mind this filename is supplied by the client and should not be used blindly. In addition to not using the directory portion, the file name could also contain characters such as ".." and others that can be used maliciously. It is recommended to not use this filename directly. Preferably generate a unique one and save this one somewhere for reference, if necessary.

      Specified by:
        `getOriginalFilename` in interface `MultipartFile`
      Returns:
        the original filename, or the empty String if no file has been chosen in the multipart form, or `null` if not defined or not available
      See Also:
        `FileItem.getName()`, `setPreserveFilename(boolean)`, RFC 7578, Section 4.2, Unrestricted File Upload

    - #### getContentType

          public String getContentType()

      Description copied from interface: `MultipartFile`
      Return the content type of the file.
      Specified by:
        `getContentType` in interface `MultipartFile`
      Returns:
        the content type, or `null` if not defined (or no file has been chosen in the multipart form)

    - #### isEmpty

          public boolean isEmpty()

      Description copied from interface: `MultipartFile`
      Return whether the uploaded file is empty, that is, either no file has been chosen in the multipart form or the chosen file has no content.
      Specified by:
        `isEmpty` in interface `MultipartFile`

    - #### getSize

          public long getSize()

      Description copied from interface: `MultipartFile`
      Return the size of the file in bytes.
      Specified by:
        `getSize` in interface `MultipartFile`
      Returns:
        the size of the file, or 0 if empty

    - #### getBytes

          public byte[] getBytes()

      Description copied from interface: `MultipartFile`
      Return the contents of the file as an array of bytes.
      Specified by:
        `getBytes` in interface `MultipartFile`
      Returns:
        the contents of the file as bytes, or an empty byte array if empty

    - #### getInputStream

          public InputStream getInputStream()
                                     throws IOException

      Description copied from interface: `MultipartFile`
      Return an InputStream to read the contents of the file from.

      The user is responsible for closing the returned stream.

      Specified by:
        `getInputStream` in interface `InputStreamSource`
      Specified by:
        `getInputStream` in interface `MultipartFile`
      Returns:
        the contents of the file as stream, or an empty stream if empty
      Throws:
        `IOException` - in case of access errors (if the temporary store fails)
      See Also:
        `Resource.isReadable()`

    - #### transferTo

          public void transferTo(File dest)
                          throws IOException,
                                 IllegalStateException

      Description copied from interface: `MultipartFile`
      Transfer the received file to the given destination file.

      This may either move the file in the filesystem, copy the file in the filesystem, or save memory-held contents to the destination file. If the destination file already exists, it will be deleted first.

      If the target file has been moved in the filesystem, this operation cannot be invoked again afterwards. Therefore, call this method just once in order to work with any storage mechanism.

      NOTE: Depending on the underlying provider, temporary storage may be container-dependent, including the base directory for relative destinations specified here (e.g. with Servlet 3.0 multipart handling). For absolute destinations, the target file may get renamed/moved from its temporary location or newly copied, even if a temporary copy already exists.

      Specified by:
        `transferTo` in interface `MultipartFile`
      Parameters:
        `dest` - the destination file (typically absolute)
      Throws:
        `IOException` - in case of reading or writing errors
        `IllegalStateException` - if the file has already been moved in the filesystem and is not available anymore for another transfer
      See Also:
        `FileItem.write(File)`, `Part.write(String)`

    - #### transferTo

          public void transferTo(Path dest)
                          throws IOException,
                                 IllegalStateException

      Description copied from interface: `MultipartFile`
      Transfer the received file to the given destination file.

      The default implementation simply copies the file input stream.

      Specified by:
        `transferTo` in interface `MultipartFile`
      Throws:
        `IOException`
        `IllegalStateException`
      See Also:
        `MultipartFile.getInputStream()`, `MultipartFile.transferTo(File)`

    - #### isAvailable

          protected boolean isAvailable()

      Determine whether the multipart content is still available. If a temporary file has been moved, the content is no longer available.

    - #### getStorageDescription

          public String getStorageDescription()

      Return a description for the storage location of the multipart content. Tries to be as specific as possible: mentions the file location in case of a temporary file.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`