- 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 |
- Install jClientUpload HTML samples on your web server.
- 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.
- Update HTML samples to setup parameters. Notice that url parameter setup is mandatory.
- 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 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 (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 .
- 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. 
- 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.
|
|