Skip to main content

Better File Uploads with AJAX and JavaServer Faces

February 9, 2006


Browser-based file uploads, in particular those involving the
HTML tag, have always been
rather lacking. As I am sure most of you are aware, uploading files
exceeding 10MB often causes a very poor user experience. Once a
user submits the file, the browser will appear to be inactive while
it attempts to upload the file to the server. While this happening
in the background, many impatient users would start to assume that
the server is "hanging" and would try to submit the file again.
This of course, only helps to make matters worse.

In an attempt to make uploading of files more user-friendly,
many sites display an indeterminate progress animation (such as a
rotating icon) once the user submits the file. Although this
technique may be useful in keeping the user distracted while the
upload being submitted to the server, it offers very little
information on the status of the file upload. Another attempt at
solving the problem is to implement an applet that uploads the file
to the server through FTP. The drawback with this solution is that
it limits your audience to those that have a Java-enabled

In this article, we will take fresh approach and implement an
AJAX-powered component that will not only upload the file to
server, but also monitor the actual progress of a file upload
request in "real time." The four stages of this component are
illustrated below, in Figures 1, 2, 3, and 4:

<br "Stage 1: Selecting the file upload" />
Figure 1. Stage 1: Selecting the file upload

<br "Stage 2: Uploading the file to the server" />
Figure 2. Stage 2: Uploading the file to the server

<br "Stage 3: Uploaded completed." />
Figure 3. Stage 3: Uploaded completed

File Upload Summary
Figure 4. File upload summary

Implementing the Component

We will first walk through the process of creating the multipart
filter that will allow us to handle and monitor the file upload. We
will then move on to implementation of the JavaServer Faces
component that will provide the user with continuous feedback in
the form of an AJAX-enabled progress bar.

The Multipart Filter: UploadMultipartFilter

The responsibility of the multipart filter is to intercept the
incoming file upload and write the file to a temporary directory on
the server. At the same time, it will also monitor the amount of
bytes received and determine how much of the file has been
uploaded. Fortunately, there is an excellent Jakarta-Commons open
source library available ( "">FileUpload)
that takes care of parsing an HTTP multipart request and writing a
file upload to disk. We will be extend this library and add in the
required "hooks" we need to monitor how many bytes have been

