readme.txt

jupload applet 0.63

--------------
JUpload applet
==============

  What is JUPLOAD?
  ----------------

   JUpload is a replacement for file upload tags in html. It will upload
   multiple files to the webserver using RFC1867 and the HTTP POST method.
   Recursion is available and HTTPS and PROXY is supported, an image preview
   and status display completes the standard features.


Author:
=======
   Mike Haller
   [e-mail]
   http://www.haller-systemservice.net/jupload/

   If you have any questions, ask them by mail.
   If you have any ideas, improvements etc. send them by mail. :-)
   Please use the word "jupload" in the subject line.



Quick Installation:
===================
   1) unzip JUpload.zip into a new directory under your document_root
   2) edit JUpload.html and insert your domain name in the applet code tags !!!IMPORTANT!!!
   3) edit JUpload.php and modify it to fit your needs
   4) start your browser and point it to the url representing your directory
      e.g. directory was /web/htdocs/jupload/
      point browser to http://localhost/jupload/JUpload.html


Hints
=====
   a) check that _all_ needed files are in the directory. minimal needed files:
       - JUpload.html (can be renamed to index.html)
       - JUpload.php (this is the server side part)
       - JUpload.jar (this is the main application) *IMPORTANT* :)
   b) check that the upload directory, mentioned in JUpload.php
      does exist and is writable for the webserver.
   c) check that you have implemented the file copy function in
      JUpload.php. it is preconfigured to save the files in the
      temp/ directory where you have installed JUpload





Available Parameters
====================

Java Plug-In Parameters (do not work in IE):
============================================
  <param name="progressbar" value="true"> Show a progress bar
  <param name="boxmessage" value="Loading JUpload Applet ..."> Sets the loading text
  <param name="boxbgcolor" value="#e0e0ff"> Sets the background color of the applet box

