JDownload Manual

JDownload is a tool for multiple downloads from a HTTP server to a user's local file system in one step. It's implemented as a Java Applet and thus platform independent.

The tool is designed for a comfortable, userfriendly interface, so users can easily start using it, without practice.

Furthermore, the tool can be customized to suit the needs of webmasters: changing colors, the look-and-feel or even use advanced customization. For more details, see the Administrator's Manual.

Client:

Server:

No special requirements on server needed. It must serve the binary JDownload archive (jdownload.jar) and (dynamically) create the XML data.

Configuring the applet is very easy.

By using PARAM tags, you can setup the preferences:

<applet 
  code="biz.jupload.jdownload.Manager"
  archive="jdownload.jar"
  width="50%"
  height="50%"
  name="JDownload"
  mayscript="mayscript"
  alt="JDownload by www.jupload.biz">

 <!-- Java Plug-In Options -->
 <param name="progressbar" value="true">
 <param name="boxmessage" value="Loading JDownload Applet ...">

 <!-- An URL pointing to the data structure containing the list of
      files and folders to download -->
 <param name="dataURL"
        value="http://jdownload.jupload.biz/download.xml">

 <!-- Show or Hide the controls 
      If hidden (set all to 'false'), remote control the applet
	  using JavaScript buttons -->
 <param name="showExplorer" value="true">
 <param name="showControls" value="true">
 <param name="showBrowser" value="true">
 <param name="showStatus" value="true">

 Your browser does not support applets.
 Or you have disabled applets in your options.
 To use this applet, please update your Java.
 You can get it from <a href="http://www.java.com/">java.com</a>

</applet>

The user cannot start the download if you hide the control buttons and do not provide another way (via JavaScript) to remote control the applet.

You can use the JavaScript function clickDownload() to start the download process automatically without any user action.

The following settings are dependent on the Java Plugin being used by the user, they are not part of JDownload:

See this document on how to use the settings with OBJECT and EMBED tags, rather than the (deprecated) APPLET tag: http://java.sun.com/j2se/1.4.2/docs/guide/plugin/developer_guide/using_tags.html

We use the APPLET tag in the documentation for presentational reasons.

The following attributes of the APPLET tag are support by Java.

At first, you should edit the provided sample file (download.xml) to suit your needs. However, it will run without any modifications. The user will download the provided sample archive (sample.zip) multiple times to different folders and filenames on his local machine.

To edit the XML Data File, you can use a text editor or a XML editor. You can find the specification of the XML structure in the provided DTD file (download.dtd). Use it for validating the XML data file to make sure it can be read correctly by the JDownload tool.

Sample:

<?xml version="1.0" encoding="UTF-8"?>
<download>
 <folder name="SampleFolder">
  <folder name="SubFolder1">
   <file name="sampleFile1.zip">
    <url>sample.zip</url>
   </file>
   <file name="sampleFile2.zip">
    <url>sample.zip</url>
   </file>
  </folder>
  <file name="sampleUncompress.zip" uncompress="true">
   <url>sample.zip</url>
  </file>
 </folder>
</download>

As you can see in this example, there is the root element download. All other nested elements must be surrounded by the unique download element.

You can add folders via the folder element. The attribute name specifies the name of the folder, which will be created on the client side. Folders can have nested subfolders.

Downloadable items are specified by the file element, which also has an attribute name for specifying the filename on the client side.

For auto-uncompress the file, use the uncompress attribute, described in Section 5, “Auto-Uncompressing”

Files cannot have any children elements like file or folder, but they do have a source address. The source URL of the file to download is specified via an url element.

The url element specifies an absolute URL to the file, but might also be relative to the codebase URL. The codebase URL is the URL where the applet is loaded from.

If, for example, the JDownload component is installed to

http://www.example.com/downloads/jdownload.jar

the codebase URL is

http://www.example.com/downloads/

On server side, you can generate the XML data file dynamically. All you have to configure in JDownload, is to point the dataURL parameter to the URL of the script, which generates the data:

<param name="dataURL" value="createxml.php">

Within the server-side script, you can dynamically generate the XML structure. For example, you can use a cutomer id or a session identifier to generate personalized download sets for the user.

See the sample script createxml.php on how to create XML files with PHP:

