Package org.apache.commons.fileupload2.core

# Interface FileItem<F extends FileItem<F>>

Type Parameters:
  `F` - The FileItem type.

All Superinterfaces:
  `FileItemHeadersProvider<F>`

All Known Implementing Classes:
  `DiskFileItem`

public interface FileItem<F extends FileItem<F>> extends FileItemHeadersProvider<F>

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 `org.apache.commons.fileupload2.core.servlet.ServletFileUpload #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` (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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `F`
  `delete()`
  Deletes the underlying storage for a file item, including deleting any associated temporary disk file.
  `byte[]`
  `get()`
  Gets the contents of the file item as a byte array.
  `String`
  `getContentType()`
  Gets the content type passed by the browser or `null` if not defined.
  `String`
  `getFieldName()`
  Gets the name of the field in the multipart form corresponding to this file item.
  `InputStream`
  `getInputStream()`
  Gets an `InputStream` that can be used to retrieve the contents of the file.
  `String`
  `getName()`
  Gets the original file name in the client's file system, as provided by the browser (or other client software).
  `OutputStream`
  `getOutputStream()`
  Gets an `OutputStream` that can be used for storing the contents of the file.
  `long`
  `getSize()`
  Gets the size of the file item.
  `String`
  `getString()`
  Gets the contents of the file item as a String, using the default character encoding.
  `String`
  `getString(Charset toCharset)`
  Gets the contents of the file item as a String, using the specified encoding.
  `boolean`
  `isFormField()`
  Tests whether or not a `FileItem` instance represents a simple form field.
  `boolean`
  `isInMemory()`
  Tests a hint as to whether or not the file contents will be read from memory.
  `F`
  `setFieldName(String name)`
  Sets the field name used to reference this file item.
  `F`
  `setFormField(boolean state)`
  Sets whether or not a `FileItem` instance represents a simple form field.
  `F`
  `write(Path file)`
  Writes an uploaded item to disk.

  ### Methods inherited from interface org.apache.commons.fileupload2.core.FileItemHeadersProvider

  `getHeaders, setHeaders`

- ## Method Details

  - ### delete

    F delete() throws IOException
    Deletes the underlying storage for a file item, including deleting any associated temporary disk file. Use this method to ensure that this is done at an earlier time, to preserve resources.
    Returns:
      this
    Throws:
      `IOException` - if an error occurs.

  - ### get

    byte[] get() throws UncheckedIOException
    Gets the contents of the file item as a byte array.
    Returns:
      The contents of the file item as a byte array.
    Throws:
      `UncheckedIOException` - if an I/O error occurs

  - ### getContentType

    String getContentType()
    Gets 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.

  - ### getFieldName

    String getFieldName()
    Gets the name of the field in the multipart form corresponding to this file item.
    Returns:
      The name of the form field.

  - ### getInputStream

    InputStream getInputStream() throws IOException
    Gets 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.

  - ### getName

    String getName()
    Gets the original file name in the client's file system, 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 file name in the client's file system.
    Throws:
      `InvalidPathException` - 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().

  - ### getOutputStream

    OutputStream getOutputStream() throws IOException
    Gets an `OutputStream` that can be used for storing the contents of the file.
    Returns:
      An `OutputStream` that can be used for storing the contents of the file.
    Throws:
      `IOException` - if an error occurs.

  - ### getSize

    long getSize()
    Gets the size of the file item.
    Returns:
      The size of the file item, in bytes.

  - ### getString

    String getString()
    Gets 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.

  - ### getString

    String getString(Charset toCharset) throws IOException
    Gets 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:
      `toCharset` - The character encoding to use.
    Returns:
      The contents of the item, as a string.
    Throws:
      `IOException` - if an I/O error occurs

  - ### isFormField

    boolean isFormField()
    Tests 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.

  - ### isInMemory

    boolean isInMemory()
    Tests 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.

  - ### setFieldName

    F setFieldName(String name)
    Sets the field name used to reference this file item.
    Parameters:
      `name` - The name of the form field.
    Returns:
      this

  - ### setFormField

    F setFormField(boolean state)
    Sets 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.
    Returns:
      this

  - ### write

    F write(Path file) throws IOException
    Writes 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.
    Returns:
      this
    Throws:
      `IOException` - if an error occurs.