File Upload

The File Upload Tag Library provides an easy way to process files uploaded from a web form from within JSP pages. It is a tag library wrapper around the Jakarta Commons FileUpload utility.

When processing files uploaded from a web form from any Java Servlet technology, there are a few caveats that must be remembered:

• The body of the request can only be parsed once. Parsing it consumes it, so there will be nothing to parse if it is attempted a second time for the same body.
• Since file-upload forms incorporate all the parameters (not just the file upload ones) into the body of the request and any file upload parser will consume that body, those parameters will not be available through the normal 'request' object. Similarly, parameters will also not be available through the JSTL param object. The parameters must be accessed through the file-upload parser.
• Accessing parameters from a file-upload form through the normal means before parsing will cause the body of the request to be consumed, which will leave nothing for the file-upload parser to parse.

With these points in mind, the 'parse' tag of this tag library must be called exactly once at the beginning of the JSP. This tag will consume and parse the body of the request and make the files and parameters available through subsequent access tags.

Once the 'parse' has occurred, parameters can be accessed either with the 'param' tag or (if using JSTL) through the page-scope map 'param'. Uploaded files can be accessed with the 'file' tag and several accessor tags.

For example, to get a non-file parameter from a file-upload request:

To retrieve the size of each uploaded file:

To deploy this tag library for use with your web application, follow these steps:

• Copy the tag library descriptor file (fileupload.tld) to the /WEB-INF/tld subdirectory of your web application.
• Copy the tag library JAR file (xephyrus-fileupload.jar) to the /WEB-INF/lib subdirectory of your web application.
• Copy the file upload support JAR file (jakarta-fileupload.jar) to the /WEB-INF/lib subdirectory of your web application.
• Add a <taglib> element to your web application deployment descriptor in /WEB-INF/web.xml that looks like this:
  <taglib>
    <taglib-uri>/xephyrus-fileupload</taglib-uri>
    <taglib-location>/WEB-INF/tld/xephyrus-fileupload.tld</taglib-location>
  </taglib>
  

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

where "fup" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

A simple example of a JSP using the Xephyrus File Upload Tag Library is available in full syntax-color highlighting.
  View It   Run It

The parse tag must be used exactly once per file-upload request before any parameters or uploaded files are accessed.

The param tag provides access to non-file parameters that were part of the file-upload request processed by the 'parsed' tag.

The file tag provides access to file-items that were part of the file-upload request processed by the 'parsed' tag.

The contents tag provides access to the contents of the indicated uploaded file-item that were part of the file-upload request processed by the 'parsed' tag.

The contentType tag provides access to the content-type of the indicated uploaded file-item.

The localPath tag provides access to the client-side path of the indicated uploaded file-item.

The name tag provides access to the submitted form-field name of the indicated uploaded file-item.

The remotePath tag provides access to the servers temporary storage path for the indicated uploaded file-item. If the file is smaller than the specified sizeThreshold (see the 'parse' tag), it will be held in memory rather than on disk. In that case, this will provide nothing.

The size tag provides access to the size in bytes of the indicated uploaded file-item.

The write tag writes out the contents of the indicated uploaded file-item to the file specified. It outputs the full path of the newly written file to the specified var or the current output.

The delete tag removes the temporary storage of the indicated uploaded file-item.