Tomcat 10.1.19 · org.apache.tomcat.util.http.fileupload

Note

This code has been copied from commons-fileupload trunk 1.3 and commons-io 1.4 and package renamed to avoid clashes with any web apps that may wish to use these libraries.

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

Interface Summary

Modifier and Type	Interface and Description
public interface	FileItem This class represents a file or form item that was received within a `multipart/form-data` POST request.
public interface	FileItemFactory A factory interface for creating `FileItem` instances.
public interface	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.
public interface	FileItemHeadersSupport Interface that will indicate that `FileItem` or `FileItemStream` implementations will accept the headers read for the item.
public interface	FileItemIterator An iterator, as returned by `FileUploadBase#getItemIterator(RequestContext)`.
public interface	FileItemStream This interface provides access to a file or form item that was received within a `multipart/form-data` POST request.
public interface	ProgressListener The `ProgressListener` may be used to display a progress bar or do stuff like that.
public interface	RequestContext Abstracts access to the request information needed for file uploads.
public interface	UploadContext Enhanced access to the request information needed for file uploads, which fixes the Content Length data access in `RequestContext`.

Class Summary

Modifier and Type	Class and Description
public class	ByteArrayOutputStream This class implements an output stream in which the data is written into a byte array.
public class	DeferredFileOutputStream An output stream which will retain data in memory until a specified threshold is reached, and only then commit it to disk.
public class	FileUpload High level API for processing file uploads.
public abstract class	FileUploadBase High level API for processing file uploads.
public class	FileUploadException Exception for errors encountered while processing the request.
public class	FileUtils General file manipulation utilities.
public class	InvalidFileNameException This exception is thrown in case of an invalid file name.
public class	IOUtils General IO stream manipulation utilities.
public class	MultipartStream Low level API for processing file uploads.
public class	ParameterParser A simple parser intended to parse sequences of name/value pairs.
public abstract class	ThresholdingOutputStream An output stream which triggers an event when a specified number of bytes of data have been written to it.

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

Interface Summary

Class Summary