- FAQ -

Basic setup (7) Internationalization (11)
HTTP upload related (2) FTP upload related (3)
User's session (3) Security (10)
Large upload and compression (2) Resume and overwrite features (4)
Others (13) After upload (6)

Basic setup
  • What do I need to run JFileUpload ?
    You need Java (JRE 1.4 or higher) installed on client-side.
  • How to setup JFileUpload Applet ?
    JFileUpload applet includes two sample files: One for HTTP upload (see applet_http.html and applet_http.js) and one for FTP upload (see applet_ftp.html and applet_ftp.js). Edit and modify parameters in the JavaScript file (the one ending by .js) matching to your need.
  • Why all parameters must be setup twice ?
    You need to setup all parameters twice for cross-browser support. For instance, for "url" parameter you have to setup:
    ...
    url = "http://yourserver.com/upload.jsp"
    ...
    <PARAM name="url" value="http://yourserver.com/upload.jsp">
    ...
    JFileUpload applet works under Internet Explorer, Safari, Firefox, Netscape, Opera and Google chrome. See software section.
    It is recommended to copy/paste existing parameter when you want to add a new one. It will avoid typo mistake in the JavaScript.
  • I get "Connection refused" error message ?
    It means that "url" parameter of JFileUpload is not setup. For HTTP upload, it must be the URL of the server-side script that will handle the upload (i.e. parse multipart request), for instance http://mycompany.com/upload.php. This error could also mean that your FTP (or HTTP) server is not up.
  • I get "server error 404" error message ?
    Same as question above. Your "url" parameter is wrong.
  • Applet fails to load, I get ClassFormatError: Incompatible magic value ?
    Double check that installed JAR files are not corrupted. If you've transfered them on a web server through FTP then make sure that transfer has been done in BINARY mode.
  • Why do I need a server-side script too ?
    JFileUpload is just a client-side component that could upload files or folders to a server. You need a server-side script - for HTTP only - to store uploaded files. For FTP, you just need a FTP server.
  • For HTTP, can I use PHP, ASP, ColdFusion or PERL as server-side script ?
    Yes, JFileUpload uploads files through standard HTTP multipart request. Your server-side script could be written in PHP, JSP, ASP, ASP.NET, CGI/Perl, CGI/C++, Ruby, ColdFusion ...
  • Why do you recommend JSPUpload as server-side script ?
    We recommend JSPUpload with process.jsp script because it includes advanced features (very large upload with low memory, folders structure recomposition, resume and overwrite support, checksum ...) you might have to develop in your own script. However, JSPUpload needs Servlet/JSP support on server-side. Notice that you will find others upload script samples (such as PHP and ASP.NET) in add-ons section.
  • How to re-create folders structure on server-side when uploading a folder with multiples files and subfolders ?
    First, you have to select the recursive depth through "folderdepth" parameter of JFileUpload. Second, you need to enable "relativefilename" extra parameter on JFileUpload through paramX=relativefilename and valueX=true (with X in [1-16]). For instance:
       folderdepth="5"
       param1="relativefilename"
       value1="true"
    Finally - for HTTP only - you need a server-side script that will handle "relativefilename" parameter to create folders and subfolders before storing uploaded files.
    (process.jsp server-side script included in JSPUpload provides this feature).
FTP related
  • How to select an initial directory on FTP server before uploading files through FTP ?
    Use "account" extra parameter through paramX=account and valueX=dirname (with X in [1-16]). For instance:
       param1="account"
       value1="mydirectory/mysubdirectory"
  • How to create an initial directory on FTP server before uploading files ?
    Set "account" parameter above and set "accountcreation" extra parameter to "true". For instance:
       param2="accountcreation"
       value2="true"
  • My FTP connection is not reliable and some upload fails, what can I do ?
    Enable "retry" parameter to ask JFileUpload to make several attempts - when current upload fails - before reporting and error. For instance, to enable three attempts:
       retry="3"
    You can also setup "retrydelay" parameter to add a a few seconds delay between each attempts:
       retrydelay="5"
