# Package org.apache.commons.fileupload2.core

package org.apache.commons.fileupload2.core

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 `AbstractFileUpload` such as `org.apache.commons.fileupload2.core.servlet.ServletFileUpload ServletFileUpload` or `org.apache.commons.fileupload2.core.portlet.PortletFileUpload 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.builder()
        // maximum size that will be stored in memory
        .setSizeThreshold(4096);
        // the location for saving data that is larger than getSizeThreshold()
        .setPath(Paths.get("/tmp"))
        // build it
        .get();

      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.

Class
Description
AbstractFileUpload<R, I extends FileItem<I>, F extends FileItemFactory<I>>
High level API for processing file uploads.
AbstractRequestContext<T>
Abstracts a RequestContext for implementations.
DeferrableOutputStream
An `OutputStream`, which keeps its data in memory, until a configured threshold is reached.
DeferrableOutputStream.Listener
Interface of a listener object, that wishes to be notified about state changes.
DeferrableOutputStream.State
This enumeration represents the possible states of the `DeferrableOutputStream`.
DiskFileItem
The default implementation of the `FileItem` interface.
DiskFileItem.Builder
Builds a new `DiskFileItem` instance.
DiskFileItemFactory
The default `FileItemFactory` implementation.
DiskFileItemFactory.Builder
Builds a new `DiskFileItemFactory` instance.
FileItem<F extends FileItem<F>>
This class represents a file or form item that was received within a `multipart/form-data` POST request.
FileItemFactory<I extends FileItem<I>>
Creates `FileItem` instances.
FileItemFactory.AbstractFileItemBuilder<I extends FileItem<I>, B extends FileItemFactory.AbstractFileItemBuilder<I,B>>
Abstracts building for subclasses.
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.
FileItemHeadersProvider<T extends FileItemHeadersProvider<T>>
Provides access to headers.
FileItemInput
Provides access to a file or form item that was received within a `multipart/form-data` POST request.
FileItemInput.ItemSkippedException
This exception is thrown, if an attempt is made to read data from the `InputStream`, which has been returned by `FileItemInput.getInputStream()`, after `Iterator.hasNext()` has been invoked on the iterator, which created the `FileItemInput`.
FileItemInputIterator
An iterator, as returned by `AbstractFileUpload.getItemIterator(RequestContext)`.
FileUploadByteCountLimitException
Signals that a file size exceeds the configured maximum.
FileUploadContentTypeException
Signals that a request is not a multipart request.
FileUploadException
Signals errors encountered while processing the request.
FileUploadFileCountLimitException
Signals that a request contains more files than the specified limit.
FileUploadSizeException
Signals that a requests permitted size is exceeded.
MultipartInput
Low-level API for processing file uploads.
MultipartInput.Builder
Builds a new `MultipartInput` instance.
MultipartInput.FileUploadBoundaryException
Signals an attempt to set an invalid boundary token.
MultipartInput.MalformedStreamException
Signals that the input stream fails to follow the required syntax.
MultipartInput.ProgressNotifier
Internal class, which is used to invoke the `ProgressListener`.
ParameterParser
A simple parser intended to parse sequences of name/value pairs.
ProgressListener
Receives progress information.
RequestContext
Abstracts access to the request information needed for file uploads.