Package org.apache.tomcat.util.http.fileupload

Interface FileItem

  • All Superinterfaces:
    FileItemHeadersSupport
    All Known Implementing Classes:
    DiskFileItem
    public interface FileItem
extends 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(RequestContext)), 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

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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.
      java.lang.String getContentType()
      Returns the content type passed by the browser or null if not defined.
      java.lang.String getFieldName()
      Returns the name of the field in the multipart form corresponding to this file item.
      java.io.InputStream getInputStream()
      Returns an InputStream that can be used to retrieve the contents of the file.
      java.lang.String getName()
      Returns the original file name in the client's file system, as provided by the browser (or other client software).
      java.io.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.
      java.lang.String getString()
      Returns the contents of the file item as a String, using the default character encoding.
      java.lang.String getString​(java.lang.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​(java.lang.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​(java.io.File file)
      A convenience method to write an uploaded item to disk.

    • Method Detail

      • getInputStream

        java.io.InputStream getInputStream()
                            throws java.io.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:
        java.io.IOException - if an error occurs.

      • getContentType

        java.lang.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

        java.lang.String getName()
        Returns 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:
        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()
    throws java.io.UncheckedIOException
        Returns the contents of the file item as an array of bytes.
        Returns:
        The contents of the file item as an array of bytes.
        Throws:
        java.io.UncheckedIOException - if an I/O error occurs

      • getString

        java.lang.String getString​(java.lang.String encoding)
                    throws java.io.UnsupportedEncodingException,
                           java.io.IOException
        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:
        java.io.UnsupportedEncodingException - if the requested character encoding is not available.
        java.io.IOException - if an I/O error occurs

      • getString

        java.lang.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​(java.io.File file)
    throws java.lang.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:
        java.lang.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

        java.lang.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​(java.lang.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

        java.io.OutputStream getOutputStream()
                              throws java.io.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 contents of the file.
        Throws:
        java.io.IOException - if an error occurs.