apache common 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 {@link org.apache.commons.fileupload.FileUpload FileUpload} such as {@link org.apache.commons.fileupload.servlet.ServletFileUpload ServletFileUpload} or {@link org.apache.commons.fileupload.portlet.PortletFileUpload PortletFileUpload}, together with a factory for {@link org.apache.commons.fileupload.FileItem FileItem} instances, such as {@link org.apache.commons.fileupload.disk.DiskFileItemFactory 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.

A disk-based implementation of the {@link org.apache.commons.fileupload.FileItem FileItem} interface. This implementation retains smaller items in memory, while writing larger ones to disk. The threshold between these two is configurable, as is the location of files that are written to disk.

In typical usage, an instance of {@link org.apache.commons.fileupload.disk.DiskFileItemFactory DiskFileItemFactory} would be created, configured, and then passed to a {@link org.apache.commons.fileupload.FileUpload FileUpload} implementation such as {@link org.apache.commons.fileupload.servlet.ServletFileUpload ServletFileUpload} or {@link org.apache.commons.fileupload.portlet.PortletFileUpload PortletFileUpload}.

The following code fragment demonstrates this usage.

        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);

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

An implementation of {@link org.apache.commons.fileupload.FileUpload FileUpload} for use in portlets conforming to JSR 168. This implementation requires only access to the portlet's current ActionRequest instance, and a suitable {@link org.apache.commons.fileupload.FileItemFactory FileItemFactory} implementation, such as {@link org.apache.commons.fileupload.disk.DiskFileItemFactory DiskFileItemFactory}.

The following code fragment demonstrates typical usage.

        DiskFileItemFactory factory = new DiskFileItemFactory();
        // Configure the factory here, if desired.
        PortletFileUpload upload = new PortletFileUpload(factory);
        // Configure the uploader here, if desired.
        List fileItems = upload.parseRequest(request);

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

An implementation of {@link org.apache.commons.fileupload.FileUpload FileUpload} for use in servlets conforming to JSR 53. This implementation requires only access to the servlet's current HttpServletRequest instance, and a suitable {@link org.apache.commons.fileupload.FileItemFactory FileItemFactory} implementation, such as {@link org.apache.commons.fileupload.disk.DiskFileItemFactory DiskFileItemFactory}.

The following code fragment demonstrates typical usage.

        DiskFileItemFactory factory = new DiskFileItemFactory();
        // Configure the factory here, if desired.
        ServletFileUpload upload = new ServletFileUpload(factory);
        // Configure the uploader here, if desired.
        List fileItems = upload.parseRequest(request);

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

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.