30th of April, 2010
One of the most requested features on any site that accepts file submissions is the ability to handle multiple uploads elegantly. The current HTML standard only permits one file upload at a time, which makes transferring a large number of files quite tedious.
This tutorial will show how to painlessly integrate Uploadify and Java using Apache Wicket. You should have at least beginner-level knowledge of Wicket before moving forward, but feel free to dive right in even if you’ve never used Wicket before. (If you haven’t used Wicket before, I can’t suggest it strongly enough for developing stateful Java-based web applications.)
A number of excellent Flash-based multiple file upload plugins are available, including the excellent Uploadify. Uploadify is essentially a jQuery wrapper for SWFUpload. I already use jQuery quite extensively so I chose Uploadify as my multiple upload plugin. If you use a different JavaScript framework or simply prefer plain old JavaScript, SWFUpload might be a better choice.
The only catch is that most of these plugins are geared towards PHP developers/apps and not all that intuitive to integrate with Java-based solutions.
Before jumping in with both feet, the use of Flash is a stopgap measure until HTML5 is more widely supported. HTML5 supports the attribute “multiple” in the input tag, offering true native multiple file upload support. Also, with Apple fully throwing its weight behind HTML5 and actively attacking Flash, it’s only a matter of time before Flash-based solutions go the way of the bond market in Greece.
While HTML5 supports the attribute “multiple” in the input tag, browser support for HTML5 is far from ubiquitous. To make matters worse, the HTML5 standard won’t officially be signed off on until 2022. Yes, 12 more years. Yes, it’s completely ridiculous. That’s how design-by-committee works.
Preamble complete, let’s get down to business. Our strategy will be to create a re-usable Apache Wicket “multiple file upload” component. In our case, because we will be re-using both Java code and HTML, we’ll create a Wicket panel to do this.
We don’t need everything included in the Uploadify download. We’ll create new packages for the components, CSS, and scripts, and cherry-pick the Uploadify artifacts to copy to the new project. Depending on how you have Wicket configured, your scripts, CSS, and HTML files may be separate from Java source files. The default in Wicket is to place them together in the same package, so we’ll be using that paradigm for this tutorial.
The next step is to create the HTML for our Panel. Create a new file called UploadifyPanel.html with the following source:
1<wicket:panel>
2
3<div id="fileQueue">
4 <p><strong>Click browse to select files for uploading.</strong></p>
5 <p><em>To select more than one file, hold down control or shift.</em></p>
6 <p><input type="file" name="uploadify" id="uploadify" /></p>
7</div>
8
9</wicket:panel>Most of what you see above is standard HTML and CSS. The only item of note is the input tag, which will be replaced with the Flash component by the Uploadify script. If the user does not have Flash installed, the above input tag will be used as-is without replacement, so make sure the tag is valid for graceful downgrading.
If you want to enhance the tutorial, you should use Wicket’s excellent localization support to add fully configurable dynamic text to the re-usable component.
1package org.rocketpages.wicket.component.uploadify;
2
3import org.apache.wicket.markup.html.CSSPackageResource;
4import org.apache.wicket.markup.html.JavascriptPackageResource;
5import org.apache.wicket.markup.html.panel.Panel;
6import org.apache.wicket.util.template.TextTemplateHeaderContributor;
7
8public class UploadifyPanel extends Panel {
9 private static final long serialVersionUID = 1L;
10
11 public UploadifyPanel(String id, UploadifyPanelBehaviour behaviour) {
12 super(id);
13
14 add(JavascriptPackageResource.getHeaderContribution(UploadifyPanel.class, "scripts/swfobject.js"));
15 add(JavascriptPackageResource.getHeaderContribution(UploadifyPanel.class, "scripts/jquery.uploadify.v2.1.0.js"));
16
17 /* TextTemplateHeaderContributor performs text substitution of values located
18 in multiupload.js with the values obtained from the behaviour, and
19 inserts the processed .js in the header. */
20 add(TextTemplateHeaderContributor.forJavaScript(UploadifyPanel.class, "multiupload.js", behaviour.getVariables()));
21 add(CSSPackageResource.getHeaderContribution(UploadifyPanel.class, "css/uploadify.css"));
22 }
23}For those of you familiar with Wicket, most of this will look straightforward enough. We’re encapsulating all of our configuration variables in a behaviour, which keeps our code clean and generic. Of special interest is the call to TextTemplateHeaderContributor.forJavaScript(). This is a handy little method that allows you to pass in a Map of variables (key/value) and a reference to a JavaScript file. This results in token substitution in the JavaScript file based on the values in the Map. It’s much more simple than performing manual string concatenation to achieve the same result.
1public class UploadifyPanelBehaviour implements Serializable {
2 private String fileExt = "";
3 private String fileDesc = "";
4 private String sizeLimit = "";
5
6 private final String formTokenId;
7 private final String formSessionId;
8
9 private Class<? extends UploadifyFileProcessPage> fileProcessPageClass;
10
11 public UploadifyPanelBehaviour(Class<? extends UploadifyFileProcessPage> fileProcessPageClass, String tokenId, String sessionId)
12 {
13 this.fileProcessPageClass = fileProcessPageClass;
14 this.formSessionId = sessionId;
15 this.formTokenId = tokenId;
16 }
17
18 /**
19 * Sets the valid file extensions for the uploader.
20 *
21 * Do not include leading or trailing quotes, only semi-colon
22 * separated wildcards.
23 *
24 * Example usage:
25 * *.doc;*.docx;*.pdf;*.jpg;*.png;*.zip
26 *
27 * @param validExts
28 */
29 public void setFileExt(String validExts)
30 {
31 this.fileExt = validExts;
32 }
33
34 /**
35 * Sets the message to be displayed when selecting files.
36 *
37 * Example message:
38 * Select files of type .doc, .pdf, .jpg, .png, or .zip
39 *
40 * @param fileDesc
41 */
42 public void setFileDesc(String fileDesc)
43 {
44 this.fileDesc = fileDesc;
45 }
46
47 /**
48 * Sets the size limit, in bytes.
49 *
50 * Example: 3072000
51 *
52 * @param sizeLimit
53 */
54 public void setSizeLimit(String sizeLimit)
55 {
56 this.sizeLimit = sizeLimit;
57 }
58
59 /**
60 * Builds a variables model in order to perform text substitution
61 * on values located in JavaScript (multiupload.js)
62 *
63 * The key values in the Map must match the tokens in the .js file.
64 *
65 * @return
66 */
67 protected IModel getVariables() {
68 IModel variablesModel = new AbstractReadOnlyModel() {
69 public Map getObject() {
70 Map<String, CharSequence> variables = new HashMap<String, CharSequence>();
71
72 //Mandatory configuration
73 variables.put("uploader", RequestCycle.get().urlFor(new CompressedResourceReference(UploadifyPanel.class, "scripts/uploadify.swf")).toString());
74 variables.put("cancelImg", RequestCycle.get().urlFor(new CompressedResourceReference(UploadifyPanel.class, "cancel.png")).toString());
75 variables.put("script", ";jsessionid=" + formSessionId + RequestCycle.get().urlFor(fileProcessPageClass, null));
76 variables.put("tokenId", formTokenId);
77
78 //Optional configuration
79 variables.put("fileExt", fileExt);
80 variables.put("fileDesc", fileDesc);
81 variables.put("sizeLimit", sizeLimit);
82
83 return variables;
84 }
85 };
86
87 return variablesModel;
88 }
89}The behaviour captures configuration options, which correspond to the available options within Uploadify. You can add more configuration options (or remove some) depending on your specific requirements.
Another quirk to pay attention to is the token and session id values. This is a kludge we’ve added to avoid the messy problem of Flash losing a reference to the HttpSession. Because the end result of this script will be a call to a stateless page to process our uploads, we’ll need some way to retrieve the user’s session. Because of this, we need to include the session ID as a value in the JavaScript file and pass this as a parameter to our stateless file processing page.
Finally, make special note of the class we’re passing to our behaviour object. We do this because Wicket needs to “mount” our stateless file processing page so it can be accessed by the plugin. Wicket instantiates the page “just in time”, not before, otherwise it would hang around in memory doing nothing (kinda like a TTC collector). Note the call to RequestCycle.get().urlFor().
1public abstract class UploadifyFileProcessPage extends WebPage {
2
3 protected User user;
4
5 public UploadifyFileProcessPage(PageParameters params) {
6 HttpServletRequest r = ((WebRequest) RequestCycle.get().getRequest()).getHttpServletRequest();
7 try
8 {
9 MultipartServletWebRequest r2 = new MultipartServletWebRequest(r, Bytes.MAX);
10 Map paramMap = r2.getParameterMap();
11 String[] tokenIdParms = (String[]) paramMap.get("tokenId");
12 String tokenId = tokenIdParms[0];
13 UserSession session = (UserSession) Session.get();
14 FormToken token = session.getFormToken();
15
16 if (token.isValid(tokenId, r.getRemoteAddr()))
17 {
18 long userId = session.getUser().getId();
19 user = new UserServiceImpl().getUser(userId);
20
21 for (FileItem fi : r2.getFiles().values())
22 {
23 processFileItem(fi);
24 fi.delete();
25 }
26 }
27 else
28 {
29 throw new Exception("Invalid token!");
30 }
31 }
32 catch (Exception e)
33 {
34 e.printStackTrace();
35 }
36 }
37
38 protected abstract void processFileItem(FileItem fileItem) throws Exception;
39}In order to bridge our plugin with Java, we’re creating a stateless page by extending WebPage. This base code is fairly straightforward, pulling out the file data from the request, and passing it to the yet-to-be-defined abstract method processFileItem().
The only other thing to note is the token logic. This is simply an example/placeholder to draw your attention to security when dealing with jsessionid directly. This leaves a small window open for hackers to perform a session hijacking, so in our scenario, we associate a jsessionid with an IP address and an additional token value.
1$(document).ready(function() {
2 $('#uploadify').uploadify({
3 'uploader': '${uploader}',
4 'script': '${script}',
5 'scriptData': {'tokenId': '${tokenId}'},
6 'folder': '/var/photos/stuffahoy',
7 'cancelImg': '${cancelImg}',
8 'fileExt' : '${fileExt}',
9 'fileDesc' : '${fileDesc}',
10 'sizeLimit' : '${sizeLimit}',
11 'auto': true,
12 'multi': true,
13 onAllComplete: function(event, queueID, fileObj, response, data) {
14 uploadCompleted();
15 }
16 });
17});If you’re familiar with JavaScript, you’ll see we’re essentially passing an object to the uploadify() method. The key values of the object correspond to the Uploadify options. The token values on the right correlate to our behaviour class and the key values we defined. Text substitution is done on these when we include the JavaScript file via the call to TextTemplateHeaderContributor.
1public class AddPhotosProcessingPage extends UploadifyFileProcessPage {
2 public AddPhotosProcessingPage(PageParameters params)
3 {
4 super(params);
5 }
6
7 @Override
8 protected void processFileItem(FileItem fileItem) throws Exception
9 {
10 //Wrap the Apache Commons FileItem type in a Wicket FileUpload type
11 FileUpload upload = new FileUpload(fileItem);
12 //Get a service reference, store the photo, and create a new Photo record
13 PhotoService photoService = new PhotoServiceImpl();
14 Photo photo = photoService.saveUploadedPhoto(upload, true);
15 photo.setUser(user);
16 photoService.savePhoto(photo);
17 }
18}This is our actual stateless page that extends our more generic file processor. The code is an example of business logic you may execute on each file. In this case, we’re processing image files, so we pass the file reference to a service which in turn writes the file to disk (or Amazon S3, etc) and persists the information in our database.
1public class AddPhotosPage extends UserRoleSuperPage {
2 private static final long serialVersionUID = 1L;
3
4 private Label noPhotosLabel;
5
6 public AddPhotosPage(final PageParameters parameters) {
7 this();
8 }
9
10 public AddPhotosPage() {
11 super(null);
12
13 add(CSSPackageResource.getHeaderContribution(AddPhotosPage.class,
14 "css/AddPhotosPage.css"));
15
16 UserSession session = (UserSession) Session.get();
17 long userId = session.getUser().getId();
18
19 HttpServletRequest r = ((WebRequest) RequestCycle.get().getRequest()).getHttpServletRequest();
20 session.createFormToken(r.getRemoteAddr());
21
22 String tokenId = session.getFormToken().getToken();
23 String sessionId = session.getId();
24
25 // Configure the panel
26 UploadifyPanelBehaviour behaviour = new UploadifyPanelBehaviour(AddPhotosProcessingPage.class, tokenId, sessionId);
27 behaviour.setFileExt("*.jpg;*.jpeg;*.gif;*.png");
28 behaviour.setFileDesc("Select files of type *.jpg, *.jpeg, *.gif, *.png");
29 behaviour.setSizeLimit("3000000");
30
31 add(new UploadifyPanel("uploads", behaviour));
32
33 final UnprocessedPhotosPanel unprocessedPanel;
34 add(unprocessedPanel = new UnprocessedPhotosPanel("unprocessedPhotos", userId));
35 unprocessedPanel.setOutputMarkupId(true);
36
37 final Label noPhotosLabel;
38 add(noPhotosLabel = new Label("noPhotosLabel", "You haven't uploaded any new photos!"));
39 noPhotosLabel.setOutputMarkupId(true);
40
41 if (unprocessedPanel.getUnprocessedPhotosCount() > 0) {
42 noPhotosLabel.setVisible(false);
43 }
44 else {
45 noPhotosLabel.setVisible(true);
46 }
47
48 final IBehavior repaintBehavior = new AbstractDefaultAjaxBehavior() {
49 @Override
50 protected void respond(AjaxRequestTarget target)
51 {
52 if (unprocessedPanel.getUnprocessedPhotosCount() > 0) {
53 noPhotosLabel.setVisible(false);
54 }
55 else {
56 noPhotosLabel.setVisible(true);
57 }
58
59 target.addComponent(noPhotosLabel);
60 target.addComponent(unprocessedPanel);
61 }
62
63 @Override
64 public void renderHead(IHeaderResponse response)
65 {
66 super.renderHead(response);
67 CharSequence callback = getCallbackScript();
68 response.renderJavascript("function uploadCompleted() { " + callback + "}", "customUploadCompleted");
69 }
70 };
71
72 add(repaintBehavior);
73
74 add(new Image("easy", new ResourceReference(AddPhotosPage.class, "easy.png")));
75 }
76}This example is a little long-winded, but it ties everything together and shows a few key concepts. Most interesting is our ability to asynchronously invoke a piece of code when all uploads are complete by using Wicket’s fantastic built in Ajax support. We do this by creating a new repaintBehaviour object and overriding both respond (which contains the actual code we want to invoke asynchronously) and renderHead (which injects this callback method inside our HTML).
Other than that, most things are quite straightforward. We tie everything together by configuring our behaviour object and instantiating the processing page.
Enabling true multiple upload support is fairly straightforward with the Flash plugins readily available. Uploadify is my favourite, but there are a ton to choose from. Integrating with Apache Wicket is a piece of cake, and as always, Wicket just makes life a little easier for Java developers.