JavaZOOM Web Site
  Software
  
Installation
  
HTTP Upload
  
FTP Upload
  
API & Design
<< back

- Installation -

jClientUpload is a client-side JAVA™ component (Applet or WebStart) that allows to upload files and folders to a web or ftp server. This component could be integrated in any application. Server-side technology could be JSP/Servlet, PHP, CGI/PERL, ColdFusion or Microsoft ASP. Front-end provides an upload progress bar, a cancel button and drag&drop support. jClientUpload supports very large uploads over 2GB and could resume broken uploads. It is customizable (colors, size and multilanguage). See installation instructions below and parameters to setup for HTTP upload or FTP upload.

Any problem ? Read the [FAQ] first. Still a problem ? Post your question to our online JSP Forum.

Installation
  1. Install jClientUpload HTML samples on your web server.
  2. Add lib/ folder including all JAR files (chttpclient.jar, clogging.jar, httpimpl.jar, ftpimpl.jar and jclientupload.jar) in the same folder as HTML samples.
  3. Update HTML samples to setup parameters. Notice that url parameter setup is mandatory.
  4. For HTTP upload, try http://yourserver.com/applet_http.html
    For FTP upload, try http://yourserver.com/applet_ftp.html

Note that jClientUpload could run locally (without a web server).

FAQ
  • What do I need to run jClientUpload ?
    You need Java (JRE 1.4 or higher) installed on client-side.
  • How to setup jClientUpload Applet ?
    jClientUpload applet includes two sample files : One for HTTP upload (see applet_http.html) and one for FTP upload (see applet_ftp.html). Edit and modify parameters in the file 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">
    ...
    jClientUpload applet works under Internet Explorer, Safari, Firefox, Netscape, Opera, ... see software section.
  • I get "Connection refused" error message ?
    It means that "url" parameter of jClientUpload 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 ?
    jClientUpload 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, jClientUpload uploads files through standard HTTP multipart request. Your server-side script could be written in PHP, JSP, ASP, ASP.NET, CGI/Perl, CGI/C++, ColdFusion ...
  • Why do you recommend UploadBean as server-side script ?
    We recommend UploadBean and LargeUpload.jsp script because it includes advanced features (very large upload with low memory, folders structure recomposition, resume and overwrite support ...) you might have to develop in your own script. However, UploadBean needs Servlet/JSP support on server-side. Notice that you will find others upload script samples (such as PHP) 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 jClientUpload. Second, you need to enable "relativefilename" extra parameter on jClientUpload 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.
    (LargeUpload.jsp server-side script included in UploadBean provides this feature).


  • 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"

  • 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 jClientUpload 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.
  • What happen to the response of the HTTP POST ?
    Reponse of "post" url is discarded by jClientUpload.
  • 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 - jClientUpload : Send HTTP POST  ----> Server : Process POST request.
    2 - jClientUpload : Discard response  <---- Server : Send response.
    3 - jClientUpload : 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 to modify jClientUpload resources (messages, menu, errors ...) ?
    Most jClientUpload 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 jClientUpload 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 jClientUpload resources (messages, errors , ...) ?
    jClientUpload is ready for internationalization. First, enable "resources" parameter as explained above. i18n.properties will be the default resources file. Second, if you want jClientUpload 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.
    jClientUpload will automatically load i18n_de.properties if end-user settings are in german. 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 jClientUpload display "time elapsed" when uploading file ?
    Yes, enable both progress.info and progress.info.label keys in i18n.properties. 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.
  • How to modify jClientUpload 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 jClientUpload resources (label, button, menu ...). This feature could be useful for accessibility.
  • How to have a Microsoft Windows-like jClientUpload front-end ?
    Enable lookandfeel=com.sun.java.swing.plaf.windows.WindowsLookAndFeel key in i18n.properties. Screenshot 2
  • Applet is not loading (greg 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 jClientUpload 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.

  • How to pass a cookie from jClientUpload 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 jClientUpload 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. jClientUpload will try to read the header to display the error message in front-end.

  • Does jClientUpload support HTTPS ?
    Yes, it does. url parameter must start with "https://...". Just pay attention to have trusted X509 certificate on JRE client.
  • Does jClientUpload support FTPS ?
    Yes, it does. url parameter must start with "ftps://...". Just pay attention to have trusted X509 certificate on JRE client.
  • 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 jClientUpload users.
              (Not easy in production).
         2 - Use WeakSSL plugin in jClientUpload 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.
              (Recommended in production).
  • How to hide FTP username and password in HTML code ?
    jClientUpload 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.
  • Could jClientUpload work with a proxy ?
    Yes, jClientUpload will attempt to auto-detect HTTP or SOCKS proxy. However, you could force proxy settings if needed.
  • Does jClientUpload support HTTP WWW-Authenticate ?
    Yes, jClientUpload supports basic WWW-Authenticate through username and password parameters.
  • Does jClientUpload support explicit SSL mode (AUTH TLS) for FTPS ?
    Yes, default FTPS setup is AUTH TLS with protection channel enabled (PROT P). jClientUpload 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.


  • Can jClientUpload compress file automatically before upload ?
    Yes, jClientUpload could zip file before upload if you enable "ziponfly" parameter. Here is how jClientUpload 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, ...
  • How to upload files > 2GB through HTTP ?
    First, you have to set "chunksize" parameter on jClientUpload. Chunksize must be under 2GB (for 256MB, chunksize=268435456). Here is how jClientUpload 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.
    (LargeUpload.jsp server-side script included in UploadBean provides this feature).

  • How jClientUpload could resume broken uploads ?
    Uncomplete upload could occur on system/network failure or simply because you've cancelled upload. jClientUpload can resume uncomplete uploads. Use "resume" parameter to enable this feature. jClientUpload 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.
      (LargeUpload.jsp server-side script included in UploadBean provides this feature).
  • How jClientUpload could rename duplicated files before upload ?
    jClientUpload can check if file already exists on server before uploading it. Use overwrite parameter to enable this feature. jClientUpload 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.
    (LargeUpload.jsp server-side script included in UploadBean 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.

  • How to pass parameters to jClientUpload from JavaScript ?
    jClientUpload supports JavaScript to Applet communication. Use document.clientupload.setParameter(name,value) to pass or update parameters. For instance :
    [...]
    <SCRIPT LANGUAGE="JavaScript"><!--
    function modify(val)
    {
        document.clientupload.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)">
    [...]
  • Any other JavaScript method available ?
    Yes, jClientUpload provides two methods allowing to get info about uploads :
    document.clientupload.getState(filename) returns WAITING, INPROGRESS, COMPLETED, FAILED, CANCELLED string for a given filename.
    document.clientupload.getFilenames() returns a list of filenames to upload.
  • How to get more traces for debug purposes ?
    jClientUpload uses Commons-Logging API. To enable DEBUG mode, just copy/paste commons-logging.properties and simplelog.properties in the same directory as jClientUpload applet. Notice that DEBUG mode will slow down applet execution so NEVER enable DEBUG mode in production because jClientUpload could use much CPU after a long time. Debug messages will be displayed in the Java Console.
  • Can I run jClientUpload from a CD-ROM or DVD ?
    Yes. If you use "chunksize" and/or "ziponfly" parameters then you should setup "tmpfolder" parameter too because jClientUpload 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 ?
    jClientUpload 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 jClientUpload add-ons section.
  • Can I PGP encrypt files before upload ?
    You could find a PGP pre-processing filter that encrypts files before upload in jClientUpload add-ons section.
  • I'm lost, where are the samples for basic and advanced usages ?
    Check out the samples/ folder in this documention.
  • jClientUpload 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. For instance, you will notice some lines ending with "\" char, if you add new parameter then don't forget the ending "\" (use copy/paste). We've have been reported that messed up JavaScript could return a VC++ runtime error on a few windows configuration.


[News] [Applets] [Servlets] [Services] [Projects] [Links] [About]

Copyright © JavaZOOM 1999-2005

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.