General view

JUpload is provided with two main server-side samples:

• One for Java. It is actually the root of a webapp, which you can deploy on any J2EE server, like tomcat.
• One for PHP

In either case, this will allow you to:

• Test the applet. During the JUpload development process, I personally use the Java webapp, to actually execute the upload, and check that the upload result is Ok.
• Embed the applet into your own application. The Java sample is more a starting base, which you'll have to extends. The PHP sample, contains both a JUpload class (which you should use 'as is'), and a sample use of this class, which you should adapt, according to your needs.

All samples are available in the core JUpload package, and on the SVN:

• In the package, the path is: ./samples.java and ./samples.PHP
• In SVN, the path is: ./src/site/resources/samples.java and ./src/site/resources/samples.PHP

Use the java sample

With the below configuration, you have a functionnal server side script, which can accept the applet uploads. You'll have to execute the applet from your preferred IDE, like eclipse. In the execution parameters for the applet, you'll have to configure the postURL parameter to the values, as explained below.

The java sample is a sample script: parseRequest.jsp. It manages the uploaded file(s) on server side. It is based on the Jakarta common-files package. Its main capabilities are:

• Reading the uploaded file, and storing of it on the server (local) hard drive. The target path is defined in the ourTempDirectory variable, which default value is /tmp/. To change it, you'll have to update the parseRequest.jsp file : it's defined just at the beginning of the script.
• Concatenation of the chunk, when using the applet chunk mode. Each chunk is stored in the 'ourTempDirectory' path. Then, after receiving the last chunk, all chunk are concatenated, to create the full file back. All chunks remain in the temp folder. This is useful for debug purpose. Please remember, that the chunk parts, should be cleaned when in production.
• Return various information in the upload response. These information can be read in the JUpload debug output. Please see the ./howto-debug.html page.
• Generate an error, to check the applet behavior. You should use the "error=true" parameter on the URL, to force the error generation. The URL could be something like this: http://localhost:8080/jupload/parseRequest.jsp?error=true
• Generate an warning, to check the applet behavior. You should use the "warning=true" parameter on the URL, to force the warning generation. The URL could be something like this: http://localhost:8080/jupload/parseRequest.jsp?error=false&warning=true
• To test the hierarchical view, so that the java sample generates the folders (and not only stores the received file), add the createfolders parameter to true, on the URL. For instance: http://localhost:8080/jupload/parseRequest.jsp?error=false&warning=true&createfolders=true

The java sample is actually an exploded J2EE application. You can use the given content 'as is', with tomcat, by executing these steps:

