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.
-
Interface Summary Interface Description FileItem<F extends FileItem<F>> This class represents a file or form item that was received within amultipart/form-data
POST request.FileItemFactory<I extends FileItem<I>> CreatesFileItem
instances.FileItemHeaders This class provides support for accessing the headers for a file or form item that was received within amultipart/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 amultipart/form-data
POST request.FileItemInputIterator An iterator, as returned byAbstractFileUpload.getItemIterator(RequestContext)
.ProgressListener Receives progress information.RequestContext Abstracts access to the request information needed for file uploads. -
Class Summary Class Description AbstractFileUpload<R,I extends FileItem<I>,F extends FileItemFactory<I>> High level API for processing file uploads.AbstractRequestContext<T> DiskFileItem The default implementation of theFileItem
interface.DiskFileItem.Builder Builds a newDiskFileItem
instance.DiskFileItemFactory The defaultFileItemFactory
implementation.DiskFileItemFactory.Builder Builds a newDiskFileItemFactory
instance.FileItemFactory.AbstractFileItemBuilder<I extends FileItem<I>,B extends FileItemFactory.AbstractFileItemBuilder<I,B>> Abstracts building for subclasses.MultipartInput Low-level API for processing file uploads.MultipartInput.Builder Builds a newMultipartInput
instance.MultipartInput.ProgressNotifier Internal class, which is used to invoke theProgressListener
.ParameterParser A simple parser intended to parse sequences of name/value pairs. -
Exception Summary Exception Description FileItemInput.ItemSkippedException This exception is thrown, if an attempt is made to read data from theInputStream
, which has been returned byFileItemInput.getInputStream()
, afterIterator.hasNext()
has been invoked on the iterator, which created theFileItemInput
.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.FileUploadBoundaryException Signals an attempt to set an invalid boundary token.MultipartInput.MalformedStreamException Signals that the input stream fails to follow the required syntax.