<?php
// $Id: jdownload-manual-en.xml,v 1.2 2005/01/24 16:23:43 mhaller Exp $
//
// JDownload
// sample php script to dynamically generate XML Data file
// Copyright (c) 2005 Haller Systemservice
//
// http://jdownload.jupload.biz
//

// Create an empty XML Document with UTF-8 encoding
$dom = new DOMDocument('1.0', 'UTF-8');

// Create an empty root element
$rootelement_download= $dom->createElement('download');

// Create a folder element and give him a name
$samplefolder1 = $dom->createElement('folder');
$samplefolder1->setAttribute('name','SampleFolder1');

// Create a subfolder element and give him a name
$subfolder1 = $dom->createElement('folder');
$subfolder1->setAttribute('name','SubFolder1');

// Create three files, and give them names
// One file will be auto-uncompressed after being downloaded
$uncompressfile = $dom->createElement('file');
$uncompressfile->setAttribute('name','sampleUncompress.zip');
$uncompressfile->setAttribute('uncompress','true');
$file1 = $dom->createElement('file');
$file1->setAttribute('name','sampleFile1.zip');
$file2 = $dom->createElement('file');
$file2->setAttribute('name','sampleFile2.zip');

// The files need URLs where we can download them
// we just use the same URL for all three files for
// demonstration purposes.
$url1 = $dom->createElement('url');
$url2 = $dom->createElement('url');
$url3 = $dom->createElement('url');

$url1->appendChild($dom->createTextNode('sample.zip'));
$url2->appendChild($dom->createTextNode('sample.zip'));
$url3->appendChild($dom->createTextNode('sample.zip'));

// add the URLs to the files
$file1->appendChild($url1);
$file2->appendChild($url2);
$uncompressfile->appendChild($url3);

// add the files to the folders
$subfolder1->appendChild($file1);
$subfolder1->appendChild($file2);

$samplefolder1->appendChild($subfolder1);
$samplefolder1->appendChild($uncompressfile);

// add the folders to the root element
$rootelement_download->appendChild($samplefolder1);

// add the root element to the DOM (Document Object Model)
$dom->appendChild($rootelement_download);

// just print out the file. this will be later read by JDownload
$dom->normalize(); 
print $dom->saveXML();

?>

JDownload is capable of automatically uncompress downloaded ZIP archives on the clients file system.

This can be used to decrease the download time, especially with download sets containing many files, as compressing them and archiving them into a single file will significantly reduce download duration.

To use this feature, add the attribute uncompress="true" to the file element:

<file name="sampleUncompress.zip" uncompress="true">
 <url>sample.zip</url>
</file>

Webmasters can customize the JDownload component to suit their design and layout needs.

The built-in components of JDownload (Explorer-Tree, Control Buttons, Target Folder Chooser) can be disabled and hidden.

If the applet is made completely hidden, you need a way to remote control it, so the user can browse for another target folder, start the download progress or stop the download progress.

You can provide this functionality by implementing it in JavaScript. Executing several actions is done by calling the JavaScript API:

<applet
  code="biz.jupload.jdownload.Manager" 
  archive="jdownload.jar"
  width="50%"
  height="50%"
  name="JDownload"
  mayscript="mayscript">

This is the corresponding JavaScript code to remotely invoke a click to the Browser button:

function openBrowseDialog() 
{ 
 JDownload.clickBrowse();
}

For example, it can be called by a button:

<input type="button" value="Browse" 
            onClick="openBrowseDialog();">

The JDownload component will send event notifications to a JavaScript function, which is embedded into the same HTML document.

The JavaScript function must have this signature: onJDownloadEvent(EVENT_TYPE, DATA)

Details about the even types and the data can be found in the Appendix chapter.

The events are fired and sent to the JavaScript function on several actions within JDownload, for example when the user clicks Download, or stops the download.

Status updates can be implemented by retrieving event notification messages of the 'progress' type. These events will hold information about the ongoing process, such as percentage, starting time, ending time etc.

Data 0 shows the file being extracted, Data 2 shows the percentage value (91%), Data 3 shows the current (uncompressed) position in the archive (1.4MB) and Data 4 shows the total length of the uncompressed files (1.5MB).