• Access to the tomcat manager HTML GUI (default: http://localhost:8080/manager/html),
• Go to the Deployer part of it,
• Select /jupload in the context path,
• Select the full path of the sample.java folder, in the URL to WAR file or folder. For instance: H:\data\eclipse\jupload\src\site\resources\samples.java
• Click on the Deploy button
• Check the deployment by using going to the fileupload.html file of this context. For example: http://localhost:8080/jupload/fileupload.html, where 8080 is the port for your tomcat installation (8080 is actually the default one), and /jupload is the path you entered in the context path, here above.

PHP Sample

The PHP sample is available in this folder: ./src/site/resources/samples.PHP. IT is a sample fully functionnal webapp, written in PHP. It consists of three PHP files:

• jupload.php is the main one. It contains a PHP class, which hides all JUpload complexity:
  • It reads the uploaded files, and concatenates the chunk (when the applet is used in chunk mode).
  • The $appletparams contains the parameters to be sent to the applet. Read about the applet parameters here: ./apidocs/wjhk/jupload2/policies/UploadPolicy.html
  • The $classparams contains the various parameter to manage the PHP class itself. They are quite self-explanatory, so I let you read them.
• index.php is the starting one. It contains:
  • The PHP code which uses the jupload PHP class
  • The HTML code which, once sent to the navigator, will display the applet on your web page.
• after_upload.php is a sample of a page which manages the result of the upload.

To test the PHP sample on your local apache (httpd) installation, here are the steps to follow:

• Be sure you properly built the applet (typically by the command mvn clean install site, see the ./howto-compile.html page for all details)
• Open the httpd.conf file.
• Add an alias, and add the relevant rights. For instance :

  Alias /jupload_site "H:\data\eclipse\jupload\target\site"
  <Directory "H:\data\eclipse\jupload\target\site">
          Order deny,allow
          Allow from all
  </Directory>
  

• You can then test the applet, and upload toward these PHP scripts, by using this URL: http://localhost/jupload_site/samples.PHP/

Embed JUpload into your own code

The usual way to embed JUpload is to use it as an applet. But now on, applet support is in danger.

The other way is to start it from a link your navigator, with JNLP technology. This is promised to be available... for ever.

<?xml version="1.0" encoding="utf-8"?> 
<jnlp spec="1.0+" codebase="http://jupload.sourceforge.net/" href="jupload.jnlp">
        <information>
                <title>JUpload</title>
                <vendor>JUpload</vendor>
                <homepage href="http://jupload.sourceforge.net/" />
                <description>
                        JUpload takes care of the limitation posed by traditional HTML upload forms by allowing you to upload a 
                        whole directory and the files within it with a single click. All information is available on the JUpload site.
                </description>
        </information>
        <security>
                <all-permissions/>
        </security>
        <resources>
                <j2se version="1.7+" />
                <jar href="wjhk.jupload.jar" />
        </resources>
         <applet-desc 
         name="JUpload Demo"
         main-class="wjhk.jupload2.JUploadApplet"
         width="640"
         height="400">
        <param name="postURL" value="upload_dummy.html" />
        <!-- Add all your JUpload applet params here -->
     </applet-desc>
</jnlp>

The data sent by the applet during an upload

Here is a description of the data sent by the applet.

Please note that the following parameters can change the default behavior (see UploadPolicy javadoc page for details):

• formdata allows to sent the content of a form altogether with the uploaded files.
• httpUploadParameterName: the parameter name, where to receive the files themselves.
• httpUploadParameterType indicates whether the data is sent as many parameters or some arrays. See the UploadPolicy javadoc page for details.

The applet send these data, for each uploaded file:

• mimetype: The mime type for the file. On windows, this file type is guessed from the file type. On other systems, the mime type is application/octet-stream.
• pathinfo: The absolute path for this file, on the local file system.
• relpathinfo: The relative path for this file, in the current upload. This path can be calculated in two ways, depending on the fileListViewMode applet parameter:
  • When fileListViewMode is flat or tree_view mode: the common root for all uploaded files is calculated. The relpathinfo then contains the path relative to this common root. The common root is the 'highest' folder, common to all files. For instance, if the user first add the /users/a/f/file1 and /users/a/f/file2 files (by dragging the f folder on the applet), then /users/b/file3 (by draging the b folder on the applet):
    • When the user adds /users/a/f/file1 and /users/a/f/file2, the root is /users/a/f. The relative path is an empty path. In tree_view mode, no folder is displayed, as all files are in the root folder.
    • Then the user drags the /users/b/file3 file on the applet. The common root becomes /users. In tree_view mode, the displayed items on the file lists are displayed below. The relpathinfo sent are: a/f (for file1), a/f (for file2) and b (for file3).

            a
                    f
                            file1
                            file2
            b
                    file3
    

  • When fileListViewMode is independent_tree_view mode: each added file or folder is added to the root of the upload. So, from the previous sample, if the user drags f (which contains file1 and file 2) and b (which contains file3), f and b are directly attached to the root the uploaded structure is the one displayed below, and the relpathinfo sent are: f (for file1), f (for file2) and b (for file3). There is no calculation for a common root. The information is directly taken from the added files.

          f
                  file1
                  file2
          b
                  file3
  

• filemodificationdate: the last modification date for this file.
• File: The file data itself. This data can be managed by any web tool. It is sent using the Web standards. You have samples in PHP and in Java, on how to manage them. But you can manage it by any tool you're already using to receive post uploads.

Note: only the file are sent. Folders are not sent. This means:

• If you want to store a file in the relevant folder on the server, you'll have to create the intermediate folders in your server scripts. In Java, mkdirs does it for you.
• An empty folder won't be sent at all. That is, to be precise: no data about it will be received.
• Any folder, with no uploaded file in its descendant, won't be sent. Same reason as above.