After upload
  • How to redirect to an URL after upload completed ?
    Use "forward" parameter such as forward=http://company.com/another.html
    If you need to redirect to a given frame of window then use "forwardtarget".
    If you need to append uploaded filenames to redirect URL then set "forwardparameters" to true.
  • Is it possible pass a HTTP POST request after upload completed ?
    Yes, see "post" and "postparameters". It allows JFileUpload to send a HTTP POST request with uploaded filenames (and path). It could be useful if you need to send an email, store a status in database, ... after upload. For instance, post=http://company.com/postscript.php
  • What happen to the response of the HTTP POST ?
    Reponse of "post" url is discarded by JFileUpload.
  • Could both "post" and "forward" parameters work together ?
    Yes, "forward" will be processed after "post". It means that HTTP POST request will be sent prior to HTTP GET matching to URL redirection. To be more precise :
    1 - JFileUpload: Send HTTP POST  ----> Server : Process POST request.
    2 - JFileUpload: Discard response  <---- Server : Send response.
    3 - JFileUpload: Send HTTP GET    ----> Server : Process GET request.
    4 - Browser: Display HTML response <---- Server : Send response.
  • Can I pass additional parameter to "forward" parameter ?
    Yes, try forward="http://company.com/another.html?custom=something"
  • How "forwardparameters" work if I upload many files ?
    Depending on browser, URL size is limited (from 256 to 4000 characters) so the generated URL might be too long (http://company.com/another.html?filename1=...)
    if you upload more than 100 files. The solution is to use "post" and "postparameters" to get all filenames (because there is no limitation in POST size) and use "forward" parameter only to redirect.
Internationalization
  • How to modify JFileUpload resources (messages, menu, errors ...) ?
    Most JFileUpload resources could be modified. A resource could be an info message, an error message, a menu item or a color. First, copy and modify i18n.properties in the same directory as JFileUpload applet. Second, setup "resources" parameter such as:
        resources = "i18n"
    Pay attention to setup it to i18n and not i18n.properties. Finally, edit and modify i18n.properties as you need. This file is an ASCII file and # means comment.
    If you need extra characters such as german (Ä, Ö, ü, ...) or chinese, japanese, korean ... then convert them into unicode format through JRE native2ascii tool.
  • How to internationalize JFileUpload resources (messages, errors , ...) ?
    JFileUpload is ready for internationalization. First, enable "resources" parameter as explained above. i18n.properties will be the default resources file. Second, if you want JFileUpload to support multiple languages then add i18n_xy.properties translated files (with xy the ISO 639 language code such as : en, es, de, zh ...). For instance, to add german support :
        1 - Copy i18n.properties into i18n_de.properties.
        2 - Translate all resources in german in i18n_de.properties.
        3 - Optionally, use JRE/bin/native2ascii.exe tool to convert extra characters.
    JFileUpload will automatically load i18n_de.properties if end-user settings are in german (and if localeresources parameter is setup to true). If not then it will load i18n.properties.
  • How display file browser window on "File" item instead of "Select file(s)" ?
    Comment menu.file.open key in your custom i18n.properties such as:
        menu.file.open=Select file(s)
        #menu.file.open=Select file(s)
  • How to remove the top menu bar and add a "Select file(s)" button ?
    To enable a "Select file(s)" button Screenshot 3 on the left of "Cancel" button, uncomment progress.button.select key in your custom i18n.properties such as:
        #progress.button.select=Select file(s)
        progress.button.select=Select file(s)
    Then to hide the menu bar, set "hidebar" parameter to true:
    hidebar = "true"
    ...
    <PARAM name="hidebar" value="true">
  • Can JFileUpload display "time elapsed" when uploading file ?
    Yes, enable both progress.info and progress.info.label keys in i18n.properties. Time remaining and transfer speed is available too. It could also display an overall progress bar Screenshot 3 (in addition to file upload progress bar).
  • How to add a background image to the upload info/drag&drop panel ?
    Uncomment "taskoutput.image.background" property in your i18n.properties and setup your image filename Screenshot 2.
  • Is it possible to have an image previewer in file chooser ?
    Yes, to enable this feature uncomment the following keys in your i18n.properties:
        filechooser.preview.image=enabled
        filechooser.preview.image.title=Image preview
        filechooser.preview.image.enabled=Enabled
  • How to modify JFileUpload fonts ?
    There are "font.face" and "font.size" keys/values in i18n.properties. It allows to load true type fonts and apply them over all JFileUpload resources (label, button, menu ...). This feature could be useful for accessibility.
  • How to have a Microsoft Windows-like JFileUpload front-end ?
    Enable lookandfeel=com.sun.java.swing.plaf.windows.WindowsLookAndFeel key in i18n.properties Screenshot 2. You can also setup lookandfeel=auto to fit to the underlying operating system look and feel.
  • Applet is not loading (grey box) when hosted under IIS , what should I do ?
    Basically, IIS settings don't allow to serve files with unknown extensions. IIS returns 404 error when JFileUpload tries to load i18n.properties. You have to update IIS settings to map ".properties" to "text/plain" mime-type. See instructions for IIS 4.x/5.x or 6.x.
  • I get "Can't find bundle for base name i18n" error, what should I do ?
    See question above, even if you have a Unix/Linux or MacOSX server. It will work when you could access i18n.properties directly from your browser through http://yourserver.com/something/i18n.properties.
User's session
  • How to pass a cookie from JFileUpload to server-side ?
    Use both "cookiename" and "cookievalue" extra parameters through paramX,valueX (with X in [1-16]). For instance:
        param5="cookiename"
        value5="mycookie"
        param6="cookievalue"
        value6="myvalue12345"
  • How to maintain user's HTTP session with server-side ?
    Most HTTP sessions are maintained through a cookie. See question above to learn how to pass a cookie (for JSP, cookiename should be JSESSIONID). You could also pass session as URL rewriting, then modify "url" parameter to pass it (for JSP url=...upload.jsp;jsessionid=xyz12345). You could also use URL rewriting for "forward" and "post" parameters.
  • How to pass custom error from upload script to JFileUpload front-end ?
    Enable "errorheader" extra parameter such as:
        param7="errorheader"
        value7="custommessage"
    Then, pass "custommessage"="whatyouwanttobedisplayed" header in HTTP 405 response sent by your upload script. JFileUpload will try to read the header to display the error message in front-end.
Security
  • Does JFileUpload support HTTPS ?
    Yes, it does. url parameter must start with "https://...". Just pay attention to have trusted X509 certificate on JRE client.
  • Does JFileUpload support FTPS and SFTP ?
    Yes, it does. FTPS is supported natively. url parameter must start with "ftps://...". Just pay attention to have trusted X509 certificate on JRE client. SFTP support requires SFTP add-on, url parameter must start with "sftp://...".
  • I get "No trusted certificate ..." error with HTTPS and FTPS ?
    It means that you're not using a trusted X509 certificate for SSL. The signer of the certificate is not in the JRE CA list (cacerts file) so you cannot open any SSL connection with Java. You have 3 solutions:
         1 - Deploy the certificate in JRE of all JFileUpload users.
              (Not easy in production).
         2 - Use WeakSSL plugin in JFileUpload add-ons section.
              (It allows to bypass trusted CA checking. Useful for testing purpose).
         3 - Purchase a trusted certificate for SSL from company such as VeriSign or Thawte.
              (Recommended in production).
  • I get "Access denied" when uploading with "chunksize" under Windows Vista ?
    Internet Explorer 7 under Windows Vista comes with new security features. A standard windows user account doesn't have permissions to write in some directories such as c:\, c:\Program Files ... "chunksize" parameter allows to split file in chunks before uploading. Basically, each chunks is written temporary on disk in the same folder as the selected file to upload. If you select file in a folder where you don't have write permissions then chunks cannot be created and you get "Access denied" errors. You will have the same problem with "ziponfly" parameter and plugins such as Scaling Filter. The solution is to setup JFileUpload to generate any temporary files under user's home tmp folder through:
    ...
    <PARAM NAME="tmpfolder" VALUE="javatmpdir">
    ...
    Another solution, that applies to "chunksize" parameter only, is to setup JFileUpload to generate each chunks in memory through:
    ...
    <PARAM NAME="chunkmode" VALUE="onfly">
    ...
  • How to hide FTP username and password in HTML code ?
    JFileUpload supports base-64 encoded parameters. Enclose value in [] to pass base-64 encoded string. For instance to encode password parameter:
        param2="password"
        value2="qwerty1234"
    then use any base-64 encoder/decoder service to get :
        param2="password"
        value2="[cXdlcnR5MTIzNA==]"
    Note that base-64 encoding is not encryption. Since 2.3 encryption is available for username and password, we can encrypt your credentials upon request to our support team.
  • Is it possible to NOT store url and username/password in HTML ?
    Yes, if you don't want url and username/password parameters in HTML, even base-64 encoded, then you could append them in i18n.properties file such as:
     url=ftp://yourftpserver.com
     username=yourftplogin
     password=yourftppassword
  • Is it possible to pass FTP username/password through JavaScript ?
    Yes, try the following in your JavaScript :
        document.fileupload.setParameter("username","yourlogin")
        document.fileupload.setParameter("password","yourpassword")
    See others section to learn more about JavaScript API.
  • Could JFileUpload work with a proxy ?
    Yes, JFileUpload will attempt to auto-detect HTTP or SOCKS proxy. However, you could force proxy settings if needed.
  • Does JFileUpload support HTTP WWW-Authenticate ?
    Yes, JFileUpload supports basic WWW-Authenticate through username and password parameters.
  • Does JFileUpload support explicit SSL mode (AUTH TLS) for FTPS ?
    Yes, default FTPS setup is AUTH TLS with protection channel enabled (PROT P). JFileUpload also supports AUTH SSL and SSL Connect (implicit mode). You could switch between these modes through "ftpsmode" parameter. You could disable protection channel through "ftpsprot" parameter.
Large upload and compression
  • Can JFileUpload compress file automatically before upload ?
    Yes, JFileUpload could zip file before upload if you enable "ziponfly" parameter. Here is how JFileUpload works:
        1 - Create a temporary ZIP file (such as originalfilename.zip).
        2 - Upload the compressed file.
        3 - Delete the temporary ZIP file.
        Notice that file stored on server-side will be originalfilename.zip
    Using this parameter could lower bandwidth usage but it will affect client-side performance because of compression process. Don't enable "ziponfly" parameter if you plan to transfer compressed files such as GIF, JPEG, MP3, ... JFileUpload allows skipping such files with "zipignorelist" parameter.
    JFileUpload could also zip all files in one overall archive before upload. See the compression tutorial to learn how to setup this feature.
  • How to upload files > 2GB through HTTP ?
    First, you have to set "chunksize" parameter on JFileUpload. Chunksize must be under 2GB (for 256MB, chunksize=268435456). Here is how JFileUpload works:
        1 - Split file to upload in temporary chunks (such as originalfilename.chunkid).
        2 - Upload each chunk.
             (with additionnal chunkid, chunkamount, chunkbase HTTP parameters).
        3 - Delete each temporary chunk file.
    Second, you need a server-side script that handles chunkid, chunkamount, chunkbase HTTP parameters to re-compose file from uploaded chunks.
    (process.jsp server-side script included in JSPUpload provides this feature).
Resume and overwrite
  • Resume doesn't work with my Microsoft FTP server ?
    Try to set resumecommand extra parameter such as:
        param3="resumecommand"
        value3="append"
  • How JFileUpload could resume broken uploads ?
    Uncomplete upload could occur on system/network failure or simply because you've cancelled upload. JFileUpload can resume uncomplete uploads. Use "resume" parameter to enable this feature. JFileUpload sends an additional request to server to know if current upload should be resumed. If you're interested in knowing how it works then see details below:
    For FTP:
     1 - Applet sends LIST command with current filename to upload.
     2 - FTP server returns remote file info (size, date) if available.
     3 - If remote file size < local file size then Applet sends REST resumeindex command.
     4 - Applet sends STOR command to upload file (starting at resumeindex).
    For HTTP:
     Resuming is more complex and requires a server-side script that supports
     "Content-Range" header :
     1 - Applet sends HEAD request with "filename" header for current upload.
     2 - Server script must return "HTTP 404 not found" response if file does not
          exist or "HTTP 200 OK" response with file size in a "size" header if file exists.
     3 - If remote file size < local file size then Applet sends HTTP multipart POST
          request with "Content-Range" header including resumeindex.
     4 - Server script handles upload request and append data to remote file.
      (process.jsp server-side script included in JSPUpload provides this feature).
  • How JFileUpload could rename duplicated files before upload ?
    JFileUpload can check if file already exists on server before uploading it. Use overwrite parameter to enable this feature. JFileUpload sends an additional request to server to know if current upload should be overwritten or not. If you're interested in knowing how it works then see details below for HTTP :
     1 - Applet sends HEAD request with "filename" header for current upload.
     2 - Server script must return "HTTP 404 not found" response if file does not
          exist or "HTTP 200 OK" response with file size in a "size" header if file exists.
     3 - Applet applies overwrite policy (indexrename, ...) and loops to step 1 until
          making sure that the file to upload doesn't exist on server.
     4 - Applet sends HTTP multipart POST request to upload file with the new name.
     5 - Server script handles upload request and save file.
    (process.jsp server-side script included in JSPUpload provides this feature).
    Note: You could use the "template" parameter to rename files to upload. It would avoid the additional request.
  • Could resume and overwrite features work together ?
    Yes, if both are enabled then resume is prior to overwrite. Resume and overwrite will also work with folders and subfolders upload.
Others
  • How to have dynamic parameters in applet_http.js JavaScript file ?
    Do the same as you did for any dynamic file. For instance, for PHP rename the file as applet_http_js.php, add your PHP code and modify link in applet_http.html such as <script src="applet_http_js.php"></script>
  • How to pass extra parameters to JFileUpload from JavaScript ?
    JFileUpload supports JavaScript to Applet communication. Use document.fileupload.setParameter(name,value) to pass or update extra parameters. For instance in your HTML:
    [...]
    <SCRIPT LANGUAGE="JavaScript"><!--
    function modify(val)
    {
        document.fileupload.setParameter("anotherHTTPparam",val);
    }
    //--></SCRIPT>
    [...]
    <form name="myform" method="post" action="">
    <input name="custom" type="text">
    <input type="button" name="mybutton" value="test" onClick="modify(myform.custom.value)">
    [...]
  • How to update regular applet parameters from JavaScript ?
    There is a document.fileupload.setProperty(name,value) method allowing to update the following applet parameters: forward, forwardtarget, forwardparameters, post, postparameters, ziponfly, username, password, template and resume. For instance, to update forward parameter:
       document.fileupload.setProperty("forward","http://server.com/script.php");
  • Any other JavaScript method available ?
    Yes, JFileUpload provides two methods allowing to get info about uploads :
    document.fileupload.getState(filename) returns WAITING, INPROGRESS, COMPLETED, FAILED, CANCELLED string for a given filename.
    document.fileupload.getFilenames() returns a list of filenames to upload.
    You have a sample usage of the JavaScript API in samples/javascript_api/
  • How to get more traces for debug purposes ?
    JFileUpload uses Commons-Logging API. To enable DEBUG mode, just copy/paste commons-logging.properties and simplelog.properties in the same directory as JFileUpload applet. Notice that DEBUG mode will slow down applet execution so NEVER enable DEBUG mode in production because JFileUpload could use much CPU after a long time. Debug messages will be displayed in the Java Console.
  • Can I run JFileUpload from a CD-ROM or DVD ?
    Yes. If you use "chunksize" and/or "ziponfly" parameters then you should setup "tmpfolder" parameter too because JFileUpload will generate temporary files. tmpfolder="javatmpdir" will generate temporary files in user's home folder instead of selected files folder.
  • Can I scale images before upload ?
    JFileUpload provides a filter API to pre-process files to upload. You could find an image scaling filter that generates thumbnails (or magnify images) before upload in JFileUpload add-ons section.
  • Can I queue files instead of uploading immediatly after selection ?
    Yes, you need JBatchUpload plugin available in add-ons section.
  • Can I PGP encrypt files before upload ?
    You could find a PGP pre-processing filter that encrypts files before upload in JFileUpload add-ons section.
  • I'm lost, where are the samples for basic and advanced usages ?
    Check out the samples/ folder in this documention.
  • I need to click on applet before using it, what's wrong ?
    A recent update to Microsoft Internet Explorer 6 included a change that alters the way users interact with applets in the browser. Check out the samples/kb912945/ folder to fix this issue.
  • JFileUpload seems to ignore my settings, what's wrong ?
    It might be a problem of JavaScript. If you mess up the cross-browser JavaScript that displays applet then some parameters may be skipped. Use copy/paste of an existing parameter to add new parameter.
  • My browser crashes when loading JFileUpload ?
    We've have been reported that messed up JavaScript could return a VC++ runtime error and crash Internet Explorer on a few windows configuration. The solution is to setup carefully the JavaScript file (copy/paste existing line to add parameter).

Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
All other company and/or product names are the property of their respective owners.