The buttons can be used to remote control the applet. The HTML buttons are disabled within the JavaScript code, to prevent the user from clicking buttons, which do not make sense. (You can't stop a download progress, if no download progress is running)

See Section 3, “JavaScript API Event Types” for details of the event types and their argument data.

This is a sample implementation of the event listener function:

function onJDownloadEvent(EVENT_TYPE, DATA)
{
 // Display the event type as number and descriptive text
JDownloadMessages.EventType.value=EVENT_TYPE;
  var msg = "---";
  var code = parseInt(EVENT_TYPE);
  switch(code)
  {
   case 0: msg = "Detaching listener"; break;
   case 1: msg = "Attaching listener"; break;
   case 2: msg = "Applet initialized"; break;
   case 3: msg = "Applet waiting"; break;
   case 4: msg = "Queue status changed"; break;
   case 5: msg = "Target path changed"; break;
   case 10: msg = "Download starting"; break;
   case 11: msg = "Download in progress"; break;
   case 12: msg = "Download finished"; 
     JDownloadMessages.btnS.disabled='disabled';
     JDownloadMessages.btnD.disabled='';
    break;
   case 13: msg = "Download stopped"; 
     JDownloadMessages.btnS.disabled='disabled';
     JDownloadMessages.btnD.disabled='';
    break;
   case 20: msg = "Download item starting"; break;
   case 21: msg = "Download item in progress"; break;
   case 22: msg = "Download item finished"; break;
   case 23: msg = "Download item stopped"; break;
   case 30: msg = "Uncompress starting"; break;
   case 31: msg = "Uncompress in progress"; break;
   case 32: msg = "Uncompress finished"; break;
   case 33: msg = "Uncompress stopped"; break;
   default: msg = "Unknown event ["+code+"]"; break;
  }
  JDownloadMessages.EventDesc.value=msg;
}

The Look'n'Feel of the components can be changed by using the SkinLF package. To configure this, add the skinlf.jar file to the archive tag of the applet. The theme must be named themepack.zip and reside in the same location as the jdownload.jar file.

JDownload will automatically try to initialize the look and feel classes by SkinLF on startup. If this succeeds, it will try to download the theme and install it. If this fails, the applet will continue normally with the default Java look and feel.

The applet can be internationalized using the included properties file.

To support other languages, follow these steps:

Signing the jar file is necessaray for JDownload to work properly.

Applets are running in a sandbox, a protected environment, which has no access to local file system. JDownload's purpose is to write files to local file system. In order to do the work, it needs access to the local file system. Due to this fact, it must be signed, so it can access the local filesystem.

The signature can be self-signed or trusted by a 3rd party provider. The end-user must accept the certificate (in the security dialog) to let the component access his local file system.

Generating a self-signed test-certificate is easy:

This will sign the application archive (jdownloa.djar) with your generated, self-signed (untrusted) certificate.

To get a real code signing certificate, contact companies like Verisign or Thawte.

The root certificate of the company should be integrated into the target browsers, so users will see that the applet is signed by a trusted party. This increases the acceptance of the tool by the users.

Debugging the JDownload applet should be done within the IDE. This is for developers only. If you need verbose information at runtime, switch on the debug mode in JDownload and open the Java Console.

The Java Console can be found by right-clicking on the Java icon in the System Tray (bottom right of your Windows desktop).

The user interface of JDownload is rather simple. On the left side, you will find an Explorer-like tree with folders and files.

Each folder has an icon to collapse and expand it. Expanding a folder will show it's children - nested subfolders and files. A folder has a name, which directly maps to the folder name which will be created on download.

Each file has a progress bar, a checkbox and a name.

The checkbox is the queueing state of the file. A file can be unchecked and will then not be downloaded. It will just be ignored.

The progress bar shows the percentage done while downloading the file. The current transfer speed (bandwidth in kilobyte per second) is also shown.

While the tool is downloading all the folders and files, the selection will move on to the current downloading item, which will then be surrounded by a red border.

The target folder is preset with the My Files folder on Windows systems, or with the home directory on Linux systems.

The user can change the desired download folder (target folder) by clicking on the Browse button.

This is the XML DTD for the XML Data file used by JDownload.

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT download (folder,file)>
<!ELEMENT file (url)>
<!ATTLIST file
  name NMTOKEN #REQUIRED
  uncompress NMTOKEN #IMPLIED
>
<!ELEMENT folder (file|folder)*>
<!ATTLIST folder name NMTOKEN #REQUIRED>
<!ELEMENT url (#PCDATA)>

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.

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