Better File Uploads with AJAX and JavaServer Faces

Browser-based file uploads, in particular those involving the HTML <input type="file"> 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 browser. 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: Figure 1. Stage 1: Selecting the file upload Figure 2. Stage 2: Uploading the file to the server Figure 3. Stage 3: Uploaded completed 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 processed. 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){ chain.doFilter(request,response); }else{ UploadMultipartRequestWrapper wrapper = new UploadMultipartRequestWrapper(hRequest); chain.doFilter(wrapper,response); } ... } 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 UploadMultipartRequestWrapper. The UploadMultipartRequestWrapper Class public class UploadMultipartRequestWrapper extends HttpServletRequestWrapper{ private Map<String,String> formParameters; private Map<String,FileItem> fileParameters; public UploadMultipartRequestWrapper(HttpServletRequest request) { super(request); try{ 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){ formParameters.put(item.getFieldName(),item.getString()); }else{ fileParameters.put(item.getFieldName(),item); request.setAttribute(item.getFieldName(),item); } } }catch(FileUploadException fe){ //Request Timed out - user might have gone to other page. //Do some logging //... } ... In our UploadMultipartRequestWrapper class, we initialize the commons ServletFileUpload class that will parse our request and write the file to the default temporary directory on the server. The ServletFileUpload instance creates a FileItem instance for each field that is encountered in the request. These include both file uploads and normal form elements. A FileItem 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 FileItems 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 same. By default, the Commons FileUpload library use instances of the DiskFileItems class to handle file uploads. Although DiskFileItems 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 library provides developers with the ability to specify the factory that will be used to create the FileItem. 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) { super(); temporaryDirectory = (File)request.getSession().getServletContext(). getAttribute("javax.servlet.context.tempdir"); 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, fileName); ProgressMonitorFileItem item = new ProgressMonitorFileItem( fieldName, contentType, isFormField, fileName, 2048, temporaryDirectory, observer, requestLength); 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, progress); request.getSession().setAttribute("FileUpload.FileName." + fieldName, fileName); } } } } 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; ... @Override public OutputStream getOutputStream() throws IOException { OutputStream baseOutputStream = super.getOutputStream(); if(isFormField == false){ return new BytesCountingOutputStream(baseOutputStream); }else{ 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 observer.setProgress(); } } } The ProgressMonitorFileItem wraps the default OutputStream of the DiskFileItem 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. <comp:fileUpload value="#{uploadPageBean.uploadedFile}" uploadIcon="images/upload.png" styleClass="progressBarDiv" progressBarStyleClass="progressBar" cellStyleClass="progressBarCell" activeStyleClass="progressBarActiveCell"> <%--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." /> </f:facet> <h:panelGroup style="text-align:left;display:block;width:100%;"> <h:commandButton action="#{uploadPageBean.reset}" image="images/reset.png"/> </h:panelGroup> <h:panelGroup style="text-align:right;display:block;width:100%;"> <h:commandButton action="#{uploadPageBean.nextPage}" image="images/continue.png"/> </h:panelGroup> </h:panelGrid> </comp:fileUpload> The value attribute of the file upload component needs to be bound to a bean with a property that holds a FileItem. 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 PhaseListener (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 before. Everything is, however, included in the source code download for this article (in the 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: Encode the full file upload component (complete with the HTML file upload tag), components to be displayed once a file has been uploaded, and the client-side JavaScript code to implement for the AJAX requests. Handle partial AJAX requests appropriately and send back the necessary XML. Decode a file upload and set it as a FileItem instance on the underlying value binding. 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 JavaScript. Stage 1 Figure 5 shows stage 1 of the upload component. 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()); } writer.endElement("input"); 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); writer.writeAttribute("src",iconURL,"src"); writer.writeAttribute("type","image","type"); writer.writeAttribute("style","cursor:hand;cursor:pointer;","style"); 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);", null); } ... writer.endElement("img"); //Now do the IFRAME we are going to submit the file/form to. writer.startElement("iframe", component); writer.writeAttribute("id", iframeName, null); writer.writeAttribute("name",iframeName,null); writer.writeAttribute("style","display:none;",null); writer.endElement("iframe"); writer.endElement("div"); 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. 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); writer.writeAttribute("id",progressBarID,"id"); String progressBarStyleClass = input.getProgressBarStyleClass(); if(progressBarStyleClass != null) writer.writeAttribute("class",progressBarStyleClass,"class"); for(int i=0;i<100;i++){ writer.write("<span> </span>"); } writer.endElement("div"); writer.startElement("div", component); writer.writeAttribute("id",progressBarLabelID,"id"); ... writer.endElement("div"); 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. 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){ writer.writeAttribute("style","display:none;",null); }else{ writer.writeAttribute("style","display:block",null); } List<UIComponent> children = input.getChildren(); for(UIComponent child : children){ FacesUtils.encodeRecursive(context,child); } 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. return; } if(parameterMap.containsKey(PROGRESS_REQUEST_PARAM_NAME)){ //This is a request to get the progress on the file request. //Get the progress and render it as XML HttpServletResponse response = (HttpServletResponse) context.getExternalContext().getResponse(); // set the header information for the response response.setContentType("text/xml"); 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." + input.getClientId(context)); if(progressCount != null){ writer.writeText(progressCount, null); }else{ //We haven't received the upload yet. writer.writeText("1", null); } writer.endElement("percentage"); writer.startElement("clientId", input); writer.writeText(input.getClientId(context), null); writer.endElement("clientId"); writer.endElement("progress"); } catch(Exception e){ //Do some sort of error logging... } }else{ //Normal decoding request. ... Normal Decoding Behavior During normal decoding, the file upload renderer retrieves the FileItem 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. if(requestMap.get(clientId).toString().equals("file")){ try{ 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." + input.getClientId(context), 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 XMLHttpRequest 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 a PhaseListener (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 form. 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 AjaxRequest.post( { //Specify the correct parameters so that //the component is correctly handled on //the server side. 'parameters':{ 'uploadForm':'uploadForm', 'fileUpload1':'fileUpload1', 'jsf.component.UIFileUpload':'1', '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) { setTimeout('refreshProgress()',200); return; } 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'; }else{ innerSpans[i].className = 'passive'; } } // If the percentage is not 100, we need to carry // on polling the server for updates. if(percentage != 100){ setTimeout('refreshProgress()',400); } 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(); Conclusion 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. Resources Source code for this article Commons FileUpload library: The library we used process the file uploads Java BluePrints Solution Catalog: " Using JavaServer Faces Technology with AJAX" Ajax Toolbox for more information on the AjaxRequest API used in this article 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. http://today.java.net/pub/a/today/2006/02/09/file-uploads-with-ajax-and-jsf.html