JUpload Classic

JUpload is a which enables any common browser to upload local files to a webserver using the standard HTTP-protocol supported by a simple though powerful and dynamic User-Interface with a lot of options for the webdesigner to customize.

Main Screen of JUpload

JUpload's strong points:

Security

Secure-HTTP (through SSL), authentication-support

Intranet

Complete Proxy server support

Userfriendly

Very easy to use; Image-Previewing, Drag-And-Drop, Progress-Information etc

Structured

Uploads files, folders and subfolders in a self-arrangable Upload-Structure

Customizable

Activate and configure all the components you like and deactivate those you do not like

Customize the user-interface: Change labels, colors, make your own skin or download one of many choosable themes

Use the power of javascript to re-design parts of the GUI, do a complete make-over or write powerful addons

Write your own plugin or use one of those that are already there

Progress

Displays detailed progress-information

File types

Supports more than 90 mime types, can upload all files

Thumbnails

Automatically creates and uploads thumbnail

PHP,ASP,...

Supports any server side scripting languages

Speed

Very fast

Ease of use

The user interface is intuitive, easy to understand and though powerful

Licensing

Free for private and cheap for commercial customers

Developers

API documentation & source-code available; Extendable through easily developed Plugins

Powerful

Extended Javascript- and Plugin- Support

Server

Server-independent

Safety

Resume uploads using the HTTP-PUT-Method

No limit

There are no artificial limits in JUpload

Mobility

It's platform independent; runs on Windows, Linux and Mac

For technical support, please go to the official Jupload product support page at jupload.biz

Chapter 1. Installation

The fast guide to get JUpload up and running

1. System Requirements

Client

Java Plug-In, Version 1.4 or greater - Microsoft Java is deprecated and thus not supported.
A compatible Browser (e.g. Microsoft Internet Explorer, Mozilla Firefox, Opera)
Internet Connection with open outgoing HTTP ports in firewall

Server

