Package org.apache.commons.fileupload

A component for handling HTML file uploads as specified by RFC 1867.

See:
          Description

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

Class Summary
DefaultFileItem Deprecated. Use DiskFileItem instead.
DefaultFileItemFactory Deprecated. Use DiskFileItemFactory instead.
DiskFileUpload Deprecated. Use ServletFileUpload together with DiskFileItemFactory instead.
FileUpload High level API for processing file uploads.
FileUploadBase High level API for processing file uploads.
MultipartStream Low level API for processing file uploads.
MultipartStream.ProgressNotifier Internal class, which is used to invoke the ProgressListener.
ParameterParser A simple parser intended to parse sequences of name/value pairs.
 

Exception Summary
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.
FileUploadBase.FileSizeLimitExceededException Thrown to indicate that A files size exceeds the configured maximum.
FileUploadBase.FileUploadIOException This exception is thrown for hiding an inner FileUploadException in an IOException.
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. 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.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.
 

Package org.apache.commons.fileupload Description

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();
        // filename on the client
        String fileName = fi.getName();
        // save comment and filename 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.



Copyright © 2002-2010 The Apache Software Foundation. All Rights Reserved.