JUpload Classic

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.

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

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

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.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.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.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

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

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:

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.

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.

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.

$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
}

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:

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.

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

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.

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.

In the following table all other types are explained:

String (put, post)

See here for a ist of all parameters

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:

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.

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:

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

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.

<?
// 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>

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.

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

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).

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

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

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).

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.

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.

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

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.

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.