# Package org.apache.commons.fileupload

package org.apache.commons.fileupload

A component for handling HTML file uploads as specified by RFC 1867. This component provides support for uploads within both servlets (JSR 53) and portlets (JSR 168).

While this package provides the generic functionality for file uploads, these classes are not typically used directly. Instead, normal usage involves one of the provided extensions of `FileUpload` such as `ServletFileUpload` or `PortletFileUpload`, together with a factory for `FileItem` instances, such as `DiskFileItemFactory`.

The following is a brief example of typical usage in a servlet, storing the uploaded files on disk.

    public void doPost(HttpServletRequest req, HttpServletResponse res) {
       DiskFileItemFactory factory = new DiskFileItemFactory();
       // maximum size that will be stored in memory
       factory.setSizeThreshold(4096);
       // the location for saving data that is larger than getSizeThreshold()
       factory.setRepository(new File("/tmp"));

       ServletFileUpload upload = new ServletFileUpload(factory);
       // maximum size before a FileUploadException will be thrown
       upload.setSizeMax(1000000);

       List fileItems = upload.parseRequest(req);
       // assume we know there are two files. The first file is a small
       // text file, the second is unknown and is written to a file on
       // the server
       Iterator i = fileItems.iterator();
       String comment = ((FileItem)i.next()).getString();
       FileItem fi = (FileItem)i.next();
       // file name on the client
       String fileName = fi.getName();
       // save comment and file name to database
       ...
       // write the file
       fi.write(new File("/www/uploads/", fileName));
     }

In the example above, the first file is loaded into memory as a `String`. Before calling the `getString` method, the data may have been in memory or on disk depending on its size. The second file we assume it will be large and therefore never explicitly load it into memory, though if it is less than 4096 bytes it will be in memory before it is written to its final location. When writing to the final location, if the data is larger than the threshold, an attempt is made to rename the temporary file to the given location. If it cannot be renamed, it is streamed to the new location.

Please see the FileUpload User Guide for further details and examples of how to use this package.

- Related Packages
  Package
  Description
  org.apache.commons.fileupload.disk
  A disk-based implementation of the `FileItem` interface.
  org.apache.commons.fileupload.portlet
  An implementation of `FileUpload` for use in portlets conforming to JSR 168.
  org.apache.commons.fileupload.servlet
  An implementation of `FileUpload` for use in servlets conforming to JSR 53.
  org.apache.commons.fileupload.util
  This package contains various IO related utility classes or methods, which are basically reusable and not necessarily restricted to the scope of a file upload.
- Class
  Description
  DefaultFileItem
  Deprecated.
  1.1 Use `DiskFileItem` instead.
  DefaultFileItemFactory
  Deprecated.
  1.1 Use `DiskFileItemFactory` instead.
  DiskFileUpload
  Deprecated.
  1.1 Use `ServletFileUpload` together with `DiskFileItemFactory` instead.
  FileCountLimitExceededException
  This exception is thrown if a request contains more files than the specified limit.
  FileItem
  This class represents a file or form item that was received within a `multipart/form-data` POST request.
  FileItemFactory
  A factory interface for creating `FileItem` instances.
  FileItemHeaders
  This class provides support for accessing the headers for a file or form item that was received within a `multipart/form-data` POST request.
  FileItemHeadersSupport
  Interface that will indicate that `FileItem` or `FileItemStream` implementations will accept the headers read for the item.
  FileItemIterator
  An iterator, as returned by `FileUploadBase.getItemIterator(RequestContext)`.
  FileItemStream
  This interface provides access to a file or form item that was received within a `multipart/form-data` POST request.
  FileItemStream.ItemSkippedException
  This exception is thrown, if an attempt is made to read data from the `InputStream`, which has been returned by `FileItemStream.openStream()`, after `Iterator.hasNext()` has been invoked on the iterator, which created the `FileItemStream`.
  FileUpload
  High level API for processing file uploads.
  FileUploadBase
  High level API for processing file uploads.
  FileUploadBase.FileSizeLimitExceededException
  Thrown to indicate that A files size exceeds the configured maximum.
  FileUploadBase.FileUploadIOException
  Signals that a FileUpload I/O exception of some sort has occurred.
  FileUploadBase.InvalidContentTypeException
  Thrown to indicate that the request is not a multipart request.
  FileUploadBase.IOFileUploadException
  Thrown to indicate an IOException.
  FileUploadBase.SizeException
  This exception is thrown, if a requests permitted size is exceeded.
  FileUploadBase.SizeLimitExceededException
  Thrown to indicate that the request size exceeds the configured maximum.
  FileUploadBase.UnknownSizeException
  Deprecated.
  1.2 As of commons-fileupload 1.2, the presence of a content-length header is no longer required.
  FileUploadException
  Exception for errors encountered while processing the request.
  InvalidFileNameException
  This exception is thrown in case of an invalid file name.
  MultipartStream
  Low level API for processing file uploads.
  MultipartStream.IllegalBoundaryException
  Thrown upon attempt of setting an invalid boundary token.
  MultipartStream.MalformedStreamException
  Thrown to indicate that the input stream fails to follow the required syntax.
  MultipartStream.ProgressNotifier
  Internal class, which is used to invoke the `ProgressListener`.
  ParameterParser
  A simple parser intended to parse sequences of name/value pairs.
  ProgressListener
  The `ProgressListener` may be used to display a progress bar or do stuff like that.
  RequestContext
  Abstracts access to the request information needed for file uploads.
  UploadContext
  Enhanced access to the request information needed for file uploads, which fixes the Content Length data access in `RequestContext`.