org.apache.commons.fileupload

## Interface FileItem

- All Superinterfaces:
    FileItemHeadersSupport, Serializable
  All Known Implementing Classes:
    DefaultFileItem, DiskFileItem

      public interface FileItem
      extends Serializable, FileItemHeadersSupport

  This class represents a file or form item that was received within a `multipart/form-data` POST request.

  After retrieving an instance of this class from a `FileUpload` instance (see `#parseRequest(javax.servlet.http.HttpServletRequest)`), you may either request all contents of the file at once using `get()` or request an `InputStream` with `getInputStream()` and process the file without attempting to load it into memory, which may come handy with large files.

  While this interface does not extend `javax.activation.DataSource` per se (to avoid a seldom used dependency), several of the defined methods are specifically defined with the same signatures as methods in that interface. This allows an implementation of this interface to also implement `javax.activation.DataSource` with minimal additional work.

  Since:
    1.3 additionally implements FileItemHeadersSupport
  Version:
    $Id$

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `delete()` Deletes the underlying storage for a file item, including deleting any associated temporary disk file.
    `byte[]` | `get()` Returns the contents of the file item as an array of bytes.
    `String` | `getContentType()` Returns the content type passed by the browser or `null` if not defined.
    `String` | `getFieldName()` Returns the name of the field in the multipart form corresponding to this file item.
    `InputStream` | `getInputStream()` Returns an `InputStream` that can be used to retrieve the contents of the file.
    `String` | `getName()` Returns the original filename in the client's filesystem, as provided by the browser (or other client software).
    `OutputStream` | `getOutputStream()` Returns an `OutputStream` that can be used for storing the contents of the file.
    `long` | `getSize()` Returns the size of the file item.
    `String` | `getString()` Returns the contents of the file item as a String, using the default character encoding.
    `String` | `getString(String encoding)` Returns the contents of the file item as a String, using the specified encoding.
    `boolean` | `isFormField()` Determines whether or not a `FileItem` instance represents a simple form field.
    `boolean` | `isInMemory()` Provides a hint as to whether or not the file contents will be read from memory.
    `void` | `setFieldName(String name)` Sets the field name used to reference this file item.
    `void` | `setFormField(boolean state)` Specifies whether or not a `FileItem` instance represents a simple form field.
    `void` | `write(File file)` A convenience method to write an uploaded item to disk.

    - ### Methods inherited from interface org.apache.commons.fileupload.FileItemHeadersSupport

      `getHeaders, setHeaders`

- - ### Method Detail

    - #### getInputStream

          InputStream getInputStream()
                              throws IOException

      Returns an `InputStream` that can be used to retrieve the contents of the file.
      Returns:
        An `InputStream` that can be used to retrieve the contents of the file.
      Throws:
        `IOException` - if an error occurs.

    - #### getContentType

          String getContentType()

      Returns the content type passed by the browser or `null` if not defined.
      Returns:
        The content type passed by the browser or `null` if not defined.

    - #### getName

          String getName()

      Returns the original filename in the client's filesystem, as provided by the browser (or other client software). In most cases, this will be the base file name, without path information. However, some clients, such as the Opera browser, do include path information.
      Returns:
        The original filename in the client's filesystem.
      Throws:
        `InvalidFileNameException` - The file name contains a NUL character, which might be an indicator of a security attack. If you intend to use the file name anyways, catch the exception and use InvalidFileNameException#getName().

    - #### isInMemory

          boolean isInMemory()

      Provides a hint as to whether or not the file contents will be read from memory.
      Returns:
        `true` if the file contents will be read from memory; `false` otherwise.

    - #### getSize

          long getSize()

      Returns the size of the file item.
      Returns:
        The size of the file item, in bytes.

    - #### get

          byte[] get()

      Returns the contents of the file item as an array of bytes.
      Returns:
        The contents of the file item as an array of bytes.

    - #### getString

          String getString(String encoding)
                    throws UnsupportedEncodingException

      Returns the contents of the file item as a String, using the specified encoding. This method uses `get()` to retrieve the contents of the item.
      Parameters:
        `encoding` - The character encoding to use.
      Returns:
        The contents of the item, as a string.
      Throws:
        `UnsupportedEncodingException` - if the requested character encoding is not available.

    - #### getString

          String getString()

      Returns the contents of the file item as a String, using the default character encoding. This method uses `get()` to retrieve the contents of the item.
      Returns:
        The contents of the item, as a string.

    - #### write

          void write(File file)
              throws Exception

      A convenience method to write an uploaded item to disk. The client code is not concerned with whether or not the item is stored in memory, or on disk in a temporary location. They just want to write the uploaded item to a file.

      This method is not guaranteed to succeed if called more than once for the same item. This allows a particular implementation to use, for example, file renaming, where possible, rather than copying all of the underlying data, thus gaining a significant performance benefit.

      Parameters:
        `file` - The `File` into which the uploaded item should be stored.
      Throws:
        `Exception` - if an error occurs.

    - #### delete

          void delete()

      Deletes the underlying storage for a file item, including deleting any associated temporary disk file. Although this storage will be deleted automatically when the `FileItem` instance is garbage collected, this method can be used to ensure that this is done at an earlier time, thus preserving system resources.

    - #### getFieldName

          String getFieldName()

      Returns the name of the field in the multipart form corresponding to this file item.
      Returns:
        The name of the form field.

    - #### setFieldName

          void setFieldName(String name)

      Sets the field name used to reference this file item.
      Parameters:
        `name` - The name of the form field.

    - #### isFormField

          boolean isFormField()

      Determines whether or not a `FileItem` instance represents a simple form field.
      Returns:
        `true` if the instance represents a simple form field; `false` if it represents an uploaded file.

    - #### setFormField

          void setFormField(boolean state)

      Specifies whether or not a `FileItem` instance represents a simple form field.
      Parameters:
        `state` - `true` if the instance represents a simple form field; `false` if it represents an uploaded file.

    - #### getOutputStream

          OutputStream getOutputStream()
                                throws IOException

      Returns an `OutputStream` that can be used for storing the contents of the file.
      Returns:
        An `OutputStream` that can be used for storing the contensts of the file.
      Throws:
        `IOException` - if an error occurs.

Copyright © 2002–2017 The Apache Software Foundation. All rights reserved.