JUpload settings
================
 General: boolean types can have the values on,off,true,false,0,1,yes,no

 

            ***** THIS IS THE MOST IMPORTANT PARAMETER *****

 where to send the files? defaults to the JUpload.php.
 can be http:// or https:// (Secure HTTP, HTTPS, SSL)
 this must be an absolute URI as you type it in the address field of your browser
 the URL can have a query string which is forwarded to the script.

  <PARAM NAME="actionURL" VALUE="https://localhost/jupload/demo/JUpload.php">
  <!-- Type is absolute URL (not relative! must have protocol, hostname and path -->

            ***** THIS IS THE MOST IMPORTANT PARAMETER *****



 Set background color
  <PARAM NAME="backgroundColor" VALUE="#e0e0e0">
  <!-- Type is String -->

 where to go after upload is finished? leave blank to do nothing. 
 can be any URL which is handled by the browser (http, https, ftps, file, telnet, ed2k...)
 this must be an absolute URI as you type it in the address field of your browser
  <PARAM NAME="completeURL" VALUE="https://localhost/jupload/demo/JUploadComplete.html">
  <!-- Type is URL -->

 switch on to ask user for username and password for WWW-Authentification.
 if you have protected the actionURL with a .htaccess file, set this to on
  <PARAM NAME="askAuthentification" VALUE="false">
  <!-- Type is Boolean -->

 what tag name shall be used for the mime attachements? this defaults to
 'uploadedFiles'. each part will have a counter added
 the first file will be called 'uploadedFiles0', the second 'uploadedFiles1' and so on
  <PARAM NAME="tagName" VALUE="uploadedFiles">
  <!-- Type is String -->

 if JUpload should take care of what the webserver tells us after upload,
 switch this on.
  <PARAM NAME="checkResponse" VALUE="true">
  <!-- Type is Boolean -->

 if the user should be told that his upload was successfull, switch this on
  <PARAM NAME="showSuccessDialog" VALUE="true">
  <!-- Type is Boolean -->

 this is the size one request can be at maximum. if the upload size is higher than
 this number, the upload is split into multiple requests. this also mans that a
 file which is larger than this number can't be uploaded. this should be set to
 the same amount as the "upload_max_filesize" in php.ini. the unit is bytes.
 NOTE: switch off with -1
  <PARAM NAME="maxTotalRequestSize" VALUE="2000000">
  <PARAM NAME="maxTotalRequestSizeTitle" VALUE="File too large">
  <PARAM NAME="maxTotalRequestSizeWarning" VALUE="File too large for upload">
  <!-- Type is Long -->


 this switch sets a server space or a user account size. if a file or
 the upload is bigger than this, it's not allowed to add files.
 NOTE: switch off with -1
  <PARAM NAME="maxFreeSpaceOnServer" VALUE="-1">
  <PARAM NAME="maxFreeSpaceOnServerWarning VALUE="File is too large for server">
  <PARAM NAME="maxFreeSpaceOnServerTitle" VALUE="File too large">
                                          

 if you want to only allow images to be shown in the filechooser dialog, switch
 this on. Note that if a user selects a directory, all files will be recursively
 added to the upload queue, no matter what type they are.
  <PARAM NAME="imageFileFilter" VALUE="false">
  <!-- Type is Boolean -->

 in the add-files dialog, there is a file type selector. if you switch on
 imageFileFilter, this shown "All files" and "Images only". you can switch off
 the possibility for "All files" with this switch
  <PARAM NAME="hideShowAll" VALUE="false">
  <!-- Type is Boolean -->

 if you want to have a neat image preview in the filechooser, 
  <PARAM NAME="showPicturePreview" VALUE="true">
  <!-- Type is Boolean -->

 if you want to customize the title of your Add-Files window
  <PARAM NAME="addWindowTitle" VALUE="Add files">
  <!-- Type is String -->

 if you want to have a logo in the lower right corner, give the name of
 a picture file. this is relative to the location of the jar file. so
 if your logo resides in the same directory, just type in the filename
 e.g. "logo.gif". do not enter an URL like "http://www...."
  <PARAM NAME="imageURL" VALUE="jupload.gif">
  <!-- Type is String (no absolute URL) -->

 customize the label "Files:" (amount of files in the queue)
 and/or the label "Bytes:" (amount of bytes in the queue)
 and/or the three buttons for Adding, Removing and start Uploading files
  <PARAM NAME="labelFiles" VALUE="Files:"><!-- Type is String -->
  <PARAM NAME="labelBytes" VALUE="Bytes:"><!-- Type is String -->
  <PARAM NAME="labelAdd" VALUE="Add"><!-- Type is String -->
  <PARAM NAME="labelRemove" VALUE="Remove"><!-- Type is String -->
  <PARAM NAME="labelUpload" VALUE="Upload"><!-- Type is String -->

 customize the messages shown on successfull uploads
 see parameter "showSuccessDialog"
  <PARAM NAME="successDialogMessage" VALUE="Upload was reported to be successfull."><!-- Type is String -->
  <PARAM NAME="successDialogTitle" VALUE="Upload successfull"><!-- Type is String -->

 customize the tooltip help for the buttons if the user moves his mouse
 over one of the buttons and waits a few seconds. (aka bubble help)
  <PARAM NAME="addToolTip" VALUE="Press to open file chooser to add files to upload queue"><!-- Type is String -->
  <PARAM NAME="removeToolTip" VALUE="Select files in queue and click this button to remove them from queue"><!-- Type is String -->
  <PARAM NAME="uploadToolTip" VALUE="Press to start uploading the files in the queue to the configured webserver"><!-- Type is String -->

 special feature of jupload. switch this on and read the extra section 
 about "The RecursivePaths Feature" below
  <PARAM NAME="useRecursivePaths" VALUE="false"><!-- Type is Boolean -->

 switch off debug messages by settings this to false
  <PARAM NAME="debug" VALUE="true"><!-- Type is Boolean -->

 switch of the check for correct java version.
 the gotourl parameter will be opened in a new browser window if the check fails.
  <PARAM NAME="checkJavaVersion" VALUE="false"><!-- Type is Boolean -->
  <PARAM NAME="checkJavaVersionGotoURL" VALUE="http://java.sun.com/j2se/downloads.html"><!-- Type is URL -->

 send a cookie to the browser. you have to use JavaScript to write document.cookie into
 this parameter field.
  <PARAM NAME="browserCookie" VALUE="..."><!-- Type is String -->

 if you want to change the starting default directory of the add file dialog:
  <PARAM NAME="defaultAddDirectory" VALUE="c:/temp"><!-- Type is String -->

 if you want to enable resuming (aborted uploads will start where they have been
  stopped, so you don't loose the data you already uploaded)
 NOTE: this must be enabled on the Server-Side, too: you need a special PUT handler.
 In this method, only the host of actionURL is used, since JUpload does not yet support
 multiple instances on one virtual server (e.g. in different locations / folders)
 Since this method is in beta-phase, the only path usable is /temp/
 IMPORTANT: set "cgi.fix_pathinfo=1" in php.ini if you are using CGI version of php !!!
  <PARAM NAME="usePutMethod" VALUE="true"><!-- Type is Boolean -->

 Switch on and descripe your custom file filter with these settings.
 In "customFileFilterExtensions" there is a comma-separated list of
 file extensions
  <PARAM NAME="customFileFilter" VALUE="true"><!-- Type is Boolean -->
  <PARAM NAME="customFileFilterDescription" VALUE="Images">
  <PARAM NAME="customFileFilterExtensions" "gif,jpeg,jpg,png,bmp,tif">

 With these parameters, you can limit the maximum number of files which
 can be uploaded with JUpload. (Disable with value "-1")
 And customize your warning message here.
  <PARAM NAME="maxNumberFiles" VALUE="100">
  <PARAM NAME="maxNumberFilesWarning" VALUE="Maximum number of files reached.">
  <PARAM NAME="maxNumberFilesTitle" VALUE="Filelimit reached">


 If you are using Jakarta Tomcat webserver and the jakarta-fileupload package,
 you should switch this to "true"
 NOTE: fileupload wants to habe "multipart/mixed" with file uploads, php and others
 want to have "multipart/form-data"
  <PARAM NAME="fixJakartaBug" VALUE="true">


The RecursivePaths Feature
==========================
 If you switch on the "useRecursivePaths" parameter, JUpload will store relative
 pathnames and send them together with the filedata to the webserver. Normally,
 the http protocol (or to be more specific: rfc1867) has no possibility to
 upload recursively, so all files won't have any path information.
 One solution to this would be to pack all files into a tar or zip, send them up
 to the server and unpack them again.
 The other solution is supported by JUpload. You will need to have a modified
 version of JUpload.php.
 But at first, i will tell you what JUpload will do with this option turned on:
 it will encode the relative path (explained below) into the content-type header.
 the server-side script will receive the content-type and can decode the path
 information and use it to store the file in a relative path in the upload/temp
 directory.
 The path is base64 encoded: "Content-Type: JUpload/Fgjfg73dfhdlkj3jfdklsdfu4="
 "JUpload/" is an identifier and the rest "Fgjfg.." is the base64 encoded path info.
 Relative path: 
 (your filedialog is currently in /home/mike/, you select "work" and click "Add files")

  /home/mike/work/work10.txt
  /home/mike/work/old/work05.txt
  /home/mike/work/backup/work02.txt

 Uploading the common way will result in this on the server:

  work10.txt
  work05.txt
  work02.txt

 Uploading with "useRecursivePaths" will result in the following:

  work/work10.txt
  work/old/work05.txt
  work/backup/work02.txt

 Now, the webserver has relative path information on the files.

 Note: but he will loose any data about the content-type.
 But this is not as bad as it sounds since the content-type can be
 figured out by the file extension in most of the cases.

 Note: this featuer is not tested very well, so there is no guarantee
 that it works for you. especially the lengths or deepness of directory
 paths is not tested.





Advanced Installation
=====================
Your own test certification (basic steps)

   (if you tried this whole thing before, use
     "%JAVA%/bin/keytool -delete -alias jupload"
    to delete your old test key)

   1) run

          "%JAVA%/bin/keytool -genkey -keyalg rsa -alias jupload"

      choose your password. he will then ask a lot of questions, answer them correctly.
      he will now create a key, this will take some time
      he will ask for a passphrase. you can enter a passphrase or hit return to choose
      the same passphrase as your password.
 
      (to automate part of this, use option "-dname")

   3) create your own .jar file

          "%JAVA%/bin/jar cvf JUpload.jar JUpload/*.class"

   4) test your .jar file
       (this is an example, the real output looks a bit different, other files..)

          "%JAVA%/bin/jar tvf JUpload.jar"

          0 Mon Jul 07 17:39:34 CEST 2003 META-INF/
         73 Mon Jul 07 17:39:34 CEST 2003 META-INF/MANIFEST.MF
       5417 Thu Jun 19 22:55:12 CEST 2003 JUpload/JUpload.class
       9470 Thu Jun 19 22:55:12 CEST 2003 JUpload/MimeHeader.class
       2234 Thu Jun 19 22:55:12 CEST 2003 JUpload/myAddListener.class
       2051 Thu Jun 19 22:55:12 CEST 2003 JUpload/myRemoveListener.class
       7336 Thu Jun 19 22:55:12 CEST 2003 JUpload/myUploadListener.class
       3626 Thu Jun 19 22:55:12 CEST 2003 JUpload/startup.class
       1952 Thu Jun 19 22:55:12 CEST 2003 JUpload/UploadStatusFrame.class

   5) sign the jar file with your own certificate with

          "%JAVA%/bin/jarsigner JUpload.jar jupload

       (Attention: jarsigner does not work with unicode class names)





Credits
=======
for Support, beta-testing, bug-reports and more

	Yvon Quere, France
	[e-mail]



About
=====

   JUpload started as a proof-of-concept prototype for uploading multiple
   files (RFC1867) with the HTTP POST method using java applet technology
   and especially the jarsigner utility. As it turned out that JUpload
   was a much-needed tool, development started and implementation proresses
   as new features have to be coded and bugfixes be integrated.

   Mike Haller
   [e-mail]
   http://www.haller-systemservice.net/jupload/

   If you have any questions, ask them by mail.
   If you have any ideas, improvements etc. send them by mail. :-)
   Please use the word "jupload" in the subject line.