public class UploadMultipartFilter implements Filter{      
   public void doFilter(ServletRequest request, 
                        ServletResponse response, 
                        FilterChain chain)
                throws IOException, ServletException {
      HttpServletRequest hRequest = (HttpServletRequest)request;
      //Check whether we're dealing with a multipart request
      String contentHeader = hRequest.getHeader("content-type");
      boolean isMultipart = ( contentHeader != null &&
                              contentHeader.indexOf("multipart/form-data") != -1); 
      if(isMultipart == false){
        UploadMultipartRequestWrapper wrapper = 
              new UploadMultipartRequestWrapper(hRequest);

As you can see, the UploadMultipartFilter class
simply checks to see whether the current request is a multipart
request. If the request does not contain a file upload, the request
is passed on to the next filter in the chain without any additional
processing. Otherwise, the request is wrapped in an

The UploadMultipartRequestWrapper Class
 public class UploadMultipartRequestWrapper 
               extends HttpServletRequestWrapper{
   private Map<String,String> formParameters;
   private Map<String,FileItem> fileParameters;

   public UploadMultipartRequestWrapper(HttpServletRequest request) {
        ServletFileUpload upload = new ServletFileUpload();
        upload.setFileItemFactory(new ProgressMonitorFileItemFactory(request));
        List fileItems = upload.parseRequest(request);
        formParameters = new HashMap<String,String>();
        fileParameters = new HashMap<String,FileItem>();
        for(int i=0;i<fileItems.size();i++){
           FileItem item = (FileItem)fileItems.get(i);
           if(item.isFormField() == true){
      }catch(FileUploadException fe){
       //Request Timed out - user might have gone to other page.
      //Do some logging

In our UploadMultipartRequestWrapper class, we
initialize the commons

class that will parse our request and write the file to the default temporary directory on the server.
instance creates a
instance for each field that is encountered in
the request. These include both file uploads and normal form
elements. A
instance can then be used to retrieve the
properties of a submitted field, or, in the case of a file upload,
an InputStream to the underlying temporary file to which it has been saved. In summary, the
UploadMultipartRequestWrapper basically parses the
file and sets any
s that represent file uploads as attributes in
the request. These can then be picked up by JSF components further
down the line. The behavior of normal form fields remains the

By default, the "">Commons FileUpload
use instances of the

class to handle file uploads. Although
s are very useful in handling the whole
temporary-file business, there is very little support for
monitoring exactly how much of the file has been processed. Since
version 1.1, the "">Commons FileUpload
provides developers with the ability to specify the
factory that will be used to create the
. We will use the
ProgressMonitorFileItemFactory and
ProgressMonitorFileItem classes to override the
default behavior and monitor the progress file uploads.

The ProgressMonitorFileItemFactory Class
public class ProgressMonitorFileItemFactory 
                 extends DiskFileItemFactory {
  private File temporaryDirectory;
  private HttpServletRequest requestRef;
  private long requestLength;
  public ProgressMonitorFileItemFactory(HttpServletRequest request) {
    temporaryDirectory = (File)request.getSession().getServletContext().
    requestRef = request;
    String contentLength = request.getHeader("content-length");
    if(contentLength != null){
       requestLength = Long.parseLong(contentLength.trim());
  public FileItem createItem(String fieldName, String contentType,
                             boolean isFormField, String fileName) {
    SessionUpdatingProgressObserver observer = null;
    if(isFormField == false) //This must be a file upload.
       observer = new SessionUpdatingProgressObserver(fieldName,
       ProgressMonitorFileItem item = new ProgressMonitorFileItem(
       return item;
  public class SessionUpdatingProgressObserver 
                  implements ProgressObserver {
     private String fieldName;
     private String fileName;
    public void setProgress(double progress) {
      if(request != null){
        request.getSession().setAttribute("FileUpload.Progress." + fieldName,
        request.getSession().setAttribute("FileUpload.FileName." + fieldName,

The ProgressMonitorFileItemFactory uses the
Content-Length header set by the browser and assumes it to be the
accurate length of the upload file being sent. This method of
determining the file length does limit you to uploading only one
file per request--it's inaccurate if more than more file is
encoded in the request. This is due to the fact that browsers only
send one Content-Length header, regardless of the number of files
in the upload.

In addition to creating ProgressMonitorFileItem
instances, the ProgressMonitorFileItemFactory also
registers a ProgressObserver instance that will be
used by the ProgressMonitorFileItem to send updates on
the progress of the file upload. The implementation of the
ProgressObserver used,
SessionUpdatingProgressObserver, sets the progress
percentage into the user's session under the id of the submitted
field. This value can then be accessed by the JSF component in
order to send updates to the user.

The ProgressMonitorFileItem Class
public class ProgressMonitorFileItem extends DiskFileItem {
   private ProgressObserver observer;
   private long passedInFileSize;
   private boolean isFormField;
   public OutputStream getOutputStream() throws IOException {
      OutputStream baseOutputStream = super.getOutputStream();
      if(isFormField == false){
         return new BytesCountingOutputStream(baseOutputStream);
         return baseOutputStream;
   private class BytesCountingOutputStream extends OutputStream{
      private long previousProgressUpdate;
      private OutputStream base;
      public BytesCountingOutputStream(OutputStream ous){
         base = ous;
      private void fireProgressEvent(int b){
         bytesRead += b;
                 double progress = (((double)(bytesRead)) / passedInFileSize);
                 progress *= 100.0

The ProgressMonitorFileItem wraps the default
OutputStream of the

in a
BytesCountingOutputStream, which updates the
associated ProgressObserver every time a certain
number of bytes have been read.

The AJAX-Enabled JavaServer Faces Upload Component

This component is responsible for rendering the HTML file upload
tag, displaying a progress bar to monitor the file upload, and
rendering the components that need to be displayed once a file has
been successfully uploaded. One of the main advantages to
implementing this component using JavaServer Faces is the fact that
most of the complexities are hidden from the page author. The page
author only needs to add the component tag to the JSP and the
component will take care of all of the AJAX and progress-monitoring
details. Below is the JSP code snippet that is used to add the
upload component to the page.



<%--Below are the components that will be 
    visible once the file upload completes--%>
  <h:panelGrid columns="2" cellpadding="2" cellspacing="0" width="100%">
    <f:facet name="header">
       <h:outputText styleClass="text"
       value="File Upload Successful." />
    <h:panelGroup style="text-align:left;display:block;width:100%;">
      <h:commandButton action="#{uploadPageBean.reset}"
    <h:panelGroup style="text-align:right;display:block;width:100%;">
       <h:commandButton action="#{uploadPageBean.nextPage}"


The value attribute of the file upload component
needs to be bound to a bean with a property that holds a

. The child components are only displayed once
the file has been successfully received by the server.

Implementing the AJAX File Upload Component

The progress bar of the component was inspired by the " "">
Progress Bar Using JavaServer Faces Component with AJAX
solution as detailed in the "">Java
BluePrints Solution Catalog
. In essence, the upload component
either renders a complete version of itself, or in the case of an
AJAX request, only a bit of XML to update the state of the progress
bar on the page. In order to prevent JavaServer Faces from
rendering the complete component tree (which would incur
unnecessary overhead), we also need to implement a

(PagePhaseListener) to abort
the rest of the faces' request processing if an AJAX request is
encountered. I have omitted all of the standard configuration
(faces-config.xml and tag libraries) from the article, as
these are very straightforward and have been "">covered
. Everything is, however, included in the source code
download for this article (in the "#resources">Resources section) if you wish to review them.

The AJAX File Upload Component Renderer

The implementation of the component and tag classes is rather
straightforward. The bulk of the logic is contained in the
renderer, which has the following responsibilities:

Encoding the Full Upload Component

As mentioned previously, the file upload component is composed of
three stages. During the full encoding of the component, we will
encode all three stages. Their visibility (using the CSS display
property) on the page will then be controlled by the AJAX

Stage 1

Figure 5 shows stage 1 of the upload component.

<br "Stage 1: Selecting the file upload" />
Figure 5. Stage 1: Selecting the file upload

In Stage 1, we need to render the HTML file upload tag and the
button that will be responsible for starting off this process. Once
the user clicks the upload button, the form is submitted through an
IFRAME ( to prevent blocking on the page) and the second stage of
the process is initiated. Below is an extract of the rendering code

 //The File upload component
writer.startElement("input", component);
writer.writeAttribute("type", "file", null);
writer.writeAttribute("name", component.getClientId(context), "id");
writer.writeAttribute("id", component.getClientId(context),"id");
if(input.getValue() != null){
  //Render the name of the file if available.
  FileItem fileData = (FileItem)input.getValue();
  writer.writeAttribute("value", fileData.getName(), fileData.getName());

String iconURL = input.getUploadIcon();
//Render the image, and attach the JavaScript event to it.
writer.startElement("div", component);
writer.writeAttribute("style","display:block;width:100%;text-align:center;", "style");
writer.startElement("img", component);

UIForm form = FacesUtils.getForm(context,component);
if(form != null) {
  String getFormJS = "document.getElementById('" + form.getClientId(context) + "')";
  String jsFriendlyClientID = input.getClientId(context).replace(":","_");
  //Sets the encoding of the form to be multipart required for file uploads and
  //to submit its content through an IFRAME. The second stage of the component is
  //also initialized after 500 milliseconds.
  writer.writeAttribute("onclick",getFormJS + ".encoding='multipart/form-data';" +
    getFormJS + ".target='" + iframeName + "';" + getFormJS + ".submit();" +
    getFormJS + ".encoding='application/x-www-form-urlencoded';" +
    getFormJS + ".target='_self';" +
    "setTimeout('refreshProgress" + jsFriendlyClientID + "();',500);",
//Now do the IFRAME we are going to submit the file/form to.
writer.startElement("iframe", component);
writer.writeAttribute("id", iframeName, null);
writer.endElement("div"); //End of Stage1

Stage 2

Stage 2 of the component is the progress bar and the label that
indicates the current percentage, as seen in Figure 6. The progress
bar is implemented as a div tag with 100
embedded span tags. These will be set by the AJAX
JavaScript based on the response received from the server.

<br "Figure 6. Stage 2: Uploading the file to the server" />
Figure 6. Stage 2: Uploading the file to the server

writer.startElement("div", component);
writer.writeAttribute("id", input.getClientId(context) + "_stage2", "id");
writer.writeAttribute("style","display:none", "style");
String progressBarID = component.getClientId(context) + "_progressBar";
String progressBarLabelID = component.getClientId(context) + "_progressBarlabel";
writer.startElement("div", component);
String progressBarStyleClass = input.getProgressBarStyleClass();

if(progressBarStyleClass != null) 

for(int i=0;i<100;i++){
  writer.write("<span> </span>");

writer.startElement("div", component);
writer.endElement("div"); //End of Stage2

Stage 3

Finally, the components that need to be displayed once a
file has been successfully uploaded, seen in Figure 7, are rendered
as part of Stage 3. These are done in the
encodeChildren method of the renderer.

<br "Stage 3: Uploaded completed." />
Figure 7. Stage 3: Uploaded completed

public void encodeChildren(FacesContext context, 
            UIComponent component) throws IOException {
  ResponseWriter writer = context.getResponseWriter();
  UIFileUpload input = (UIFileUpload)component;
  //Do the children that will be shown once the 
  //file has been successfully uploaded
  writer.startElement("div", component);
  writer.writeAttribute("id", input.getClientId(context) + "_stage3", "id"); //Stage3.
  if(input.getValue() == null){
  List<UIComponent> children = input.getChildren();
  for(UIComponent child : children){
  writer.endElement("div"); //End of Stage3

Handling AJAX Requests

The rendering of AJAX requests is handled in the
decode method of this component, in accordance with
recommendations in the "">Java
BluePrints Solution Catalog.
We need to check whether this is
in fact an AJAX request (to differentiate from normal decoding
behavior) and then send back an XML response to the client based on
the values that have been set in the session by the
SessionUpdatingProgressObserver instance in the
ProgressMonitorFileItemFactory class.

public void decode(FacesContext context, UIComponent component) {
  UIFileUpload input = (UIFileUpload) component;
  //Check whether this is a request for the 
  //progress of the upload, or if it is an actual
  // upload request.
  ExternalContext extContext = context.getExternalContext();
  Map parameterMap = extContext.getRequestParameterMap();
  String clientId = input.getClientId(context);
  Map requestMap = extContext.getRequestParameterMap();
  if(requestMap.get(clientId) == null){
    //Nothing to do.
  //This is a request to get the progress on the file request.
  //Get the progress and render it as XML
    HttpServletResponse response = (HttpServletResponse)
    // set the header information for the response
    response.setHeader("Cache-Control", "no-cache");
    try {
      ResponseWriter writer = FacesUtils.setupResponseWriter(context);
      writer.startElement("progress", input);
      writer.startElement("percentage", input);
      //Get the current progress percentage from 
      //the session (as set by the filter).
      Double progressCount = (Double)extContext.getSessionMap().
                              get("FileUpload.Progress." + 
      if(progressCount != null){
        writer.writeText(progressCount, null);
      //We haven't received the upload yet.
        writer.writeText("1", null);
      writer.startElement("clientId", input);
      writer.writeText(input.getClientId(context), null);
    } catch(Exception e){
     //Do some sort of error logging...
   //Normal decoding request.

Normal Decoding Behavior

During normal decoding, the file upload renderer retrieves the

from the request attributes, where it has been
set by the filter, and updates the component's value binding. The
progress in the session is then updated to 100 percent so that the
JavaScript on the page can move the component into Stage 3.

//Normal decoding request.
    HttpServletRequest request = (HttpServletRequest)extContext.getRequest();
    FileItem fileData = (FileItem)request.getAttribute(clientId);
    if(fileData != null) input.setSubmittedValue(fileData);
    //Now we need to clear any progress associated with this item.
    extContext.getSessionMap().put("FileUpload.Progress." + 
                                   new Double(100));
  }catch(Exception e){
     throw new RuntimeException("Could not handle file upload" + 
                                " - please configure the filter.",e);

The client-side JavaScript is responsible for making progress
requests to the server and for moving the component through the
different stages. To cut out the usual boilerplate code associated
with handling all of the browser-specific quirks of the


object, I've opted for the excellent "">AjaxRequest.js library provided
by Matt Krause. This library allows us to considerably reduce the
amount of JavaScript code we need to write to get this component
working. Although it is probably best practice to package the
JavaScript code as part of the component and then to render it from
(as detailed "">here
), I've tried to keep it simple by defining a link to the
JavaScript library on the JSP page.

The getProgressBarJavaScript method in the
component is called to render the JavaScript. Getting the
JavaScript correct is usually the most painful part of implementing
any AJAX component; hopefully, the code below is clear enough to
be easily understood. While the JavaScript in my example is
embedded within the Java code, it is probably better practice to
externalize it into a separate file. For the purposes of this
article I wanted to keep it simple and to the point. Below is an
example of the JavaScript that would be rendered by the component.
It is assumed that fileUpload1 is the client-side JSF Id assigned
to the file component, while uploadForm is the Id of the HTML

 function refreshProgress(){ 
  // Assume we are entering stage 2.
  document.getElementById('fileUpload1_stage1').style.display = 'none';
  document.getElementById('fileUpload1_stage2').style.display = '';
  document.getElementById('fileUpload1_stage3').style.display = 'none';

  // Create the AJAX post 
    //Specify the correct parameters so that 
    //the component is correctly handled on 
    //the server side.
     'parameters':{ 'uploadForm':'uploadForm',
     'ajax.abortPhase':'4' } //Abort at Phase 4.
    // Specify the callback method for successful processing.
    ,'onSuccess':function(req) { 
       var xml = req.responseXML;
       if( xml.getElementsByTagName('clientId').length == 0) { 
       var clientId = xml.getElementsByTagName('clientId');
       clientId = clientId[0].firstChild.nodeValue + '_progressBar';
       //Get the percentage from the XML
       var percentage = xml.getElementsByTagName('percentage')[0].firstChild.nodeValue;
       var innerSpans = document.getElementById(clientId).getElementsByTagName('span');
       document.getElementById(clientId + 'label').innerHTML = Math.round(percentage) + '%';

       // Set the style classes of the spans based on the current progress.
       for(var i=0;i<innerSpans.length;i++){
          if(i < percentage){
             innerSpans[i].className = 'active';
             innerSpans[i].className = 'passive'; 
// If the percentage is not 100, we need to carry
// on polling the server for updates.
       if(percentage != 100){ 
       } else { 
// The file upload is done - we now 
//need to move the component into stage 3.
        document.getElementById('fileUpload1_stage1').style.display = 'none';
        document.getElementById('fileUpload1_stage2').style.display = 'none'; 
        document.getElementById('fileUpload1_stage3').style.display = '';
return builder.toString();



Hopefully, this article offered you some insight on how to make
file uploads more user-friendly, and on the possibilities of
combining AJAX and JavaServer Faces for advanced user interface
components. The solution in this article is by no means exhaustive
and could probably be further improved. I would encourage you to
look at the complete source code to gain a deeper understanding of
the concepts discussed here.


width="1" height="1" border="0" alt=" " />
Jacobus Steenkamp has been developing in Java for the last 4.5 years and has worked in various sectors including the financial, pharmaceutical and energy industries.
Related Topics >> Programming   |   Web Design   |   Web Development Tools   |   


I can't download source code

I can't download source code in Anybody help me?

&nbsp;You need to login to download the file. Regards,

You need to login to download the file.


<%@ taglib uri="/tags/taglib"

<%@ taglib uri="/tags/taglib" prefix="comp"%> i don't know the exact jar file ror support the above taglib. Where i can get the library for support the comp:fileUpload tag. Help me. Thanks in advance.