A webserver that is able to deliver binary data, so the Applet can be downloaded by the users. (eg. Apache at http://httpd.apache.org/ or alternatively you can install XAMPP which includes Apache, PHP and many other useful extensions, ready to run. You can find it at http://www.apachefriends.org/en/xampp.html)
Support for PHP, ASP, Perl or any other script-language that supports handling of HTTP-POST- or HTTP-PUT-Requests (already included in XAMPP)

2. Plug and Play - The fast way

Uncompress the downloaded archive jupload.zip (name may vary) into a directory beneath the DOCUMENT_ROOT of your webserver.

Make sure that your current server-settings are according to JUpload's current configuration.

Now simply use your browser to navigate to the correct location of the index.html on your webserver and JUpload should load up and be ready to use.

When using Apache, you can see all uploaded files by simply navigating to the "JUpload/uploaded/"-directory. The delivered .htaccess-file should enable auto-indexing of all files and sub-directories within this directory.

Note

Your webserver might have prohibited use of automatic indexing in general or only for this folder or for its subfolders. In that case please consider your webserver's manual.

Warning

Everyone accessing this page, can now upload files. To prohibit that, you can enable User-Authentication.

Tip

To do further customization, refer to the Advanced-Section.

3. Client-Side: Displaying the Applet

The files for JUpload and its embedding HTML-Page

/index.html
An HTML-Page embedding JUpload:
The core for embedding JUpload is t Applet-tag which looks something like this by default:
```
<applet
		title="JUpload"
		name="JUpload"
		code="com.smartwerkz.jupload.classic.JUpload"
		codebase="."
		archive="
				dist/jupload.jar,
				dist/commons-codec-1.3.jar,
				dist/commons-httpclient-3.0-rc4.jar,
				dist/commons-logging.jar"
		width="640"
		height="480"
		mayscript="mayscript"
		alt="JUpload by www.jupload.biz">

	<param name="Config" value="cfg/jupload.default.properties">

	Your browser does not support applets or you disabled applets in your browser-options.
	To use this Applet, please install the newest version of Sun's Java Runtime Environment (JRE).
	You can get it from <a href="http://www.java.com/">java.com</a>

</applet>
```
The Applet-settings in Detail:
applet
The Applet tag tells the browser that a Java-Applet should be embedded here. The attributes have all required information for Java to find and run the specified Applet from the given archive.
name
The name of the Applet, that Javascript is using to access JUpload with.
code
The code tag specifies the location and name of the main class within the delivered archives.
codebase
This is the location where the jars, specified in archive are to be found. Also all relative URLs used within JUpload are relative to the Applet's codebase.
archive
The archives are relative to the codebase or absolute and contain the Applet and further classes that are required by JUpload.
All archives that are doing certain GUI-interactions, using network-connections or are accessing the local file-system need to be signed. See information on signing.
The archives delivered with the download package are already signed as needed.
width, height
These two attributes specify the dimension (size) of the Applet. You can specify them in pixels or -by adding a "%"- in percent. Eg. width=800 or height=50%.
mayscript
This toggles wether or not Javascript is allowed to call methods of the JUpload-Applet (see the chapter on Javascript-Support).
param
The <param> tags can be used to configure the Applet. All supported parameters are described in the configuration-chapter. Names and values must be quoted. Also note that the names and values are case-sensitive.
Since JUpload 0.90 this is not the preferred way to configure the applet anymore. It is rather recommended to simply write the configuration to a config file which will then be the only specified <param>-tag:
```
<param name="Config" value="location/to/the/config.properties">
```
This will make JUpload connect to the given URL (absolute or relative to the Applet's codebase) and download the config file for further use.
Example 1.1. Config-File Example
The config file replaces the <param>-tags with simple key=value - pairs, seperated by lines. If this parameter is specified, all other <param>-tags are ignored.
The old-fashioned configuration:
<param name="Files.Convert.Format" value="jpg"> <param name="Files.Convert.InterpolationAlgo" value="bilinear">
Is now replaced by a config-file with the following content:
Files.Convert.Format=jpg Files.Convert.InterpolationAlgo=true
Note
The config file entries are not quoted.
Don't forget to add the config-file's location through the Config-Parameter as shown above.
If you do not want to use a config file, remove the Config-<param>-tag and add all the file's settings in the old-fashioned style as <param>-tags into the Applet-tag.
^[1]
/index-js-test.html
Embedds JUpload and demonstrates the usage of the Javascript-API.
/cfg/jupload.default.properties
The Config-File for JUpload is a simple text file and can be opened with any text-editor (such as Notepad).
It consists of simple key=value pairs and replaces the definition of JUpload's parameters through Applet's <param>-tags (see above for more information).
```
Upload.URL.Action=http://some/very/very/very/very/long/long/long/long/long/long/long/long/long/long/long/long/long/long/url
```
You can add comments, by preceeding the line with a "#":
```
# This is a comment and will not be evaluated
```
You can distribute a parameter-definition over several lines by placing a "\" at the very end of a line:
```
Upload.URL.Action=http://some/very/very/very/very/long/long/long/long/long\
/long/long/long/long/long/long/long/long/long/url
```
For more flexibility or user-specific config-files, you can simply replace the URL with the location of a script-file (PHP, ASP, Perl etc) which then replaces the parameters based on information read from a database or similar.
/dist/jupload.jar
The JUpload-Applet itself
/dist/*.jar
Further libraries, needed by JUpload
/dist/skinlf/*.*
The skinlf with a few skins. See the Look&Feel - Section for further details.
/uploaded/files/ and /uploaded/thumbnails/
The folders that the delivered scripts are configured to upload files and thumbnails correspondingly to by default.
/uploaded/.htaccess
An .htaccess-file for apache to automatically index all uploaded files when accessing this directory

4. Server-Side: Save uploaded files

The script files, responsible for reception of files

/scripts/php/jupload-post.php
A php-script for file-reception using HTTP-POST
/scripts/php/jupload-put.php
A php-script for file-reception using HTTP-PUT
/scripts/php/inc/jupload.inc.php
File that is included by both PHP-Scripts mentioned above. Provides functions and functionality which is needed by both script files.
/scripts/php/inc/jupload.cfg.php
Configuration for file-reception
/scripts/php/listener/JUBaseListener.class.php
Abstract Listener for Upload-Events. Implement this for custom file-processing and set the config correspondingly.
/scripts/php/listener/JUDefaultListener.class.php
Default listener for Uploads - simple Listener-Implementation to provide basic information about the received files

Please see the chapter on File-Reception for further information.

^[1]If your configuration includes characters that are not part of the Latin1-character-set (certain special characters or characters of any non-roman language), please consider the following, as stated in Java's documentation:

“The stream is assumed to be using the ISO 8859-1 character encoding; that is each byte is one Latin1 character. Characters not in Latin1, and certain special characters, can be represented in keys and elements using escape sequences similar to those used for character and string literals.”

Unicode-escaping is described in chapter 3.3 of the Java Language Specification.

Chapter 2. How does JUpload work?

A brief overview over all of JUpload's features and how they work

1. Run JUpload

Use the webbrowser to go to the address of the JUpload-embedding HTML-Page. JUpload will automatically load.

While Java is loading the archive, a progressbar is shown.

When the Applet is fully loaded, the Java Plug-In will check its certificate. It will show a dialog with information about the certificate which was used to sign the Applets archive. Please check the certificate for correctness and accept with Yes or with Always.

Figure 2.1. Java Security Dialog on Windows

Java's Security Dialog on Windows

Figure 2.2. Java Security Dialog on MacOS X

Java's Security Dialog on Apple MacOS X

2. Overview

After JUpload has loaded and the certificate has been accepted, the main window will appear. After adding some files, it should look similar to this:

Main Screen of JUpload

2.1. Look And Feel (L&F): The overall appereance

The LookAndFeel (L&F) defines how the Applet should look like. It defaults to the Windows-LookAndFeel under Windows and the "Metal"-LookAndFeel under any other OS.

JUpload has the amazing feature to change its L&F in 3 simple steps:

Choose one L&F from many places:
- Any of Java's defaults: WindowsLookAndFeel (only available on Windows) (short: windows), BasicLookAndFeel (short: basic) or MetalLookAndFeel (short: metal)
- Use JUpload's integrated built-in support for the SkinLookAndFeel by l2fproductions (short: skinlf):
  1. Choose a skin, eg from: http://javootoo.l2fprod.com/plaf/skinlf/index.php or use JGoodies.
  2. Add the skin's jar-file(s) to the Applet-tag's archives in the embedding HTML-Page.
  3. Specify the fully-qualified classname through Gui.LF.SkinPackUrl.
- A major collection of further L&Fs can be found at http://javootoo.l2fprod.com/.
- Create your own LookAndFeel or (way easier) Skin or have a Java-Developer do it for you
Add the L&F's jar-file(s) to the embedding HTML-Page (Not needed if using any of Java's default L&Fs)
Add the location of the jar-file(s) (absolute or relative to the Applet's codebase or (if codebase left empty) the embedding html-file) to the Applet's archive-tag, seperated by comma.
Set Gui.LF.Classname to specify the fully qualified classname of the L&F.
You can use the shortcuts metal, windows, basic and skinlf for the corresponding L&Fs mentioned above.

Done. You can now see JUpload in a completely new look.

2.2. The FileChooser-Dialog

The FileChooser-Dialog opens, when clicking on the Add Files - Button in the toolbar.

Within the FileChooser you can see the preview of selected image-files on the right side which can be deactivated.

You can change the FileFilters which are used to hide and prohibit adding of files which should not be uploaded at all. The FileFilters appear at the very bottom ("Files of Type"). In JUpload, there are predefined FileFilters and -if that is not enough- you can create and add your own FileFilters using Gui.FileChooser.Filter.Multi.

Select one or multiple files with a single left click and the help of the CTRL- and SHIFT-key. If you want to select all files, press CTRL + 'A'. This works in the filechooser, as well as in the UploadViews.

You can deactivate this Dialog by removing the corresponding button from the toolbar and add the JUpload's own FileChooser-Plugin and/or FolderChooser-Plugin to the page instead.

The file chooser can also display previews of images

2.3. Drag and Drop (DnD) + Copy and Paste

You can use Drag&Drop (short: DnD) to drag files from the explorer or any other external file-manager directly into JUpload.

Select the files or directories to be uploaded and do not release the mouse button. Now, move your mouse over to the running JUpload Applet. Move the mouse into the folder of your choice within the TreeView and release the mouse button. The files will now be added to the corresponding folder.

Also you can drag and drop folders and files within JUpload to any other folder to re-arrange the Upload-Structure.

Alternatively you can paste files, folders or images that you copied in another application directly into JUpload.

Dragging files out from JUpload is not supported.

2.4. The Toolbar

The toolbar at the very top top contains several control-buttons and can be customized through the Gui.Toolbar.Buttons-Parameter.

The Upload Files - Button becomes the Stop Upload - Button during the upload-process.

The Toolbar

2.5. UploadViews

The UploadViews display all files and folders which will be uploaded in a hierarchical structure when the user presses the Upload Files - Button.

By default there is the TreeView which displays the folders on the left side and the three other views on the right: The ListView with optional thumbnail-display, the DetailedView displaying additional information about the file or image and the ThumbnailView (or ImageView) which displays thumbnails of all images.

If you rest the mouse-cursor over a filename for a few seconds, you will see a tooltip containing the path of that file.

To remove files, select them using the mouse (single click for single files; hold SHIFT or CTRL to select multiple files) and either press "DEL" or click the Remove-button. No files will be erased from the hard disk.

You can change the order of or remove views through the parameter Gui.Views.Display. Further changes to the views can be done, using other Gui.*-Parameters.

The ListView

The DetailView

The ThumbView (ImageView)

2.6. Uploading and Upload-Progress

After adding all files, you can start the upload process by pressing the Upload-button. Press it again to cancel the upload.

While uploading, you will see a status display on the bottom of the Applet which can be expanded or collapsed by simply clicking on its title.

When using HTTP-PUT, you can resume the upload. Simply add the same files again and click the Upload Files - Button and only the rest of the file will be uploaded.

The upper progress bar will show the progress of the current file, the lower one shows the total progress.

An upload is currently being processed

2.7. Server Response

After the server received all files, it can send HTML-formatted text which will then be displayed in the ResponsePanel ("Server Response") at the bottom.

It is activated and collapsed by default. To disable it, set the Gui.ServerResponse.Enable-Parameter to false.

You can expand it by clicking on its title but it will be empty until it receives the first response from the server.

When information is received, it automatically expands. This behavior can be changed through the Gui.ServerResponse.AutoShow - Parameter.

Its height can be changed through the Gui.ServerResponse.Height - Parameter.

The Response Panel shows the server's reply

2.8. Capturing screenshots

JUpload is able to capture screenshots of the complete desktop or only JUpload respectively. If multiple screens are installed in the machine (dual-head), the user is asked for the screen to be captured.

The delay time before the capture can also be changed.

You can add or remove the corresponding buttons in the contextmenus through the Gui.ContextMenu.*-Parameters.

2.9. Proxy Support

JUpload fully supports proxies, using Basic-, Digest- or NTLM-Authentication. You can set up proxy-support under Tools -> Settings -> Proxy Login.

The windows-domain only needs to be entered when using NTLM-Authentication, and will be ignored in any other case.

Corporate users might need to set up an Intranet Proxy

3. Special Features

3.1. The Upload-Structure: Files and Folders

JUpload allows the user to upload files in a hierarchical structure which can easily be re-arranged, using DragAndDrop.

The structure allows files to be in folders and subfolders: All files and folders are within the root-folder. The root-folder is the "/" - Folder to be seen at the top of the UploadTree. This folder -as well as any sub-folder- can hold further sub-folders and files. The files will be shown in the ListView, DetailedView or the ThumbnailView on the right while all folders are shown in the TreeView on the left.

You can deactivate this feature and prohibit the use of folders in three simple steps:

Deactivate Folders using the Files.Filter.Folders - Parameter
Deactivate the UploadTree by removing tree from the Gui.Views.Display because it would become unnecessary
Deactivate the AddFolder - Button from the Gui.ContextMenu.* - Parameters

Now the user cannot create subfolders anymore and will not see the UploadTree-View. To re-enable the feature, simply reverse the three steps.

The server can use Meta-Information sent by JUpload to determine in which folder a file is.

3.2. Thumbnails: Create and upload image-thumbnails automatically

JUpload can automatically create and upload thumbnails of image-files.

The thumbnails will be uploaded right after all files have been uploaded.

Use the Upload.Thumbnails.* - Parameters to customize this behavior.

Example 2.1. Thumbnail-Configuration Example

# Activate Thumbnail support
Upload.Thumbnails.Enable=true

# The location of the thumbnail-receiving script
Upload.Thumbnails.TargetURL=http://www.mydomain.com/thumbnails/jupload-post.php

# The maximum size of the thumbnails (resizes in proportion if either width or height exceeds their limit)
Upload.Thumbnails.Size=80x80

Note

The receiving script can determine wether the received file is a thumbnail or a file. See Meta-Information for details.

3.3. Custom User-Input

JUpload also can submit custom user input (eg from textareas, checkboxes etc) from the embedding page.

The feature is disabled by default and can be activated by setting the Upload.Formname. All elements of the specified form will then be sent via GET with each Upload-Request.

In PHP for example, all values (text, checkbox-/radio- selections, options, lists, buttons) of this form are stored in the superglobal: $_GET

Note

You do not need to add this form for hidden-values. You can add constant GET-values (not changable by the user) through the Upload.Http.Query-Parameter.

3.4. Validity-Check: Do not make unnecessary uploads

JUpload always checks first if supplied authentication, proxy-settings and the supplied user-input is accepted by the server with a HTTP-HEAD-Request. With this first request no files are uploaded.

Depending on the statuscode of the response-header of the server, JUpload can then determine wether or not to actually upload the files.

For that you need to set the Upload.Http.ExpectedHeaders-Parameter (or the status-code will be ignored): If set (and only if set) JUpload will not attempt the upload in case that the server responded to the HEAD-Request with anything but one of the expected headers.

The status-header must be the first header and it must be valid (or else it might be replaced by the webserver).

If JUpload idenitifies a header not to be valid, it cancels the download and shows the status-info as error-message.

See the configuration-example using PHP for details.

3.5. Multi-threading: Make everything work at once

JUpload is multi-threaded which simply means that it can perform several operations at once.

Save multi-threading allows the user to still edit the upload-tree while JUpload is uploading without messing up the upload or the structure of the uploaded files. This is because the files that are being uploaded will not be affected by any changes within JUpload.

This feature can be deactivated through the Gui.DeactivateOnUpload-Parameter

Note

It is completely save to let the user still add, remove or rename files or interact in any other way while uploading.

Chapter 3. Advanced Settings

The main features are not enough? Have a look on how to customize JUpload with over one hundred different settings and options

1. Localization

Do you have an international user-base? JUpload speaks a lot of languages and is able to learn any other.

With the help of properties-files, you can easily specify your own translation.

All language-files are located within JUpload's jar-file in: com/smartwerkz/jupload/classic/language/

The filenames of a language-file is either jupload_xx_YY.properties or jupload_xx.properties.

Language- (xx) und Country-names (YY) are standardized according to the i18n-standard, see

Language Codes: http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt
Country Codes: http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html http://www.iso.org/iso/en/prods-services/iso3166ma/index.html

The files are simple text-files; each line has a keyword and a value. For example, the label of the "Add FIles"-Button within the GUI, is assigned like this:

Gui.Control.Add.Label=Add Files

While initialising, the Applet gathers information about the locale settings on client side and loads the corresponding language file automatically. You do not need to specifiy the language explicitly. It first tries to find a file that matches the user's language and country (jupload_xx_YY.properties). If that cannot be found, it will look for a file that matches only the language (jupload_xx.properties).

If no corresponding language file can be found, the default will be used: jupload.properties.

You can force all users to use one certain Locale, by setting the Locale-Parameter.

To create a custom translation, follow these steps:

Copy one of the already existing language-files out of /dist/jupload: Jar-files (or archives) are simple zip-files and can be opened with any tool that supports zip-compression (eg winzip, winrar or winace for windows users).
Rename it, according to the i18n-standard, mentioned above (eg jupload_de.properties for German, jupload_zh_ZH.properties for simplified Chinese, jupload_jp.properties for Japanese etc).
Generally speaking, you should always have a language-file that matches the jupload_xx.properties-pattern so that people who speak the same language but live in a different country, from what you used as basis for the translation, would still see everything translated into their own language, even if some words, characters or grammar might be different (eg Austrians see everything translated in German and Taiwanese see everything translated in Chinese).
Open the file with any text-editor and translate the messages on the right side of the equation sign ("=") of all lines. Do not change the values on the left side!
If you want to write a message over several lines, add a backslash ("\") to the end of the line and the next line will just be appended to this line.
Copy the file back into the language-folder within the jar-file.
Resign the jar-file

All users with the corresponding language-settings or with the Locale-Parameter set to the language and country of the language-file, will now see all messages translated.

Note

Make sure to remove JUpload from the cache after changing the settings.

2. Debugging

If there are problems in the transmission or the functionality of JUpload, you should enable the debug mode to locate the source of the problem. Enabling the debug mode is done by using the Debug-Parameter.

Debug messages will be written into the Java Console. This console can be opened automatically, if set in the Java Plug-In in the Windows Control Panel. Alternatively you can open it from the tool-menu of your browser or from the Java-Icon in the taskbar (rightclick -> Open Console).

When encountering problems, you might often run into so-called Exceptions of different kinds which represent abnormal Program behavior or errors. One Exception often might cause other Exceptions in other places of the program where the actual initial Exception is always at the top. So if you encounter a problem and want to know what actually went wrong in the first place, look into the first line of the Exception's output.

For example, in the following exception, we found 2 Exceptions where the first line contains the actual cause of the problem: JUpload's class could not be found (see common problems):

load: class com.smartwerkz.jupload.classic.JUpload not found.
java.lang.ClassNotFoundException: com.smartwerkz.jupload.classic.JUpload
   at sun.applet.AppletClassLoader.findClass(Unknown Source)
   at java.lang.ClassLoader.loadClass(Unknown Source)
   at sun.applet.AppletClassLoader.loadClass(Unknown Source)
   at java.lang.ClassLoader.loadClass(Unknown Source)
   at sun.applet.AppletClassLoader.loadCode(Unknown Source)
   at sun.applet.AppletPanel.createApplet(Unknown Source)
   at sun.plugin.AppletViewer.createApplet(Unknown Source)
   at sun.applet.AppletPanel.runLoader(Unknown Source)
   at sun.applet.AppletPanel.run(Unknown Source)
   at java.lang.Thread.run(Unknown Source)
Caused by: java.io.IOException: open HTTP connection failed.
   at sun.applet.AppletClassLoader.getBytes(Unknown Source)
   at sun.applet.AppletClassLoader.access$100(Unknown Source)
   at sun.applet.AppletClassLoader$1.run(Unknown Source)
   at java.security.AccessController.doPrivileged(Native Method)

You can also add a Javascript-Handler for debug-information.

Java Console is helpful for debugging purposes

The Java Console Log Window can usually be shown through an option in your browser's Tool-menu. It can also be accesses by Java's system tray icon.

3. Verifying Data Integrity

To ensure that files are uploaded correctly, you can use hash codes to verify their contents. JUpload can calculate MD5 hashcodes of files and send it as Meta-Information.

To check the MD5 hashes on the server, you can use the corresponding Meta-Information sent by JUpload.

Warning

For performance reasons this feature is disabled by default and is NOT recommended to be used for files without outstanding importance!

Example 3.1. Veryifying Data Integrity using POST and PHP

$filename = $_FILES[0]['tmpname'];
$real_md5 = $_POST['files1_md5hash'];
$calc_md5 = md5_file($filename);
if ($calc_md5 != $real_md5) {
// Content got corrupted while or after upload
}
else {
// Hashes-values match: File is good
}

4. Resigning the jar File

The Certificate shown in the Security Dialog when the Applet is first loaded on the client's machine can be replaced by your own certificate.

You can use your own Code Signing Certificate and let a Certificate Authority (like Thawte, Verisign etc.) verify it.

The following steps are required to re-sign the jupload.jar file:

Download and Install the Java 2 SDK from http://java.sun.com
Either: Import your existing certificate into the Java Keystore:
```
keytool -import -alias JUpload -file mycert.jks
```
You will have to enter a new password for the keystore. The Keystore will secure the imported certificate with this password, so don't forget it. You will need it in the next step again.
Or alternatively: To import an already existing certificate, you can create your own self-signed certificate. This won't be trusted by any root Certificate Authority and hence will be shown as "Untrusted" to the user.
```
keytool -genkey -alias JUpload
```
You will have to answer some questions (your name, company name etc.) and the certificate key will be generated.
Use the jar signer utility to re-sign the JUpload-archive and all other archives that it uses (such as the HttpClient or the logging-archive).
```
jarsigner jupload.jar JUpload
jarsigner httpclient.jar JUpload
etc...
```

Warning

In case that you signed the Applet and it still does not work. make sure that you a) really changed the signature of all needed jar-files (other jars, such as the skinlf-jar might also need to be (re-)signed. If it still does not work, make sure to remove all re-signed applets from the cache.

The following files are required by JUpload and need to be signed

Commons HTTPClient: http://jakarta.apache.org/commons/httpclient/
Commons Logging: http://jakarta.apache.org/commons/logging/
Commons Codec: http://jakarta.apache.org/commons/codec/

Note

Signed versions of all these files are already included into the download-archive, which is available at our download-page.

Certain other archives, such as the SkinLF also need to be signed in order to work.

5. User-Authentication

Several ways of integrating User-Authentication

Basic- or NTLM (IWA) -Authentication

When using Apache, you can simply protect your upload-scripts and upload-directory by adding an .htaccess-file to restrict access (refer to your webserver's manual for more details).

JUpload supports Basic, Digest or NTLM (also known as IWA) -Authentication. The algorithm is set through the Upload.Http.Auth.Scheme-Parameter.

Activate User-Authentication by setting the Upload.Auth.UserAuthRequired-Parameter to true. The user is now asked to enter user-authentication before being able to upload any files. These settings can be changed by the user in Tools -> Settings -> User Login and can be locally stored (remembered) for future use.

You can also let JUpload automatically submit the login, by setting the Upload.Auth.AutoLogin-Parameter.

Warning

Never send any Login-Information to the user that the user himself is not supposed to know.

Example 3.2. Basic-Authentication Example

Upload.Auth.UserAuthRequired=true
Upload.Http.Auth.Scheme=basic
Upload.Auth.AutoLogin=user:pass

Use of cookies, get-values or post-values

If a user is already logged in on the website and you do not want to require him/her to login again, you can simply use session-cookies, query-values (get-values) or post-values to submit the current login-status. Therefore replace JUpload's Configuration-file by a script (for example using PHP). The script can then dynamically insert values of cookies or other.

In this case the Upload.Auth.UserAuthRequired-Parameter must then be set to false because it requires the user to actually enter user-information for webserver's default authentication (see above).

Example 3.3. Scripted Configuration

Note

Always make sure to add all information that you want the config-script to have, to the Config - URL. This is necessary eg. for sessions, since JUpload downloads the config-file in a seperate request which does not contain any further information.

Replace corresponding parameters in your configuration-file to dynamically submit the login-status (and/or any other kind of information) of the user. You have 3 different options to choose from:

Query (Get), Post, and Cookies

Thumbnail-uploads use their own set of parameters; make sure to also set those if you are making use of automatic thumbnail-creation.

Upload.Http.Method=post

# More parameters here...


# File parameters:

Upload.Http.Query=userid=<?php echo $user->getId(); ?>

Upload.Http.AdditionalPostFields=userid=<?php echo $user->getId(); ?>

Upload.Http.Cookies=<?php echo "phpsessid=$sid,myothercookie=$interestingInfo"; ?>


# Thumbnail parameters:

Upload.Thumbnails.Http.Query=userid=<?php echo $user->getId(); ?>

Upload.Thumbnails.Http.AdditionalPostFields=userid=<?php echo $user->getId(); ?>

Upload.Thumbnails.Http.Cookies=<?php echo "phpsessid=$sid,myothercookie=$interestingInfo"; ?>

Important

For some reason in PHP the linebreak directly following a <??> - tag is removed, thus you need to add an empty line after every script-insertion.

Warning

You cannot submit POST-Values with the PUT-Method.

6. Secure servers (SSL)

JUpload can connect to secure servers, using SSL. Secure server URLs must be prefixed with https://, indicating secure HTTP - protocol.

By default, JUpload accepts all SSL certificates automatically which might be considered a security risk in certain environments. This behavior can be changed by exchanging the TrustManager which determines wether or not certificates can be trusted. The TrustManager can be set through the Upload.SSLTrustManagerClass.

Note

Providing a custom TrustManager requires knowledge in Java. Smartwerkz offers additional services for customers who cannot meet this requirement - feel free to check back with us.

To implement a custom TrustManager, you need to follow these three steps:

If you do not already have a TrustManager, you need to write one. A TrustManager has to implement the javax.net.ssl.X509TrustManager - Interface. The checkServerTrusted - Method is the method which decides wether or not a server can be trusted. With a call of the checkValidity - Method of each Certificate, you can ensure that the certificate is valid.
Either add the class with all package-folders to an already existing jar-file or create a new jar-file which contains the class.
If you need to access the local file-system, network-streams or certain other functions that are considered a potential security risk for web-applications, you also need to sign the jar-file.
Add the jar-file to the list of archives.
Set the Upload.SSLTrustManagerClass to the fully qualified classname of your TrustManager, including the package name.

Whenever JUpload is connecting to a secure server, it will use this TrustManager to determine wether or not the server's certificates are trustworthy. You can of course use GUI-interaction or similar to ask the user if the server is a trusted one or not.

7. Customizing with Parameters

Parameters and their types

You can find a list of all parameters in the appendix.

Parameters in JUpload's Config-File are simple key=value-pairs: The name indicates what the parameter is used for and the value overrides JUpload's default.

Every Parameter has a previously defined type. A type simply tells JUpload how the value should be understood.

There are 2 Special types: List and Map.

List

Values in a list are komma-seperated and have a certain type of their own. For example List (Files) stands for a List of Files.

Gui.ContextMenu.Files=ButtonA, ButtonB, ButtonC

Map

Values in a map are komma-seperated key-value-pairs in the format of key=value. For example Map(String, String) stands for a map with simple text-keys and text-values.

Keys of these map have non-unique keys which means that a map like myMap=x=1,x=2 contains 2 entries: x=1 and x=2.

Upload.Http.AdditionalHeaders=X-JUpload-UserID=henry, X-JUpload-Pass=secret

Upload.Http.Query=choice[]=1,choice[]=2

In the following table all other types are explained:

Type	Description	Example
String	Simple text. Can be restricted to only have certain values allowed. For example: String (put, post) In this case, the value can only be `put` or `post`.	Files.Convert.Format=jpg
StringPair	A pair of 2 strings in the format: name=value	Upload.Auth.AutoLogin=username=password
Integer	A simple number in a range between -2 billion and +2 billion	Files.MaxImageSize=123456
IntegerRange	A list of numbers, where each number must be in a range between -2 billion and +2 billion. You can add multiple ranges seperated by commas. A single range can be either a single number or 2 numbers, combined with a dash "-" where the number to be expected would be in between.	Upload.Http.ExpectedHeaders=200-204,210,220-234
Long	A simple number in a range between negative and positive 9223372036854775800	Upload.MaxTotalFileSize=8000000
Double	A floating-point-number, such as 10.28	MinJavaVersion=5.0
Boolean	Yes-or-no-switch: yes, 1, on and true can be used to enable this option and all other values would result into this option to be disabled	Debug=no
File	The location of a file in the local file system.	Gui.FileChooser.DefaultDir=c:\me\important
URL	The location of a file located on the local file system or on an HTTP-server. Can be relative to the location of JUpload's embedding HTML-Page.	Upload.URL.Action=http://mycompany.com/receive.php Upload.URL.Action=scripts/receive.php
Color	CSS-Formated-Color: A 6-digit hexadecimal value, representing the level of RGB-intensity (Red Green Blue). Can be preceeded by a "#".	Gui.LF.Background=#EE99FF
Locale	A locale specifying language and cultural location in the pattern of: language[,country[,variant]] Anything but the language is optional. The specification for language-, country- and variant-codes are according to the international standard i18n (see Localization).	Locale=en,US Locale=en
Font	A font in the pattern of: name,style,size The name can be the name of any font, supported by Java (any common one). The style is a value between 0 and 3: 0 = Plain, 1 = Bold, 2 = Italic, 3 = Bold Italic The size is the size of the font in points.	Gui.LF.Font=Arial,0,12
Dimension	A size in the pattern of `Width`x`Height`	Gui.Views.Tree.MinSize=300x300
Image	The URL of an Image-File (see URL-Type).	SomeImage=media/background.gif
RegexFileFilter	A filefilter that has a name and a regex-pattern, seperated by 2 vertical lines "\|\|". If this filefilter is selected (eg in the FileChooser), its name will be displayed and only files that match the given regex-pattern will be displayed and added.	Gui.FileChooser.Filter.Multi=Executables\|\|(.?\.exe)\|(.?\.com)
ExtFileFilter	A FileFilter, consisting of a name, followed by 2 vertical lines ("\|\|") and a list of Extensions. All Files that have one of the given extensions are ignored.	MyFilter=Images\|\|jpg,jpeg,.png,gif

See here for a ist of all parameters

Chapter 4. File-Reception - Scripts on your webserver

JUpload needs either webdav or a script using PHP, ASP or another language that is supported by your webbrowser to actually receive and save the sent files.

JUpload does not only send files but also sends so-called meta-information with every file, such as the name, its path, etc (see below for more info).

You can use two different methods for uploading the files: POST or PUT. The method being used can be changed, using the Upload.Http.Method - Parameter.

Script-files supporting both methods are already delivered with the download-package. You can easily configure them to do whatever your server needs to do.

1. Meta-Information from JUpload

JUpload sends so-called meta-information with every file (see Upload.Http.Meta.* - Parameters) and thumbnail (see Upload.Thumbnails.Http.* - Parameters) as shown in the table below.

When using the POST-Method, the file itself, as well as the sent meta-information are each one MIME-Multipart and each have a name-tag.

The name-tag of the file-parts consists of the value, specified in the Upload.Http.Meta.FileTag - Parameter, followed by a number (such as "files1").

The name-tag of the thumbnail-parts consists of the value, specified in the Upload.Thumbnails.Http.TagName - Parameter, followed by the number of the file it represents (such as "thumbnails1").

Each piece of meta-information about a file or thumbnail will be prefixed with the file's or thumbnail's name-tag and an underscore.

When using the PUT-Method, the meta-information of the file being sent is sent in the header. All meta-information-headers are prefixed with "X-JUpload" which means that this header is an "Extension for JUpload".

HTTP-headers do not support any encoding other than ASCII, which is why these information are URL-encoded, using JUpload's default encoding.

Here is a list of all available meta-information:

Suffix of part when using POST	Name of header when using PUT	Description
_relativePath	X-JUpload-RelativeFilename	The filename and relative path of the file or (in case of a thumbnail) of the original within the Upload-Tree (eg. "/my documents/important/Laura.jpg").
_thumbnail	X-JUpload-Thumbnail	1 or 0, indicating wether it is a thumbnail of a file or an actual file.
_image	X-JUpload-Image	1 or 0, indicating wether it is a valid image-file. Not sent for thumbnails.
_virtual	X-JUpload-Virtual	1 or 0, indicating wether the file is virtual or actually exists on the client's harddisk. Not sent for thumbnails.
_absolutePath	X-JUpload-AbsolutePath	The absolut position of a file on the client's harddisk. Not sent for thumbnails.
_lastModified	X-JUpload-LastModified	The date and time of the last modification of this file in seconds since the 01/01/1970.
_md5hash	X-JUpload-MD5	The MD5-Hash of the file. See here for more information.

2. Using the POST-Method

The POST-Method, similarly to emails, uses MIME-Multiparts which means that every POST-request can consist of one or more parts. One POST-request is one connection attempt. Everything that has been sent with one completed POST-request, will be saved. If a POST-Request fails, all files or parts of files that have been sent within the request are lost.

Every file as well as every bit of meta-information about the file represents one part. All sent files and their information (such as size and temporary name) are to be found in PHP's $_FILE array. All further information sent by JUpload can be found in the $_POST array. So we basically iterate over the $_FILE array, and find information about each file corresponding to its name in the $_POST array, as shown below.

There are 2 parameters for limiting size and amount of files being sent:

To set the maximum size of one post request, see the Upload.Http.MaxRequestSize - Parameter.

To set the maximum amount of bytes to be sent during one post request, see the Upload.Http.MaxRequestFileCount - Parameter.

The corresponding file jupload-post.php is delivered in the download-package.

2.1. Configuring PHP

When using POST with PHP, you must ensure that the server allows file-uploads. For that set the following values either directly in the php.ini or through the ini_set()-function.

file_uploads

Must be enabled, set it to 1

upload_tmp_dir

Must be set to a local folder on the server, to which the webserver has write-access. By default, the system's temporary directory is used, e.g. /tmp/

upload_max_filesize

Set this to the maximum filesize in bytes you wish to be permitted (should be greater than JUpload's Upload.Http.MaxRequestSize).

You can use the shorthands K,M and G for Kilobyte, Megabyte and Gigabyte: 1M is 1 Megabyte.

Warning

This defaults to 2 Megabyte in PHP! So you won't be able to upload files bigger than 2M with a standard php installation. Many hosting companies use a value of 8MB.

post_max_size

This should be set to a value larger than Upload.Http.MaxRequestSize

memory_limit

This setting also affects the file upload capabilities of PHP. Please ensure that this is set to a value high enough. The PHP Interpreter must be compiled with --enable-memory-limit to activate this limit. Set the value to -1 to disable memory limit.

max_execution_time

Set this to a value high enough for uploads to complete.

You can also disable the execution time limit in a single session by calling the function set_time_limit(0) at the beginning of a script.

max_input_time

Set this to a value high enough for uploads to complete.

When using Apache, some of these values can also be set in .htaccess files within your web folder. Check the PHP manual for details.

Additional information for PHP can be found at php.net.

To view your current PHP- and server- settings, use phpinfo() in your php script. This will print out your overall configuration of PHP and the webserver being used.

3. Using the PUT-Method

The PUT-Method supports resume of aborted file-transfers.

When using the PUT-Method, each file will be uploaded in its own PUT-request. It sends a HEAD-request before each file-upload to determine wether the file already exists. The server sends the so called Content-Length - Header in the response of each HEAD-request to tell JUpload how big the file already is. JUpload will then auto-resume the upload and only send the rest of the file.

In some cases you might want to save received files at a different location, in which case you need to send a customized Content-Length - Header for the HEAD-request in your own script. Some webservers (such as Apache) might automatically remove these header-information because they are considered faulty. In that case you need to use the X-Content-Length - Header which has the same syntax with a different name, to make sure that it won't be removed by the webserver. In case that the file to be uploaded does not exist, JUpload expects statuscode 404.

To activate the PUT-Method, you need to set Upload.URL.Action to an existing directory on your webserver.

To have this directory accept PUT-Requests, you can choose from one of the following options:

Using Webdav

The recommended and most simple way is: Activate webdav for the given Action-URL. You can read more about enabling and configuring webdav in your webserver's webdav-configuration or at the official homepage.

Using a custom script

Alternatively you let Upload.URL.Action point to the directory that you want your files to be saved to and redirect all PUT-Requests to a script-file of your choice: In our case, the JUpload-Receiver-Script.

When using Apache, in order to redirect all PUT-Requests, you need to add a "Script"-directive for the corresponding directory into your httpd.conf:

Example 4.1. Example for a Script-Directive for a certain Directory

<Directory "C:/htdocs/jupload/uploaded/">
    AllowOverride All
    Options None
    Order allow,deny
    Allow from all
    Script PUT C:/htdocs/jupload/scripts/php/jupload-put.php
</Directory>

The files will then be sent to this directory and saved by the script, that handles PUT-Requests for this directory.

The corresponding file jupload-put.php is delivered in the download-package.

When you are trying to save files to a location that is different from the directory, specified as the target in Upload.URL.Action, you also need to redirect all HEAD-requests to a custom script which sends the X-Content-Length - Header to JUpload to determine how much (if anything) of a file has already been received. There is no script-file for that delivered in the download-package because it is not recommended to save the files anywhere but in the pre-destined directory.

Both, Webdav and the delivered jupload-put.php already have builtin support for resuming files.

4. Configuring and customizing the upload-scripts

In case you are not using webdav, you can easily configure the scripts from the default scripts without changing them.

For that you can set all variables (must be global) which are defined in the corresponding config-file.

4.1. Set the variables

An overview over all customizable parameters for the receiving PHP-Scripts

Simply override these variables before including the either of JUpload's receive-scripts. Don't forget, they have to be global.

JUBaseListener $_ju_listener

Default: $_ju_listener = new JUDefaultListener();

If you want to work differently with received files(for example store the information in a database etc), create a new class that inherits from JUBaseListener or JUDefaultListener and override the corresponding methods. See the JUBaseListener-class for details.

Example 4.2. An example JUpload-Listener for a gallery (PHP)

/**
 * By simply overriding the JUDefaultListener, we can use all of its methods instead of re-define all of them when 
 * implementing JUBaseListener. 
 * In our case we only want to override the onReceived - method in order to add received images and thumbnails 
 * to the gallery which then eg inserts these information into a database.
 */
class JUGalleryListener extends JUDefaultListener {
	/**
	 * @var MyGallery $gallery
	 */
	var $gallery;

	function  JUGalleryListener($gallery) {
		$this->gallery = $gallery;
	}
	
	function onReceived($filepath, $relativePath, $isThumb) {
		$path = stripslashes($gallery->getPath() . $relativePath);
		
		if ($isThumb) {
			$this->gallery->addThumb($path);
		}
		else {
			$htmlpath = htmlspecialchars(basename($relativePath), ENT_QUOTES, "UTF-8");
			if ($this->gallery->addImage($path)) {
				echo "<div halign=left>Picture saved: $htmlpath</div>";
			}
			else {
				echo "<div halign=left>Could not save picture: $htmlpath</div>";
			}
		}
	}
}

string $_ju_uploadRoot

Default: $_ju_uploadRoot = dirname(__FILE__) . "/../../../uploaded/";

This is the location of the directory where files and thumbnails should be saved to.

By default points to the relative location of the /uploaded/ - folder that is delivered with the download-package.

Set it to an empty string if you do not want to save files and thumbnails within the same folder.

string $_ju_fileDir

Default: $_ju_fileDir = "files";

This is the location of the directory where files should be saved to within the $_ju_uploadRoot; basically at: "$_ju_uploadRoot$_ju_fileDir"

Set it to an empty string or null if you want to save all files directly under $_ju_uploadRoot.

string $_ju_thumbDir

Default: $_ju_thumbDir = "thumbnails";

This is the location of the directory where thumbnails should be saved to within the $_ju_uploadRoot; basically at: "$_ju_uploadRoot$_ju_thumbDir"

Set it to an empty string or null if you want to save all thumbnails directly under $_ju_uploadRoot.

int $_ju_maxSize

Default: -not set-

If set, determines the maximum size of files for PUT-Requests. The corresponding value for POST-Requests must be set through the php-configuration.

4.2. Embedd the receiver in your own script

Set the variables as described above and then simply include the corresponding receiver supporting your method: jupload-post.php or jupload-put.php:

Example 4.3. Customized JUpload-Receiver Example

<?
// Get the gallery according to the sid that was submitted via GET (Query)
$gallery = getGallery($_GET["sid"]);

// Let the script die and send a header that would tell JUpload when doing the HEAD-Request that this is an invalid Move
// This way it will not even try to upload invalid files.
if (!$gallery) {
  // The header-function tells JUpload, we have statuscode 403 (see validity-check for details).
  // It consists of the supported HTTP-Version, the status-code and an info-message which will be displayed in case
  // that this header was not expected by JUpload:
  header("HTTP/1.1 403 Invalid gallery");
  die("The gallery that you want to edit does not exist.");
}
?>

<HTML>
<BODY>

<?
// For safety reasons, mark the changed variables global, in case that we are not in the global scope here
global $_ju_uploadRoot, $_ju_listener;

// Change the upload-root
$_ju_uploadRoot = "/gallerysystem/images/$username/" . $gallery->getName();

// Set our own listener which adds corresponding database-entries of received files and thumbnails
$_ju_listener = new JUGalleryListener($gallery);

// include the receiver
require_once(DIR_JUPLOAD . "jupload-post.php");
?>
</BODY>
</HTML>

Chapter 5. Javascript and how to use it to enhance the JUpload-Experience

Use Javascript to replace JUpload's default User-Interface completely or to simply interact with it

1. What is the Javascript API?

The Javascript API is a common interface between Java and JavaScript, was developed by Netscape and is called LiveConnect.

With the help of LiveConnect, Java can access Javascript functions (and the page's DOM) and Javascript can access and control the Applet. JUpload uses both these features.

You can find the Javascript API-Reference in the appendix.

It allows you to control JUpload through JS as well as listen for all kinds of events.

In order to do so, you must set the "mayscript"-parameter for the Applet. With scripting activated, the Applet can now be accessed as document.JUpload in your page, where JUpload is the name of the Applet.

If javascript is activated and supported by the browserr, the init()-method will be called by JUpload upon start. Here you can initialize the interaction between JS and JUpload (eg. Registering listeners).

Javascript cannot access all of JUpload's functionality since some of them require special access-rights (eg accessing the local file-system or network-streams). These functions can only be accessed if explicitely defined by JUpload are now refered to as privileged functions.

All important supplied functions and listeners for controlling JUpload or obtaining information from it, are to be found in the next section and in the appendix.

Note

This API is using JUpload's own types (such as UploadClient, UploadEntity, UploadFile, UploadNode, UploadTree) which are explained in the JS-API-Reference. For further and more detailed explanations, pease consider JUpload's JavaDoc.

Important

Filenames in javascript do not support backslashes ("\") which is the default path-seperator under windows. You need to replace them with forward slashes ("/") before trying to add them to JUpload.

Example 5.1. JS-API HelloWorld-Example

<script language="javascript">
//
// This function is called by JUpload right after startup.
//
function init() {
    alert("JUpload started and says: Hello World!");
}
</script>

2. General and privileged Functions

Here is a list of general functions and those which require special access rights (eg when accessing the local file-system or a network stream).

js().takeScreenshot()
Takes a screenshot.
js().clickAdd()
Opens the filechooser
js().isUploading()
Indicates wether an upload is currently in progress.
js().toggleUpload()
Starts or stops the upload.
js().changeLanguage(language)
Changes language into the given value. Language should be the iso-conform 2-character shortcut of the corresponding language. If the language is not recognized, the default one (english) will be used.
js().saveNodes(uploadNodes)
Saves the given UploadNodes (array of UploadNode) and its children correspondingly to a path chosen by the user.
js().saveNodes(uploadNodes, directoryPath)
Saves the given UploadNodes (array of UploadNode) and its children correspondingly to the given directory-path.
uploadTree()
Returns the UploadTree which holds all files and folders that are to be uploaded
Eg. can be used like this: document.JUpload.uploadTree().getFileCount()
gui()
Returns the JUploadGui which represents the default Graphical User Interface
Eg. can be used like this: document.JUpload.gui().statusMessage('some message')

3. Listeners

You can find a list of all listeners in the JS-API-Reference.

JUpload can easily inform Javascript about everything that it currently does. Simply register a listener for a set of events that you want to display on your webpage or use in any other form.

After registering a listener, whenever anything related to the corresponding listener happens, a js-function will be called in which you can describe what should happen. If an event of a registered Listener occurs whose function is not defined, a notice will be displayed in the console if debug-mode is enabled. If you do not care about certain events of a listener, just leave the function empty (you should define it though).

To register a listener, call the corresponding Register-function in your self-defined init() function which will be called right after JUpload has started. All Register-functions expect one parameter: A name which will then preceed all called functions of the listener (see example below).

When implementing a listener function, its name in js must consist of:

- the name of the Listener as defined in the Register-function

- an underscore ("_")

- the name of the listener-function, as described below

Caution

Called listener-functions will interrupt (block) the Applet until they return or finish.

Here is an overview over all supported events that you can listen to, using javascript:

Listener-name	Register-function	Range of events
ResponseListener	js().listenResponse(name)	JUpload finished uploading and received a response from the server
UploadProgressListener	js().listenUploadProgress(name)	Everything related to the upload-progress, from initializing to finishing
UploadTreeListener	js().listenUploadTree(name)	All changes of the UploadTree, such as adding, removing, renaming or saving of nodes.
ViewSelectionListener	js().listenViewSelection(name)	The selection in the current UploadView has changed
DebugListener	js().listenDebug(name)	For log messages or unexpected program-malfunctions.
ResponseLinksListener	js().listenResponseLinks(name)	The user clicks on links in the ResponsePanel

The following list of all listener-functions and their parameters are described as in Java: Every object or entity also has a type which determines what operations can be used on it.

responseReceived(String response) // The function "responseReceived" has one parameter "response" which is of type "String"

The type of course needs to be left out when declaring the javascript function (see example below).

4. Javascript - Examples

Example 5.2. JUpload-JS-Listener example

You find a similar example with some further additions, in the index-js-text.html - file.

//
// This function is called by JUpload right after startup.
// Here we need to register all Listeners we want to use.
//
function init() {
    // The supplied parameter "UploadProgress" and "Reponse" is the prefix of all functions of the corresponding listener
    document.JUpload.js().listenUploadProgress("UploadProgress");
    document.JUpload.js().listenResponse("Response");
}

//
// Next we define all functions that are part of the listeners, registered in the init()-method.
// Every function-name consists of:
// - the name of the Listener ("UploadProgress" or "Response") as defined in the
// - an underscore ("_") 
// - the name of the listener-function
//
// ###################################################################################
// Listener: UploadProgress

function UploadProgress_initializing(client) {
    alert("Initializing upload...");
}

function UploadProgress_initialized(client) {
    alert("Upload initialized - Starting...");
}

function UploadProgress_failed(client, currentEntity, exception) {
    if (currentEntity != null) {
        var entity = "current file: " + currentEntity.getFullName();
    }
    else {
        var entity = "during connection-attempt";
    }

    alert("Upload failed (" + entity + "): " + exception);
}

function UploadProgress_dequeued(client, file) {
}

function UploadProgress_uploadingFileStart(client, file) {
    alert("Starting to upload: " + file.getFullName());
}

//
// In this function we can display the upload-progress.
// The UploadClient offers a lot more progress-information, as described
//
function UploadProgress_uploadingFile(client, file, count) {
    document.title = 'JUpload - Uploading "' + file.getFullName() + '" (' + client.getProgress().getTotalPercent() * 100 + '%)' ;
}

function UploadProgress_uploadedFile(client, file) {
    alert("File successfully uploaded: " + file);
}

function UploadProgress_uploadingThumbStart(client, file) {
    // not of interest right now - leave it empty
}

function UploadProgress_uploadingThumb(client, file, count) {
    // not of interest right now - leave it empty
}

function UploadProgress_uploadedThumb(client, file) {
    // not of interest right now - leave it empty
}

function UploadProgress_closed(client, succeeded) {
    if (succeeded) {
        alert("Upload finished successfully");
    }
    else {
        alert("User cancelled upload.");
    }
    document.title = "JUpload";
}



// ###################################################################################
// Listener: Response

//
// Function of the ResponseListener handling the server-response.
//
function Response_responseReceived(text) {
    alert("Server response: " + text);
    
    // document.getElementById("someDiv").innerHTML = text;  // Set the content of a div with the id = "someDiv"
}

Chapter 6. Updating from JUpload 0.89 and before

There have been severe changes and improvements between version 0.89 and 0.90. Mentioned below are the most important changes and information on how to resolve them.

1. Parameters

Important

Config-File

You can now use a config-file instead of defining all parameters in Applet's <param>-tags.

See Client-Side: Displaying the Applet for more information

Types

All parameters now have more determined types.

Refer to the chapter on parameters and types for exact details.

User interface and appereance

LookAndFeel, colors and general appereance

Parameters renamed - See here for more information

Texts and labels

Removed - Refer to the chapter on localization instead.

thumbWidth and thumbHeight

Replaced with the Gui.Views.Icon.MaxWidth - and Gui.Views.Icon.MaxHeight - Parameters

mainSplitpaneLocation and leftSplitpaneLocation

Removed - You can change the size of the UploadTreeView instead

captureScreenDelay

Removed - User can change it within GUI instead: See Gui.ContextMenu.* - Parameters

defaultAddDirectory

Renamed to Gui.FileChooser.DefaultDir

showPicturePreview

Renamed to Gui.FileChooser.Preview.Enabled

filechooserPreviewChecked

Renamed to Gui.FileChooser.Preview.Show

filechooserPreviewQuality

Renamed to Gui.FileChooser.Preview.Smooth

imageFileFilter

Renamed to Gui.FileChooser.Filter.Image

multiFileFilter*

Renamed to Gui.FileChooser.Filter.Multi

hideShowAll

Renamed and logic reversed (see Gui.FileChooser.Filter.All)

showServerResponse

Renamed to Gui.ServerResponse.Enable

showTabViews

Renamed to Gui.Views.Display

showThumbnails

Renamed to Gui.Views.Thumbs.Enabled

showSystemIcons

Renamed to Gui.Views.Icon.SystemIcons

showFilePaths

Renamed to Gui.Views.ShowPaths

autoSelectLastFile

Renamed to Gui.Views.AutoSelectAddedFiles

showSuccessDialog

Renamed to Gui.Status.ShowSuccessDialog

showStatusPanel

Renamed to Gui.Status.ShowPanel

hideAddButton, hideUploadButton, hideStopButton and hideRemoveButton

Replaced - see information on the Toolbar

showRealtimeResponse

Removed - Response will always be shown in realtime

captureScreen

Removed - see Gui.ContextMenu.*

disableContextMenu

Removed - see Gui.ContextMenu.* - Parameters

showErrorsOnAdd

Removed - The user can see a quick note of invalid files at the statusbar at the bottom and can open a list of all invalid files through the Tool-Menu.

See Gui.ContextMenu.* - Parameters

Upload

actionUrl

Renamed to Upload.URL.Action

usePutMethod

Replaced with Upload.Http.Method

authEnabled

Renamed to Upload.Auth.UserAuthRequired

usePresetAuthentification

Replaced with Upload.Auth.AutoLogin

additionalHeaders*

The "additionalHeader + x" - parameters are now replaced with the Upload.Http.AdditionalHeaders - Parameter

browserCookie

Replaced with Upload.Http.Cookies

PUTQueryString

Changed to Upload.Http.Query

fileTag

Renamed to Upload.Http.Meta.FileTag

useAbsolutePaths

Renamed to Upload.Http.Meta.AbsolutePath

sendLastModificationDate

Renamed to Upload.Http.Meta.LastModified (works now)

calculateMD5Hash

Renamed to Upload.Http.Meta.MD5

useRecursivePaths

The relative path of a file will always be sent (see Meta information)

maxFreeSpaceOnServer

Renamed to Upload.MaxTotalFileSize

maxNumberFiles

Renamed to Upload.MaxTotalFileCount

maxTotalRequestSize

Renamed to Upload.Http.MaxRequestSize

maxFilesPerRequest

Renamed to Upload.Http.MaxRequestFileCount

autostartUpload

Renamed to Upload.Autostart

PUTFragmentSize

Removed - unnecessary

checkResponse

Removed - unnecessary

fixJakartaBug

Removed - Fixed itself

overwriteContentType

Removed - unnecessary

useProxy

Removed - unnecessary

Proxy-settings can be set by the user in the applet.

skipNewlineAfterHeader

Removed - unnecessary

useFTPMethod

FTP is not supported yet. Also the protocol of the Target-URL will be determined automatically by JUpload.

Other

locale*

Replaced with the Locale - Parameter

checkJavaVersion

Changed to MinJavaVersion

preselectedFiles

Renamed to Files.Preselected

noDuplicates

Renamed to Files.Filter.Duplicates

noRecursion

Renamed to Files.Filter.Folders

convertImagesToFormat

Renamed to Files.Convert.Format

resizeImageMaxWidth

Renamed to Files.Convert.MaxWidth

resizeImageMaxHeight

Renamed to Files.Convert.MaxHeight

resizeInterpolationAlgorithm

Renamed to Files.Convert.InterpolationAlgo

improvedRendering

Removed, simply set the interpolation algorithm to activate improved rendering when converting images.

resizeWithMetadata

Renamed to Files.Convert.IncludeMetadata

dimensionFilter

Changed - see Files.Filter.MaxImageDimension

replaceDocument, completeUrl, errorUrl

Renamed to Upload.Complete.URL and Upload.Complete.ErrorURL correspondingly.

Alternatively you can use javascript-listener instead to manipulate the document when an event occurs (see here for examples)

targetFrame

Renamed to Upload.Complete.Target

Alternatively you can use javascript-listener instead to manipulate the document when an event occurs (see here for examples)

2. Javascript

The Javascript-API has severely changed. The old version's javascript-support was not nearly dynamic enough to compete with the new version's level of interoperability. Therefore basically all old functions have been replaced and/or changed, so that Javascripts written for an old version are not compatible with this version anymore.

In exchange you can now access every single element within JUpload and change its contents to a very high extent (see the new API-definition for more information).

It is also possible to listen to any event that is happening within JUpload, using the all new listener-API.

An example can be found here.

3. JUploadForm

The JUploadForm was the name of the form whose elements -if existing- would always be sent to the server with each Upload-Request. The name of the form can now be set in the configuration.

See the custom user-information - Feature for more details.

4. File-reception on the webserver

Server-side scripts for older versions of JUpload will still work with the new version. However there have been minor changes and additions:

PUT-Headers

Before all headers were sent by default; they now have to be activated through configuration.

See Meta-Information

Last modification-time + Thumbnail indication + Image indication

A file's last modification-time as well as an indicator for thumbnails and for images will now also be sent to the server.

See Meta-Information

Virtual files and absolute path

The absolute path of files will now only be sent if it is a non-virtual file and activated through configuration.

See Meta-Information

5. Other

New Features

JUpload has several new major features.

See here for more information

Plugins

Most builtin default Plugins also have changed.

Please refer to the Plugin-Chapter for further information.

A lot of new stuff

There have been many additions to the classic JUpload which are not listed here explicitely.

However you can find all information related to a certain aspect of JUpload in the corresponding chapters of this manual.

Enjoy the new Experience!

Chapter 7. Solving common problems

1. Applet not loading or not uploading

1.1. Loading Java Applet failed...

JUpload does not show up and you perhaps see an X with a white background and an error-message at the bottom of your browser:

This error will most certainly be accompanied by the following message in the console:

load: class com.smartwerkz.jupload.classic.JUpload not found.
java.lang.ClassNotFoundException: com.smartwerkz.jupload.classic.JUpload
   at sun.applet.AppletClassLoader.findClass(Unknown Source)
   at java.lang.ClassLoader.loadClass(Unknown Source)
   at sun.applet.AppletClassLoader.loadClass(Unknown Source)
   at java.lang.ClassLoader.loadClass(Unknown Source)
   at sun.applet.AppletClassLoader.loadCode(Unknown Source)
   at sun.applet.AppletPanel.createApplet(Unknown Source)
   at sun.plugin.AppletViewer.createApplet(Unknown Source)
   at sun.applet.AppletPanel.runLoader(Unknown Source)
   at sun.applet.AppletPanel.run(Unknown Source)
   at java.lang.Thread.run(Unknown Source)
Caused by: java.io.IOException: open HTTP connection failed.
   at sun.applet.AppletClassLoader.getBytes(Unknown Source)
   at sun.applet.AppletClassLoader.access$100(Unknown Source)
   at sun.applet.AppletClassLoader$1.run(Unknown Source)
   at java.security.AccessController.doPrivileged(Native Method)

In this case the Applet's archive could not be found at the destined location or could not be accessed for some other reason. Make sure that the archives are all at the right location.

If that did not work, at one point it seemed to help to simply restart the browser once (only seems to be required when updating the archieves very often in a row - thus only for the developer when playing around a lot).

1.2. SecurityException: Access Denied

If you get security warnings or have exceptions in the Java Console like the following one, the Signature of the jar file might be broken, or you have declined the Certificate in the Security Dialog.

In this case please reload the page and accept the certificate. If it still says "Access Denied", one of the Jar-Files that JUpload uses, might need to be signed again or Javascript is trying to execute a method it is not allowed to execute (see Javascript-Support).

				java.security.AccessControlException: access denied (java.util.PropertyPermission javaplugin.proxy.config.list read)
				at java.security.AccessControlContext.checkPermission(Unknown Source)
				at java.security.AccessController.checkPermission(Unknown Source)
				at java.lang.SecurityManager.checkPermission(Unknown Source)
				at java.lang.SecurityManager.checkPropertyAccess(Unknown Source)
				at java.lang.System.getProperty(Unknown Source)

1.3. Invalid Settings: Could not parse parameter

Important

If JUpload cannot read a Parameter or Config-Settings correctly, it will not start and instead show an error-message in the console and an error will popup:

In the configuration you will have the following entry:

Files.MaxImageSize=123ef

Information to be found in the Java-Console (see Debugging):

Parsing parameters for class com.smartwerkz.jupload.classic.JUpload:
java.lang.RuntimeException: com.smartwerkz.jupload.classic.config.params.ParameterException: Could not parse parameter "Files.MaxImageSize" - Cannot convert "123ef" to type "Integer" (class java.lang.NumberFormatException: For input string: "123ef").

This would be the first 2 lines of the error-output. Be sure to always scroll up to find the real source of the problem in case of an error.

In this example-case, you can simply go to your configuration file (or applet-tag) and change the value for the parameter Files.MaxImageSize to a correct number.

2. Look&Feel (L&F) does not change or show up

In case that JUpload does not appear in your Look-and-Feel as expected, you will usually see an error in the console, such as:

java.lang.ClassNotFoundException: my.special.LookAndFeel

In this case the LookAndFeel's classname is either incorrect or the jar-file was not added to the Applet's archive-tag (refer to Step 2 and 3 of the instructions for custom L&Fs).

Alternatively you can use the other Gui.LF.* - Parameters to do some rudimentary changes to colors, borders and the font being used.

3. Cannot redirect

JUpload does not support automatic redirects. If the server sends a redirect-request, you might encounter this error-message:

Redirect requested but followRedirects is disabled

Be sure to always point to the right location and do not redirect, by sendig the Location - Header to JUpload.

From a developer's point of view, assuming that the action-URL is correct and has not been moved to another location, a redirect is only required if the client has an invalid status for the given URL (eg. the user is not logged in but wants to access a restricted area).

To avoid this problem, simply make sure that JUpload always submits all needed information that are needed to verify the correct status for the action-URL. Sessions might not work, if you do not use cookies, query- or post-values to verify the session. See the chapter on user-verification for details.

4. Applet changes are not displayed

In case that you made changes to the jar-file(s) but the outcome doesn't change, you might need to remove the applet from the system's cache in order to be reloaded.

To erase cached Java-Applets, follow these steps:

Open the Java System Settings from within your browser's Tool-menu or, under windows go to Start > Settings > Control Panel > Java Plug-In
In the General-Tab in the Temporary Internet File - Section at the bottom press View
At the top left select Show: Resources
Search for the URL of your JUpload-Applet and remove it from the list

It should now reload the applet when connecting to the given URL.

If the changes are still not visible, make sure that you applied them correctly.

To ensure that all users will have the applet updated automatically, you can also change the URL by for example changing the name of the jar-file, by eg. appending some version-number to the appletname.

If you add a random value to the URL, such as "url?rand=<? echo time(); ?> the whole applet will be completely downloaded every time, the user accesses the page which of course is not recommended.

Chapter 8. Builtin Plugins

You do not like the default FileChooser? You want to have more functionality with a minimum of effort? Use JUpload's Plugins

JUpload supports Plugins. Smartwerkz already offers the choice of 6 builtin plugins that can be integrated with JUpload within 2 minutes, they can be customized and support Javascript-interaction. You can find them at the download section of our homepage.

Java developers also can easily create their own Plugins. Ask our support-team for special wishes or requests.

1. FileChooser Plugin

File: plugins/jupload-filechooser.jar
Class: com.smartwerkz.jupload.plugins.builtin.filechooser.FileChooserPlugin

This plugin allows the user to easily add files without the need of JUpload's default FileChooser-Dialog.

It displays all files of a certain Folder. You can also enable it to show subfolders and/or show the parent directory.

The user can either use Drag and Drop (DnD) by simply selecting one or more files and click and drag them into a folder of his/her choice within JUpload or doubleclick single files to add them to the currently selected folder of the UploadTree.

It can also interact with the FolderChooser Plugin and the FileTypeChooser Plugin, allowing the user to choose the folder to be displayed and the current FileFilter for filtering (hiding) all files of a certain type.

1.1. Configuration

The following parameters are supported:

ListIconSize
Type
Dimension
Default Value
32x32
Description
The size of thumbnails in the list-view in pixels.
Register.FileTypeChooser
Type
Boolean
Default Value
false
Description
Wether or not this Plugin should interact with the FileTypeChooser. When interacting, only files that are allowed by the currently selected FileFilter of the FileTypeChooser will be shown.
Only select this option if the FileTypeChooser is present. Also you need to add the FileTypeChooser to the WaitForPlugins-List.
See Example below
Register.FolderChooser
Type
Boolean
Default Value
false
Description
Wether or not this Plugin should interact with the FolderChooser. When interacting, the FileChooser will always display the folder that is currently selected in the FolderChooser.
Only select this option if the FolderChooser is present. Also you need to add the FolderChooser to the WaitForPlugins-List.
See Example below
ShowFolders
Type
Boolean
Default Value
true
Description
Wether to also display subfolders or only files.
ShowParentDir
Type
Boolean
Default Value
true
Description
Wether or not the parent-directory ("..") should be shown when displaying files of a folder.
ThumbnailIconSize
Type
Dimension
Default Value
100x100
Description
The size of thumbnails to be displayed in the ThumbnailView in pixels.
Views
Type
List (String list,details,thumbs)
Default Value
list,details,thumbs
Description
The sequence of views to be displayed; similar to JUpload's UploadViews.
Config
See JUpload's configuration for further information.
ID
See JUpload's configuration for further information.
WaitForPlugins
See JUpload's configuration for further information.

1.2. Embedding the FileChooserPlugin

Example 8.1. Embedd FileChooserPlugin Example

Simply define the applet-tag in the embedding html-page as follows.

You might have to change the correct location of the jar-files, specified in the archive-tag and the location of the configuration-file, specified in the <param>-tag.

<applet
		title="FileChooser Plugin"
		name="FileChooserPlugin"
		code="com.smartwerkz.jupload.plugins.builtin.filechooser.FileChooserPlugin"
		codebase="."
		archive="jupload.jar,
				 plugins/jupload-filechooserplugin.jar"
		width="400"
		height="400"
		mayscript="mayscript"
		alt="JUpload by www.jupload.biz">

	<param name="Config" value="cfg/filechooser.default.config">


	Your browser does not support applets or you disabled applets in your browser-options.
	To use this Applet, please install the newest version of Sun's Java Runtime Environment (JRE).
	You can get it from <a href="http://www.java.com/">java.com</a>
</applet>

Example 8.2. FileChooserPlugin-Configuration Example

To make the FileChooserPlugin register with the FileTypeChooserPlugin and the FolderChooserPlugin, the config file, specified in the <param> - tag, should contain something like this:

Register.FileTypeChooser=true
Register.FolderChooser=true
ShowFolders=false
ShowParentDir=false
WaitForPlugins=com.smartwerkz.jupload.plugins.builtin.filechooser.FolderChooserPlugin,\
com.smartwerkz.jupload.plugins.builtin.filechooser.FolderChooserPlugin

Important

When registering to any other plugin, the FileChooserPlugin becomes dependent on them so their classes must be added to the WaitForPlugins-List in order to ensure that they are available when the FileChooser is starting.

1.3. Javascript-Interaction

A list of available functions for interacting with this Plugin

gotoFolder(folder)
Sets the folder whose files should be shown.
getPanel().viewThumbnail()
Displays the thumbnail-view.
getPanel().viewList()
Displays the simple list-view.
getPanel().viewDetailed()
Displays the detailed table-view.
getPanel().gotoParent()
Switches to the current folder's parent-folder.
getPanel().gotoHome()
Switches to the local home-folder.
getPanel().gotoDefault()
Switches to the local user's default directory.
getPanel().getView().getSelected()
Returns all currently selected Files as an array (File[]).
getPanel().getView().getLeadSelection()
Returns the last selected File.
getPanel().getView().clearSelection()
Returns the last selected File.

2. FolderChooser Plugin

File: plugins/jupload-folderchooser.jar
Class: com.smartwerkz.jupload.plugins.builtin.folderchooser.FolderChooserPlugin

This plugin offers the user an explorer-like tree-structure of your local filesystem's directory-structure.

To add directories from this Plugin into JUpload, either activate the AddOnDClick-Parameter so that the user would add folders when Double-Clicking a folder or easily DragAndDrop a folder into JUpload to add it to the currently selected folder of the UploadTree.

The FileChooserPlugin can display all files of the last selected folder, if enabled through Configuration.

2.1. Configuration

AddOnDClick
Type
Boolean
Default Value
false
Description
Indicates wether or not folders should automatically be added to JUpload when double-clicking on one.
Config
See JUpload's configuration for further information.
ID
See JUpload's configuration for further information.
WaitForPlugins
See JUpload's configuration for further information.

2.2. Embedding the FolderChooser Plugin

Example 8.3. Embedd FolderChooserPlugin Example

Simply define the applet-tag in the embedding html-page as follows.

You might have to change the correct location of the jar-files, specified in the archive-tag and the location of the configuration-file, specified in the <param>-tag.

<applet
		title="FolderChooser Plugin"
		name="FolderChooserPlugin"
		code="com.smartwerkz.jupload.plugins.builtin.folderchooser.FolderChooserPlugin"
		codebase="."
		archive="jupload.jar,
				 plugins/jupload-folderchooserplugin.jar"
		width="300"
		height="400"
		mayscript="mayscript"
		alt="JUpload by www.jupload.biz">

	<param name="Config" value="cfg/folderchooser.default.config">


	Your browser does not support applets or you disabled applets in your browser-options.
	To use this Applet, please install the newest version of Sun's Java Runtime Environment (JRE).
	You can get it from <a href="http://www.java.com/">java.com</a>
</applet>

2.3. Javascript-Interaction

A list of available functions for interacting with this Plugin

getView().selectFolder(folder)
Selects the given Folder.
getView().getLeadSelection()
Returns the last selected Folder.
getView().getSelectedFolders()
Returns all currently selected Folders in an array.
getView().clearSelection()
Clears the selection (no folders will be selected anymore).

3. FileTypeChooser Plugin

File: plugins/jupload-filetypechooser.jar
Class: com.smartwerkz.jupload.plugins.builtin.filetypechooser.FileTypeChooserPlugin

This Plugin offers you a simple DropDown-Box to select certain filetypes. It can be used for restricting files which are shown or used by other Plugins.

The FileChooserPlugin can filter shown files according to the currently selected filter, if enabled through Configuration.

3.1. Configuration

FileFilters.Default
Type
List (String image,movie,office)
Default Value
image,movie,office
Description
Three default FileFilters that also can be seen in the screenshot above.
FileFilters.Ext
Type
List (ExtFileFilter)
Default Value
Description
A list of custom Extension-FileFilters that will be added to this FileTypeChooser.
FileFilters.Regex
Type
List (RegexFileFilter)
Default Value
Description
A list of custom Regex-FileFilters that will be added to this FileTypeChooser.
Config
See JUpload's configuration for further information.
ID
See JUpload's configuration for further information.
WaitForPlugins
See JUpload's configuration for further information.

3.2. Embedding the FileTypeChooser Plugin

Example 8.4. Embedd FileTypeChooserPlugin Example

Simply define the applet-tag in the embedding html-page as follows.

You might have to change the correct location of the jar-files, specified in the archive-tag and the location of the configuration-file, specified in the <param>-tag.

<applet
		title="FileTypeChooser Plugin"
		name="FileTypeChooserPlugin"
		code="com.smartwerkz.jupload.plugins.builtin.filetypechooser.FileTypeChooserPlugin"
		codebase="."
		archive="jupload.jar,
				 plugins/jupload-filetypechooserplugin.jar"
		width="270"
		height="20"
		mayscript="mayscript"
		alt="JUpload by www.jupload.biz">

	<param name="Config" value="cfg/filetypechooser.default.config">


	Your browser does not support applets or you disabled applets in your browser-options.
	To use this Applet, please install the newest version of Sun's Java Runtime Environment (JRE).
	You can get it from <a href="http://www.java.com/">java.com</a>
</applet>

4. DragNDrop Plugin

File: plugins/jupload-dnd.jar
Class: com.smartwerkz.jupload.plugins.builtin.dnd.DNDPlugin

This Plugin is a simple container which can be used to drag files from the filesystem or the FileChooserPlugin to.

The files will automatically be added to the currently selected node (folder) of JUpload's UploadTree.

4.1. Configuration

Images.Default
Type
Image
Default Value
Description
The default background-image.
Images.Drag
Type
Image
Default Value
Description
Image that is shown while the mouse is dragging into the Applet.
Images.Hover
Type
Image
Default Value
Description
Image that is shown while the mouse is hovering over the Applet.
Config
See JUpload's configuration for further information.
ID
See JUpload's configuration for further information.
WaitForPlugins
See JUpload's configuration for further information.

4.2. Embedding the DnDPlugin

Example 8.5. Embedd DnDPlugin Example

Simply define the applet-tag in the embedding html-page as follows.

You might have to change the correct location of the jar-files, specified in the archive-tag and the location of the configuration-file, specified in the <param>-tag.

<applet
		title="DnD Plugin"
		name="DnDPlugin"
		code="com.smartwerkz.jupload.plugins.builtin.dnd.DNDPlugin"
		codebase="."
		archive="jupload.jar,
				 plugins/jupload-dndplugin.jar"
		width="80"
		height="80"
		mayscript="mayscript"
		alt="JUpload by www.jupload.biz">

	<param name="Config" value="cfg/dnd.default.config">


	Your browser does not support applets or you disabled applets in your browser-options.
	To use this Applet, please install the newest version of Sun's Java Runtime Environment (JRE).
	You can get it from <a href="http://www.java.com/">java.com</a>
</applet>

5. ImagePreview Plugin

File: plugins/jupload-imagepreview.jar
Class: com.smartwerkz.jupload.plugins.builtin.imagepreview.ImagePreviewPlugin

This Plugin displays a preview of selected image-files.

You can configure it to preview the FileChooserPlugin's selection or JUpload's UploadView's selection.

If you want to preview both at the same time, simply add two ImagePreviewPlugins to the page.

5.1. Configuration

Preview.Background
Type
Color
Default Value
Description
The background color of the Applet.
Preview.FileChooserPlugin
Type
Boolean
Default Value
false
Description
(De)activates interaction with the FileChooserPlugin. If activated, it will preview the FileChooser's last selected image-file.
See Example below for more information.
Preview.JUpload
Type
Boolean
Default Value
true
Description
(De)activates interaction with JUpload's UploadViews. If activated, it will preview the UploadView's last selected image-file.
See Example below for more information.
Config
See JUpload's configuration for further information.
ID
See JUpload's configuration for further information.
WaitForPlugins
See JUpload's configuration for further information.

5.2. Embedding the ImagePreview

Example 8.6. Embedd ImagePreviewPlugin Example

Simply define the applet-tag in the embedding html-page as follows.

You might have to change the correct location of the jar-files, specified in the archive-tag and the location of the configuration-file, specified in the <param>-tag.

<applet
		title="ImagePreview Plugin"
		name="ImagePreviewPlugin"
		code="com.smartwerkz.jupload.plugins.builtin.imagepreview.ImagePreviewPlugin"
		codebase="."
		archive="jupload.jar,
				 plugins/jupload-imagepreviewplugin.jar"
		width="200"
		height="200"
		mayscript="mayscript"
		alt="JUpload by www.jupload.biz">

	<param name="Config" value="cfg/imagepreview.default.config">


	Your browser does not support applets or you disabled applets in your browser-options.
	To use this Applet, please install the newest version of Sun's Java Runtime Environment (JRE).
	You can get it from <a href="http://www.java.com/">java.com</a>
</applet>

Example 8.7. ImagePreviewPlugin-Configuration Example

To make the ImagePreviewPlugin register with the FileChooserPlugin instead of JUpload's UploadViews (which is default) the config file, specified in the <param> - tag, should contain something like this:

Preview.FileChooserPlugin=true
Preview.JUpload=false
WaitForPlugins=com.smartwerkz.jupload.plugins.builtin.filechooser.FolderChooserPlugin,\
com.smartwerkz.jupload.plugins.builtin.filechooser.FolderChooserPlugin

Important

When registering to the other plugin, the ImagePreviewPlugin becomes dependent on it so its class must be added to the WaitForPlugins-List in order to ensure that it is available when the ImagePreviewPlugin is starting.

5.3. Javascript interaction

A list of available functions for interacting with this Plugin

preview(fileOrNode)
Shows the preview of either a File, the location of a file in the local filesystem, or an UploadNode.

6. ProgressMeter Plugin

File: plugins/jupload-progressmeter.jar
Class: com.smartwerkz.jupload.plugins.builtin.progressmeter.ProgressMeterPlugin

This Plugin shows the progress during an Upload.

You can choose to display the total progress of the upload or the progress of each single file.

6.1. Configuration

Progress.Show
Type
String(total, current)
Default Value
total
Description
Set this value to either one of total or current to make this Plugin display the progress of each single file or the overall progress respectively.
Config
See JUpload's configuration for further information.
ID
See JUpload's configuration for further information.
WaitForPlugins
See JUpload's configuration for further information.

6.2. Embedding the ProgressMeterPlugin

Example 8.8. Embedd ProgressMeter Example

Simply define the applet-tag in the embedding html-page as follows.

You might have to change the correct location of the jar-files, specified in the archive-tag and the location of the configuration-file, specified in the <param>-tag.

<applet
		title="ProgressMeter Plugin"
		name="ProgressMeterPlugin"
		code="com.smartwerkz.jupload.plugins.builtin.progressmeter.ProgressMeterPlugin"
		codebase="."
		archive="jupload.jar,
				 plugins/jupload-progressmeterplugin.jar"
		width="80"
		height="80"
		mayscript="mayscript"
		alt="JUpload by www.jupload.biz">

	<param name="Config" value="cfg/progressmeter.default.config">


	Your browser does not support applets or you disabled applets in your browser-options.
	To use this Applet, please install the newest version of Sun's Java Runtime Environment (JRE).
	You can get it from <a href="http://www.java.com/">java.com</a>
</applet>

Appendix A. Appendix

1. License Agreement

You agree that your use of the SOFTWARE PRODUCT acknowledges that you have read this license, understand it, and agree to be bound by its terms and conditions.

This agreement applies to all software code samples and documentation developed by Mike Haller.

Important

READ CAREFULLY: This Software Licence Agreement (SLA) is intended to be a legal agreement between The Licensee and the Authors for the software product identified above which includes computer software and associated media and printed materials and many include “online” or electronic documentation (hereinafter called the “Software”) By installing copying or otherwise using the Software the Licensee agrees to be bound by the terms of this SLA if the terms of this SLA are not agreed do not install, copy or use the Software.

SOFTWARE LICENCE

The Software is protected by copyright laws and other intellectual property laws and rights and the Software is licensed not sold and no property in the Software shall pass as a result of any of the terms of the Licence

1. Definitions

In this Licence the following expression shall have the meanings as attributed to them.

Software shall mean the software product identified above which without prejudice to the generality of the forgoing shall include computer software and associated media and printed materials and may include online or electronic documentation and upgrades.

Licensee shall mean a person individual corporation partnership body corporate or any agency or organisation of whatever nature whether incorporated or not who desires to use and does use the Software.

2. In consideration of the purchase of the Software by the Licensee the Authors hereby grant to the Licensee the non exclusive right to

2.1 install and use the enclosed Software on its computers and other equipment to design develop and test

2.2 modify the sample source code located in the Software to design develop and test the content

2.3 reproduce and distribute the Sample Code in object code form along with any modifications made to the Sample Code PROVIDED ALWAYS THAT the Licensee complies with the Distribution Requirements described in clause 2.4 below and for purposes of this Licence “modifications” shall include enhancements to the functionality of the Sample Code

2.4 Copy and redistribute the Sample Code provided that the Licensee will

2.4.1 distribute the sample code only in conjunction with and as a part of its Application

2.4.2 the Application adds significant and primary functionality to the sample code

2.4.3 not use the Authors name logo or trademarks to market the Licensee Application except with the prior written consent of the Authors

2.4.4 include a valid copyright notice on its Application and

2.4.5 fully and effectively indemnify hold harmless and defend the Authors from and against any claims or demands of whatsoever nature that arise out of or result from the use or distribution of the Licensees Application

2.4.6 the Authors reserve all rights not expressly granted herein

3. All rights title and copyrights in and to the Software and any copies of the Software are owned by the Authors or its suppliers or assigns and the Licensee may not copy the printed materials if any accompanying the Software

4. The Licensee will not nor permit anyone to

4.1 reverse-engineer decompile or disassemble the Software

4.2 rent or lease the Software.

5. The Licensee may permanently transfer all of its rights under this SLA provided it retains no copies and transfers all of the Software (including all component parts the media and printed materials any upgrades this SLA and if applicable the Certificate of Authenticity) and the recipient agrees to the terms of this SLA PROVIDED ALWAYS THAT if the Software is an upgrade any transfer must include all prior versions of the Software

6. Without prejudice to any other rights the Authors may terminate this SLA if the Licensee fails to comply with the terms and conditions of this SLA and in such event the Licensee warrants that all copies of the Software and all of its component parts will be destroyed

7. The Authors expressly disclaim any warranty for the Software and any related documentation are provided as is without warranty of any kind either express or implied including without limitation the implied warranties of merchantability or fitness for a particular purpose and the entire risk arising out of the use or performance of the Software remains with the Licensee

8. In no event shall the Authors its suppliers or assigns be liable for any damages whatsoever (including without limitation damages for loss of business profit business interruption consequential loss or loss of business information or any other pecuniary loss or otherwise) arising out of the use of or inability to use this software even if the Authors have been advised of the possibility of such damages

Bibliography

RFC1867: Form-based File Upload in HTML. L. Masinter. E. Nebel. http://www.faqs.org/rfcs/rfc1867.html. 1995.

RFC2387: The MIME Multipart/Related Content-type. E. Levinson. ftp://ftp.rfc-editor.org/in-notes/rfc2387.txt. 1998.

RFC2616: Hypertext Transfer Protocol -- HTTP/1.1. R. Fielding. J. Gettys. J. Mogul. ftp://ftp.rfc-editor.org/in-notes/rfc2616.txt. 1999.

ISO639: Code for the representation of names of languages. Keld Simonsen. http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt. 1990-1996.

ISO3166: Codes (Countries). Maintenance Agency for ISO 3166 country codes. http://www.iso.org/iso/en/prods-services/iso3166ma/index.html. 1999.

W3C: Document Object Model (DOM). Philippe Le Hégaret. http://www.w3.org/DOM/. 2002.

W3C: HTML 4.01 Specification. Dave Raggett. http://www.w3.org/TR/html401/struct/objects.html#edef-OBJECT. 1999.

Appendix B. Reference

1. An overview over all configurable JUpload-Parameters

See the chapter on Parameters and types for more information.

All parameters:

Config
Type
URL
Default Value
Description
If set, JUpload automatically loads all configuration from the given file instead of using the Applet's <param> tags. This can be a file or script from the web or a file on the local hard-drive (eg. file://c:/me/somewhere/jupload-default.config). Be sure to use correct URL-Syntax to specify the location.
For further information, read here how to create a config-file.
Debug
Type
Boolean
Default Value
true
Description
If activated, provides additional information about the application's workflow in the console. This option is needed to track down errors within the application.
For further information, see information on debug.
Encoding
Type
String
Default Value
UTF-8
Description
An encoding tells the application how to work with text. Valid values are all known default encodings, such as ASCII, UTF-8, BIG5, ISO-8859-1 etc. If you have troubles displaying certain characters in JUpload correctly, it is usually because of the choice of encoding and/or the Font of choice (see Gui.LF.Font). The encoding is not only vital for displaying but also for correct names of uploaded files. It is important that the server and JUpload are using the same encoding. If you and your customers use a default roman alphabet, you are recommmended to use any of the "ISO-8859-*"-family as default encoding (such as ISO-8859-1). In case of a non-roman alphabet you should use another encoding where UTF-8 (also JUpload's default) should do just fine. We will provide further information on resolving issues with text displaying.
Files.Convert.Format
Type
String
Default Value
Description
All valid images will be converted into this format. Recommended to be left empty or either of "jpg" or "png" where converting to the PNG-format seems to inflate an image's size if it was jpg before.
Files.Convert.IncludeMetadata
Type
Boolean
Default Value
false
Description
Will also read EXTIF-metadata out of image files. Those values might contain information such as date of the image's creation or the author.
Files.Convert.InterpolationAlgo
Type
String(bilinear, bicubic, nearest)
Default Value
Description
Defines the interpolation-algorithm to be used when converting image-files. When using an interpolation algorithm, shrinked pictures will be rendered smoother.
Files.Convert.MaxHeight
Type
Integer
Default Value
-1
Description
All images whose height exceeds this value will be resized so their height will have this value and the width will be scaled in proportion.
Files.Convert.MaxWidth
Type
Integer
Default Value
-1
Description
All images whose width exceeds this value will be resized so their width will have this value and the height will be scaled in proportion.
Files.Filter.Duplicates
Type
Boolean
Default Value
true
Description
If activated, there cannot be 2 files with the same name within one directory so every file's path (relative position within the tree + name) is unique. This option is recommended to be activated since it is not possible to store 2 files with the same name at the same position anyway.
If you do not filter duplicates, you also need to change the file-receiving script on your server to work with duplicate files or else only the last occurance of the file will be saved.
Files.Filter.Folders
Type
Boolean
Default Value
false
Description
If set, only files can be added, folders cannot be uploaded and the user cannot create a hierarichal file structure. In this case it is also recommended to remove the "Add Folder" Button from the ContextMenus
Files.Filter.MaxImageDimension
Type
Dimension
Default Value
Description
Images with dimensions bigger than this will not be uploaded. Alternatively you can let JUpload convert the size of images automatically through the Files.Convert.MaxHeight and Files.Convert.MaxWidth parameters.
Files.Filter.Multi
Type
RegexFileFilter
Default Value
Description
A list of Regex FileFiters, that apply for all files, not only for those added through the GUI.
Files.ForceImageCache
Type
Boolean
Default Value
false
Description
This option should only be activated for developers who need all UploadImageFile's images to be cached. By default to save resources, images are only read and cached if necessary that is to satisfy other parameter's demands.
Files.KeepImagesCached
Type
Boolean
Default Value
false
Description
This option should only be activated for developers who want all cached UploadImageFile's images to remain cached (where they have to be released manually later on). By default all cached imagefiles' images are released after preparation to save resources.
Files.MaxImageSize
Type
Integer
Default Value
10485760
Description
The maximum size of images to be cached to prevent JUpload from crashing due to lack of resources. Image-files which exceed this value, will then only be added as normal files in case that Files.UploadInvalidImages is set to true.
Files.Preselected
Type
List (File)
Default Value
Description
A list of files from the local file-system. These files will be added to JUpload's tree automatically upon startup.
Files.Thumbnails.Smooth
Type
Boolean
Default Value
true
Description
Uses antialiasing to create thumbnails for upload and displaying.
Files.UploadInvalidImages
Type
Boolean
Default Value
true
Description
If set, images that could not be rendered during preparation will also be uploaded. This includes Files that for example have an image extension such as ".jpg" but are actually just a renamed file of another format or image-files that exceed the Files.MaxImageSize.
Gui.ContextMenu.Files
Type
List (String Seperator,ConvertImage,PasteClipboard,CopyClipboard,SaveFiles,DeleteFiles,RenameFile,AddFolder,ShowInvalids,Screenshot,ScreenshotDelay,About,Options,JUploadScreenshot)
Default Value
AddFolder,Seperator,ConvertImage,Seperator,CopyClipboard,PasteClipboard,Seperator,RenameFile,SaveFiles,DeleteFiles
Description
Describes the order of items within the contextmenu that pops up when rightclicking on any of the UploadViews.
Gui.ContextMenu.General
Type
List (String Seperator,ConvertImage,PasteClipboard,CopyClipboard,SaveFiles,DeleteFiles,RenameFile,AddFolder,ShowInvalids,Screenshot,ScreenshotDelay,About,Options,JUploadScreenshot)
Default Value
ShowInvalids,Options,Seperator,Screenshot,JUploadScreenshot,ScreenshotDelay,Seperator,About
Description
Describes the order of items within the Tool-Menu associated with the corresponding button in the toolbar.
Gui.DeactivateOnUpload
Type
Boolean
Default Value
false
Description
Deactivates all Buttons and the user cannot modify anything during an Upload anymore.
Gui.FileChooser.DefaultDir
Type
File
Default Value
Description
The default selected directory in the FileChooser. Defaults to the directory that the user opened last during the last session.
Gui.FileChooser.Filter.All
Type
Boolean
Default Value
true
Description
Shows the *.* all-filefilter within the FileChooser.
Gui.FileChooser.Filter.Image
Type
Boolean
Default Value
true
Description
Adds a filefilter for image-files to the FileChooser.
Gui.FileChooser.Filter.Multi
Type
List (RegexFileFilter)
Default Value
Description
A list of Filefilters using Regular expressions that will be added to the FileChooser. A selected filefilter, prohibits display of all files that are not specified through the filter. Files in subfolders that are not allowed by a filter will not be added either.
Gui.FileChooser.Preview.Enabled
Type
Boolean
Default Value
true
Description
If activated, the FileChooser will show a preview of selected image files on the right side.
Gui.FileChooser.Preview.FixedWidth
Type
Boolean
Default Value
true
Description
Determines wether the imagepreview within the FileChooser should have a fixed width or shrink if a thumbnail is smaller than the width given through Gui.FileChooser.Preview.Size.
Gui.FileChooser.Preview.Show
Type
Boolean
Default Value
false
Description
Displays the "Show Preview" checkbox under the imagepreview to give the user an opportunity to (de)activate it.
Gui.FileChooser.Preview.Size
Type
Dimension
Default Value
192x192
Description
The maximum dimensions of the FileChooser's previewed images. If the dimension of an image exceeds in either width or height, the image will be resized and keep its original proportions.
Gui.FileChooser.Preview.Smooth
Type
Boolean
Default Value
false
Description
Shows the "Smooth"-checkbox within the FileChooser's imagepreview. This button gives the user an option to use antialiasing for rendering the previewed images. The checkbox cannot be unchecked if Files.Thumbnails.Smooth is set since all thumbnails will be rendered with antialiasing anyway.
Gui.FileChooser.Size
Type
Dimension
Default Value
800x600
Description
The default size of the FileChooser in pixels.
Gui.ImageView.ItemGap
Type
Integer
Default Value
4
Description
The gap (empty space) that should be left between the GUI's thumbnail-view's single thumbnails in pixels.
Gui.ImageView.ItemSize
Type
Dimension
Default Value
Description
The width and height of the displayed thumbnails in the thumbnail-view. It defaults to Upload.Thumbnails.Size to save resources.
Gui.LF.Background
Type
Color
Default Value
Description
The background color of all displayed components.
Gui.LF.Borders
Type
Boolean
Default Value
true
Description
Use default LookAndFeel's borders or not.
Gui.LF.Classname
Type
String
Default Value
Description
The fully qualified classname of the Look And Feel (L&F) to be used. It defaults to the Windows-LookAndFeel under Windows and the "Metal"-LookAndFeel under any other OS.
You can use the following shortcuts for default and common L&Fs: metal, windows, basic, skinlf
Gui.LF.Font
Type
Font
Default Value
Description
The default font for all displayed text. If not changed, the overall-font is system-default. Customers with an international set of users need to take the used alphabet in consideration when choosing a font. The default on each operating system is always able to display the language of the system correctly.
Please note that windows-users with a language that uses the roman alphabet (eg from America, Europe or Australia) are not able to see fonts of other non-roman languages with the default font.
Also see Encoding for further information on resolving issues with non-roman languages.
Gui.LF.Foreground
Type
Color
Default Value
Description
The foreground (text) color of all displayed components.
Gui.LF.OverrideColorsBorders
Type
Boolean
Default Value
false
Description
Use all Gui.LF.* parameters for colors and borders to override the GUI-defaults or not.
Gui.LF.OverrideFont
Type
Boolean
Default Value
true
Description
Use Gui.LF.Font to override the default font or not.
Gui.LF.SelectedBackground
Type
Color
Default Value
Description
The background color of a selected component or item (for example within the UploadViews).
Gui.LF.SelectedForeground
Type
Color
Default Value
Description
The foreground- (text-) color of a selected component or item (for example within the UploadViews (list of files to be uploaded)).
Gui.LF.SkinPackUrl
Type
URL
Default Value
Description
The URL (can be relative to the embedding website's URL) refers to a skinpack for the SkinLookAndFeel by l2fproductions (please see the the L&F-overview for more information).
Gui.ServerResponse.AutoShow
Type
Boolean
Default Value
true
Description
Automatically expands the Response-Panel when receiving the first line of response from the server during the upload.
See Server Response for more information.
Gui.ServerResponse.Enable
Type
Boolean
Default Value
true
Description
Wether to enable the Response-Panel and to show the response that is sent by the http-server within JUpload.
See Server Response for more information.
Gui.ServerResponse.Height
Type
Integer
Default Value
100
Description
The height of the Response-Panel.
See Server Response for more information.
Gui.Status.BorderColor
Type
Color
Default Value
#000000
Description
The Statusbar's border-color. The statusbar is displaying status-information at the very bottom.
Gui.Status.PanelHeight
Type
Integer
Default Value
70
Description
The height of the UploadStatus in pixels.
Gui.Status.ShowBar
Type
Boolean
Default Value
true
Description
Wether to enable and show the statusbar at the bottom of the Applet.
Gui.Status.ShowPanel
Type
Boolean
Default Value
true
Description
Wether to show the upload-status which displays the upload-progress
Gui.Status.ShowPrepare
Type
Boolean
Default Value
true
Description
Wether to show the prepare-status which displays the progress on files being prepared and added.
Gui.Status.ShowSuccessDialog
Type
Boolean
Default Value
true
Description
If activated shows a dialog with a message, informing the user about the success when upload finished and the server returned a HTTP/200 - header.
Gui.Toolbar.Buttons
Type
List (String add,remove,upload,menu)
Default Value
add,remove,upload,menu
Description
The sequence of the Toolbar-buttons. Will not display any toolbar if left empty.
Gui.Views.AutoSelectAddedFiles
Type
Boolean
Default Value
false
Description
Wether to automatically select newly added files in the UploadView.
Gui.Views.Details.Widths
Type
List (Integer)
Default Value
Description
A list of numbers that represent the widths of the DetailedView's columns in pixels. Gives each column the same width by default.
Gui.Views.Display
Type
List (String list,thumbnail,details,tree)
Default Value
tree,list,details,thumbnail
Description
The sequence of the UploadViews to be shown.
If left empty, no view and no files will be shown. This is only recommended in case that you have a custom implementation of this view within a Plugin or JavaScript.
Gui.Views.Icon.MaxHeight
Type
Integer
Default Value
32
Description
The maximum height of icons or thumbnails shown in the List-View. If thumbnails exceed this height, they will be resized in proportion.
Gui.Views.Icon.MaxWidth
Type
Integer
Default Value
32
Description
The maximum width of icons or thumbnails shown in the List-View. If thumbnails exceed this width, they will be resized in proportion.
Gui.Views.Icon.SystemIcons
Type
Boolean
Default Value
true
Description
Wether to show systemicons (rather than no icons at all for non-image files).
Gui.Views.ShowPaths
Type
Boolean
Default Value
false
Description
Wether to show the complete path of a file within the upload-hierarchy or only their name.
Gui.Views.Thumbs.Enabled
Type
Boolean
Default Value
true
Description
Wether to display thumbnails in the list-view.
Gui.Views.Tree.MinSize
Type
Dimension
Default Value
120x200
Description
The minimum dimension of the treeview in pixels. It cannot be made smaller than this.
ID
Type
String
Default Value
jupload0
Description
This parameter is only needed when having multiple instances of JUpload running on one page (which is not recommended).
The ID is then used for Plugins to determine to which instance of JUpload they belong.
Locale
Type
Locale
Default Value
Description
The locale determines appereance and language of JUpload and its Plugins. Defaults to the user's Operating System's settings if not explicitely set.
MinJavaVersion
Type
Double
Default Value
1.4
Description
The minimum Java Version that the user needs in order to run JUpload.
If a user's Java-Version is lower than this, he/she will be warned and offered to go to the Java-Website to download the latest version.
Should only be changed when using Plugins that need a higher version than the default value.
Upload.Auth.AutoLogin
Type
StringPair
Default Value
Description
A user=pw pair that this client uses to log into the server. Serverside user-authentication can for example be activated through an .htaccess-file.
See information on Authentication for more details.
Upload.Auth.UserAuthRequired
Type
Boolean
Default Value
false
Description
Needs to be set if any kind of authentication is required to access the Target-URL (Upload.URL.Action).
See information on Authentication for more details.
Upload.AutoRemove
Type
Boolean
Default Value
false
Description
Wether or not to automatically remove files that have been uploaded from the UploadViews.
Upload.Autostart
Type
Boolean
Default Value
false
Description
Indicates wether to automatically upload all files that are added through the Files.Preselected-Parameter when the Applet just started.
Upload.Complete.ErrorURL
Type
URL
Default Value
Description
Replaces the applet or a certain target frame with the given URL in case the Upload is not successful.
Upload.Complete.Target
Type
String
Default Value
Description
A target frame for Upload.Complete.URL and Upload.Complete.ErrorURL.
Upload.Complete.URL
Type
URL
Default Value
Description
Replaces the applet or a certain target frame with the given URL in case the Upload is successful.
Upload.Formname
Type
String
Default Value
Description
Contains the name of a form within the current page who's fields will be sent as GET-Values with each Upload-session.
See the custom user-information - Feature for details.
Upload.Http.AdditionalHeaders
Type
Map (String, String)
Default Value
Description
A map of additional HTTP-headers that should be sent to the server with each file-upload.
Upload.Http.AdditionalPostFields
Type
Map (String, String)
Default Value
Description
A map of additional POST-fields that should be sent to the server (when using POST-request).
Upload.Http.Auth.Scheme
Type
String(basic, digest, ntlm)
Default Value
basic
Description
The authentication scheme that is used for the server. The value can be either of basic, digest or ntlm. If you do not know which authentication you are using, it is probably "basic".
The NTLM-authentication is implemented but still untested, please let us hear about any feedback if you require or use it. Also note that Microsoft lately renamed this scheme from NTLM (NT Lan-Manager) to IWA (Integrated Windows Authentication).
See information on Authentication for more details.
Upload.Http.Cookies
Type
Map (String, String)
Default Value
Description
A map of cookies to be sent to the HTTP-server with each file-upload.
Upload.Http.ExpectedHeaders
Type
IntegerRanges
Default Value
Description
A range of numbers that represent valid Header-Status codes in order for the upload to continue.
See the validity-check - feature for details.
Upload.Http.MaxRequestFileCount
Type
Integer
Default Value
-1
Description
The maximum amount of files that can be sent within one POST-request. A negative value sigals no limit.
See webserver-configuration.
Upload.Http.MaxRequestSize
Type
Long
Default Value
8388608
Description
The maximum total length of all files that can be sent within one POST-request in bytes. Note that you should not set this option too high because the HTTP-server might not support it and that the implementation of the POST method requires the HTTP-server to completely receive all files of one request before actually being able to save them.
See webserver-configuration.
Upload.Http.Meta.AbsolutePath
Type
Boolean
Default Value
false
Description
Send the absolute path of all real files on the local file system (eg Screenshots are not real files unless they have been saved to the hard disk).
See Meta-Information.
Upload.Http.Meta.FileTag
Type
String
Default Value
files
Description
The tagname of all files that are sent using the POST-request. The actual name will be <FileTag><number> where <number> is the position of the corresponding file within the current POST-request (eg since the default for this parameter is "files": files1).
See Meta-Information.
Upload.Http.Meta.LastModified
Type
Boolean
Default Value
true
Description
Wether to send the time of the last-modified-time of uploaded files.
See Meta-Information.
Upload.Http.Meta.MD5
Type
Boolean
Default Value
false
Description
Wether to send the MD5 hash of the file.
See Meta-Information.
Warning
Enabling this option might be very slow for large files or large amounts of files.
Upload.Http.Method
Type
String(post, put)
Default Value
post
Description
The HTTP method to use for upload. Currently supported are POST or PUT.
Upload.Http.Query
Type
Map (String, String)
Default Value
Description
A map of query- (or GET-) values to be added to the HTTP-request for each file-upload.
Upload.MaxFileSize
Type
Long
Default Value
-1
Description
The maximum file size that is allowed to be uploaded. If selected files exceed this size, the user will be warned and the files will not be added/uploaded.
Negative value indicates no limit.
Upload.MaxTotalFileCount
Type
Integer
Default Value
-1
Description
The maximum amount of files to be uploaded. The user cannot upload more than this value in one session.
Negative value indicates no limit.
Upload.MaxTotalFileSize
Type
Long
Default Value
-1
Description
The maximum total file size. The user cannot upload files whose total size exceeds this value.
Negative value indicates no limit.
Upload.Retries
Type
Integer
Default Value
3
Description
The count of retry-attempts per upload-session. JUpload will retry as often as specified in case of network errors or unexpected connection losses.
Upload.SSLTrustManagerClass
Type
String
Default Value
Description
The name of a custom class which implements javax.net.ssl.X509TrustManager which determines wether or not SSL certificates from a secure serrver should be accepted.
By default JUpload silently accepts all certificates. This might be considered a security risk in certain environments, see JUpload's SSL features.
Upload.Thumbnails.Enable
Type
Boolean
Default Value
false
Description
Wether to create and upload thumbnails of image files that are uploaded.
See Thumbnail-Support for further information.
Upload.Thumbnails.Format
Type
String
Default Value
jpg
Description
The target image-format of the thumbnails ("jpg" or "png").
See Thumbnail-Support for further information.
Upload.Thumbnails.Http.AdditionalHeaders
Type
Map (String, String)
Default Value
Description
A map of additional headers that should be sent with each thumbnail-request.
See Thumbnail-Support for further information.
Upload.Thumbnails.Http.AdditionalPostFields
Type
Map (String, String)
Default Value
Description
A map of additional post-fields that should be sent with each thumbnail-request.
See Thumbnail-Support for further information.
Upload.Thumbnails.Http.Cookies
Type
Map (String, String)
Default Value
Description
A map of cookies that should be sent with each thumbnail-request.
See Thumbnail-Support for further information.
Upload.Thumbnails.Http.Query
Type
Map (String, String)
Default Value
Description
A map of additional query-pairs that should be sent with each thumbnail-request.
See Thumbnail-Support for further information.
Upload.Thumbnails.Http.TagName
Type
String
Default Value
thumbnail
Description
The HTTP-tagname for thumbnails to identify a thumbnail file (See Upload.Http.Meta.FileTag).
See Thumbnail-Support for further information.
Upload.Thumbnails.Size
Type
Dimension
Default Value
100x100
Description
The maximum dimension of the created thumbnails.
See Thumbnail-Support for further information.
Upload.Thumbnails.TargetURL
Type
URL
Default Value
Description
The target URL for thumbnails to be uploaded to.
See Thumbnail-Support for further information.
Upload.URL.Action
Type
URL
Default Value
Description
The target URL for the files to be uploaded to. SSL and SHTTP are also supported.
WaitForPlugins
Type
List (String)
Default Value
Description
Note
This parameter is also supported by all Plugins.
A list of plugins that JUpload or any implementing Plugin should wait for.
When a Plugin depends other Plugin(s), make sure to have it wait by filling this parameter with the fully-qualified classnames of all Plugins that it depends on.
See Plugin-Support and the FileChooserPlugin-Example for further information.

2. JUpload's Javascript API-Reference

2.1. Types used in the Javascript-Api

This is an overview over the most important types in JUpload's Javascript-Api.

UploadNode, UploadTree , UploadFile and UploadImageFile basically have the same functions and functionality and are used to represent and manipulate the structure of the uploaded files. They all represent files and folders that are to be uploaded.

UploadTree and UploadFile are also UploadNodes.

UploadImageFile is also an UploadFile.

UploadNode

The following functions are used for all kinds of UploadNodes, including UploadTree, UploadFile and UploadImageFile

isFolder()
If true, this node represents a simple folder or the UploadTree itself. If false, this node is either an UploadFile or an UploadImageFile.
getFullName()
The fullname of the file (getName().getExtension())
getName()
The given name of this directory or file without extension.
getExtension()
The extension of this node. Returns an empty string for directories and the corresponding file-extension/format for files.
setFullName(name)
Tried to change the name of this directory or file. Returns true or false, depending on if it succeeded. The name is illegal if duplicated are prohibited and this Node's parent already contains a child with the same name.
getPath()
The full path within the upload-tree.
getLocation()
The location of this node (without the name) within the upload-tree.
getTree()
The UploadTree that this node belongs to.
getDepth()
The depth of this node equals the amount of ancestors: The UploadTree has depth = 0, direct children -> 1, children's children -> 2 etc.
isVirtual()
False for files that are existing in the local filesystem, true for directories, screenshots and copied images.

The following functions are only usable for pure folders or the UploadTree itself and cannot be used for UploadFiles or UploadImageFiles:

get(index)
Returns the child-node with the given index.
get(name)
Returns the child-node with the given name.
getAll(sorted)
Returns all successor-UploadNodes of this node in an array.
If sorted is true the nodes will be sorted by folders and depth, else they have the order in which they were added.
count()
Returns the amount of children of this node.
contains(name)
Returns wether or not this node contains a child with the given name.
add(filepath)
Adds the file with the given path as child to this node.
add(filepaths)
Adds an array of paths to files on the local filesystem as child to this node.
remove(name, recurse)
Removes all descendants with the given name.
recurse is of type boolean and indicates wether or not to also remove files and directories with the given name from all subdirectories.
removeAll()
Removes all children from this node.

UploadTree

UploadTree is also an UploadNode and represents the root ("/") for all files and folders to be uploaded.

getFileCount()
The total count of all Files within the tree (does not count directories).
getTotalLength()
Returns the total amount of bytes of all files and thumbnails added together.
cancelPrepare()
Cancels the current preparation (if tree is currently preparing) and notifies all listeners.
preparing()
Indicates wether or not the tree is currently preparing.
getInvalids()
Returns an array of all current InvalidFileArgs. They represent files that are invalid and could not be added for a given reason.
clearInvalids()
Clears the list of invalid files and their reasons.
getNode(nodePath)
Returns the node with the given path within this tree.
removePath(nodePath)
Removes the node or file with the given path within this tree.
remove(node)
Removes the given node from this tree.
remove(nodes)
Removes the given array of nodes from this tree.

UploadFile, UploadImageFile

UploadFile and UploadImageFile represent normal files from the local file-system. They are also UploadNodes.

UploadImageFiles represent either images (jpg, png etc) from the local filesystem or virtual files, such as screenshots or images that have been pasted into JUpload.

getUnderlyingFile()
The underlying File or null if virtual.

These are some miscellaneous types with different purposes:

UploadClient

Can be used for following the upload-progress.

uploading()
Returns wether or not an Upload is currently in Progress.
getFileURL()
The URL where all files should be uploaded to.
getThumbnailURL()
The URL where all thumbnails should be uploaded to.
getCurrentEntity().getFullName()
The name of the file or thumbnail's file currently being uploaded.
getCurrentEntity().getPath()
The path of the file or thumbnail's file currently being uploaded within the upload-tree.
getProgress().getStartTime()
The start time in milliseconds since 01/01/1970.
getProgress().getCurrentBytesUploaded()
The amount of bytes that have been sent during the upload of the current or last file.
getProgress().getTotalBytesUploaded()
The total amount of bytes that have been uploaded during the current or last upload-session.
getProgress().getCurrentBytes()
The amount of bytes of the current file.
getProgress().getTotalBytes()
The total amount of bytes to be uploaded during this session.
getProgress().getCurrentSpeed()
The average speed of the current or last file in bytes per second.
getProgress().getRemainingTime()
The estimated amount of seconds until all files have been uploaded.
getProgress().getEta()
Remaining time + starttime
getProgress().getCurrentPercent()
Percentage of uploaded bytes of the current file.
getProgress().getTotalPercent()
Percentage of uploaded bytes of the complete upload-session.

JUploadGui

The default Graphical User Interface.

statusMessage(message)
Shows the given message in the StatusBar at the bottom (if statusbar exists).
getResponsePanel().clear()
Clears the responsepanel (if panel exists).
getCurrentFolder()
The UploadNode representing the folder that is currently being viewed by the user.
queryScreenCaptureDelay()
Queries the user for a new delay which JUpload waits before taking a screenshot.
getTreeDisplayer().getLeadSelection()
The most recently selected UploadNode.
getTreeDisplayer().getSelected()
All currently selected UploadNodes in an array.
getTreeDisplayer().clearSelection()
Deselects all currently selected elements.

UploadView

The TreeView, ListView, DetailedView or ThumbnailView within the Applet are all UploadViews.

getSelected()
Returns all currently selected UploadNodes in an array (UploadNode[]). UploadNodes can also be UploadFiles
getLeadSelection()
Returns the most recently selected UploadNode.
select(uploadNode)
Selects the given UploadNode.
clearSelection()
Clears the selection.
isSelected(uploadNode)
Returns wether or not the given UploadNode is selected.

2.2. Javascript-Listeners

An overview over JUpload's listeners and their corresponding listener-functions

Listeners are explained in the javascript-chapter.

ResponseListener

responseReceived(String status, String response, int statusCode)
One upload finished (every file for PUT, several files according to the limits for POST), the server responded and had the given status-message and statuscode.
The response contains the complete HTML-formated output of the server which is a concatenation of all partial responses received.
partialResponseReceived(String responsePart)
After all files have been uploaded, whenever the server sends something, this method will be called with the corresponding part of the response that the server just sent.
This might be important if the actual processing of the files after the download is a longer process.

UploadProgressListener

initializing(UploadClient client)
The upload is about to start. The time between initializing and initialized can be of undefined length because the tree might still be adding nodes and the upload won't be initialized before the preparation of all added nodes has finished.
initialized(UploadClient client)
The upload is starting.
failed(UploadClient client, UploadEntity currentEntity, Exception reason)
The upload failed for on the given entity (an UploadFile or a Thumbnail) for the given reason.
The supplied argument currentEntity is null in case that we could not connect.
dequeued(UploadClient client, UploadFile file)
The given file has been dequeued and will be uploaded within the next chunk.
When using POST files within one request will first be dequeued and added to it until there is no space left in the request. Then the files of the request will be uploaded one by one.
When using PUT every file will be dequeued and uploaded one by one.
uploadingFileStart(UploadClient client, UploadFile file)
The given file is being uploaded.
uploadingFile(UploadClient client, UploadFile file, int bytes)
Another bytes bytes of the given file have been uploaded.
uploadedFile(UploadClient client, UploadFile file)
The given UploadFile has been uploaded.
uploadingThumbStart(UploadClient client, UploadImageFile file)
The thumbnail of the given file is being uploaded.
uploadingThumb(UploadClient client, UploadImageFile file, int bytes)
Another bytes bytes of the thumbnail of the given file have been uploaded.
uploadedThumb(UploadClient client, UploadImageFile file)
The thumbnail of the given file has been uploaded.
closed(UploadClient client, boolean succeeded)
The upload was stopped by the user or we finished uploading and the server gave us a HTTP-200 header. In the second case, succeeded is true.

UploadTreeListener

initAdding(UploadTree tree, UploadNode target)
The tree is about to add new Files to the given UploadNode. It is now searching for all files that are to be added. This might take a while depending on the amount of files and depth of added directories.
If the tree is already adding files and new files are being added, the new files are also added to the tree's preparation-queue.
adding(UploadTree tree, UploadNode target, int count)
count files have been found and are now starting to be prepared and added to the tree.
preparing(UploadTree tree, UploadNode parent, UploadFile file)
The given file is being prepared to be added to the given parent. The UploadFile's parent is null since it has not yet been added to the tree.
invalidFile(UploadTree tree, InvalidFileArgs args)
A file could not be added for the given reason.
nodeAdded(UploadTree tree, UploadNode node)
The given UploadNode has been added. The node could be a directory, a virtual file or a file from the local filesystem.
fileSaved(UploadTree tree, UploadFile file)
The given file has been saved
nodeRenamed(UploadTree tree, UploadNode node)
The given UploadNode's name has changed.
nodeRemoved(UploadTree tree, UploadNode node)
The given UploadNode has been removed from the tree.
finishedAdd(UploadTree tree)
A set of files have been successfully added to the tree.

ViewSelectionListener

selectionChanged(UploadView view)
The set of selected UploadNodes within the given UploadView changed.

DebugListener

thrown(Throwable t, String stacktrace)
This function is called if the given Throwable has been thrown unexpectedly.
In Java, Throwables represent program-malfunctions. The throwable represents the error itself in human-readable form and the stacktrace reveals the location of the problem.
This can be used for error-feedback. If your users encounter these malfunctions, you can -for example- log them and redirect them to the Smartwerkz-Team who will then be able to help you and fix the problem.
info(String info)
Debug- or runtime-information.

ResponseLinksListener

activated(String url)
A link to the given URL has been clicked on in the ResponsePanel.
over(String url)
The mouse is hovering over a link to the given URL in the ResponsePanel.