How to customize this applet ?

Content of this page

  • Main Choices
  • Basic HTML configuration
  • Using another existing UploadPolicy
  • Creating a new UploadPolicy
  • List of available parameters
  • Links
  • Main choices

    You can customize the behavour of this applet by using one (or more) of the following ways (from the simplest to the most complex):

    Basic HTML Customization

    A first level of customization is available by using the DefaultUploadPolicy (that is, not provide any uploadPolicy applet parameter), and use parameters available within the DefaultUploadPolicy, without any Java coding: these parameters are provided in HTML, within the APPLET tag that creates this applet. These parameters are described below . As there is no uploadPolicy parameter, you can only use the parameters that are implemented in the DefaultUploadPolicy. See the column 'Implemented in' in the parameter list, hereafter .
    The main customizations available by applet parameters are listed here:
  • Control of the target URL (where files should be uploaded).
  • Choose of an upload policy, among the available policies (see all classes that inherit from DefaultUploadPolicy
  • Log information level, with debugLevel.
  • Language control, that can be specific for the HTML page.
  • A URL where all debug information can/should be sent when an error occurs (see urlToSendErrorTo).
  • Number of files to be put in one HTTP Request (see nbFilesPerRequest)
  • A string to control that upload is a success (see stringUploadSuccess)
  • For pictures only: A maximum width and/or height (see maxPicHeight and maxPicWidth)
  • Using another existing UploadPolicy

    By providing the uploadPolicy parameter within the APPLET tag, you can select another class that implements the UploadPolicy interface. The current implemented upload policies are :

    Customization by creating a new Java Upload Policy (simple java coding)

    All details on the policies package summary.

    If these customization possibilities are not enough, you can create a new upload policy. To do this, you need to create a new java class: the easiest way is to inherit from DefaultUploadPolicy. You can then override methods of the UploadPolicy interface.

    This kind of customization will be compatible within next JUpload applet release. If you need other hooks (method within the UploadPolicy interface, to allow other customizations), please let me know by posting a message on the sourceforge jupload forums (open discussions for instance), or post a new Feature Request in the jupload sourceforge project page.

    Here is a description of the customization that you can do by using the creating a new policy, using the UploadPolicy interface:

    Customization by creating a new Java FileData

    All details on the new FileData howto page.

    This allows you to change the file relative behaviour. You can for instance add data compression, preload check, new data about files in the upload to the server..

    Parameters

    Here is the list of all parameters available in the current package, that is: available in available upload policies. These are applet parameters that should be 'given' to the applet, with tags, as precised below in the example.

    Parameter name Default value /
    Implemented in
    Description
    afterUploadTarget
    Since 2.9.2rc4
    _self

    DefaultUploadPolicy
    This parameter allows to select a specific target frame when redirecting to afterUploadURL. The following values are possible:
    • _self - Show in the window and frame that contain the applet.
    • _parent - Show in the applet's parent frame. If the applet's frame has no parent frame, acts the same as _self.
    • _top - Show in the top-level frame of the applet's window. If the applet's frame is the top-level frame, acts the same as _self.
    • _blank - Show in a new, unnamed top-level window.
    • name - Show in the frame or window named name. If a target named name does not already exist, a new top-level window with the specified name is created, and the document is shown there.
    See also: AppletContext.showDocument(java.net.URL, java.lang.String)
    afterUploadURL null
    since 2.9.0
    DefaultUploadPolicy
    This parameter is used by all policies. It allows the applet to change the current page to another one after a successful upload.
    This allows, for instance, to display a page containing the file description of the newly uploaded page. Since version 3.0.2b2, you can specify a JavaScript expression instead of a plain URL. So afterUploadURL can now contain:
    • A javascript expression: The URL must start by javascript:. See below for details.
    • A http URL: the navigator will open this URL, in the current page or another, according to the afterUploadTarget parameter. Any URL that doesn't start by javascript: is handled as an http URL.
    If the value of afterUploadURL starts with the string "javascript:", the remainder of the string is evaluated as JavaScript expression in the current document context. For example: If afterUloadURL is
    "javascript:alert('Thanks for the upload');",
    then after a successful upload, a messagebox would pop up. Since 3.0.2b3 there are now three placeholders available which can be used as parameters in function calls:
    • %success% is replaced by true or false depending on upload success.
    • %msg% is replaced by an unquoted string, containing the error message received from the server (if any). Inside that string, all occurances of the single-quote character (hex 27) are quoted by backslashes.
    • %body% is replaced by an unquoted string, containing the complete response body. Inside that string, all occurances of the single-quote character (hex 27) are quoted by backslashes.
    So if you set afterUloadURL to "alert('%body%');", then the resulting message box would show the body content of the last server response.
    albumId -1

    CoppermineUploadPolicy
    This parameter is only used by CoppermineUploadPolicy. So it is to be used to upload into a coppermine picture gallery. This parameter contains the identifier of the album, where pictures should be used. See CoppermineUploadPolicy for an example.
    Before upload, CoppermineUploadPolicy.CoppermineUploadPolicy.isUploadReady() checks that the albumId is correct, that is: >=1.
    allowedFileExtensions empty string
    since 2.9.0
    DefaultUploadPolicy
    This parameter allows the caller to specify a list of file extension. If this parameter is specified, only file with this extension can be selected in the applet.
    This parameter must contains a list of extensions, in lower case, separated by slashes. eg: jpg/jpeg/gif
    allowHttpPersistent true
    since 3.0.0rc1
    DefaultUploadPolicy
    This parameter allows to switch off persistent HTTP connections which are enabled by default (and the protocol version allows it). Currently, we encountered problems with persistent connections when testing on a windows box using a loopback interface only.
    debugLevel 0

    DefaultUploadPolicy
    With 0, you get the normal production output. The higher the number is, the more information is displayed in the log window.
    Note: All debug messages are stored in a temporary log file. This can be used to display more information, if needed. See also the urlToSendErrorTo applet parameter.
    fileChooserIconFromFileContent 0
    since 3.1.0b
    UploadPolicy
    This parameter allows to control whether the file icons in the file chooser are calculated from the file content. This is currently only available for pictures.
    If activated, the file chooser will open each pictures, and calculate the icon by resizing the picture. This is done in by using thread of minimam priority, to minimize performances impact on the navigator. Available values are:
  • -1: disabled. The default system are used.
  • 0 (default): available only in picture mode. That is: the current upload policy is an instance of or a class inheriting from PictureUploadPolicy
  • 1: available for all upload policies.
  • fileChooserIconSize 20
    since 3.1.0b
    UploadPolicy
    This parameter allows to control the size of icons, in pixels, in the file chooser. Used only when fileChooserIconFromFileContent is activated.
    Note: The standard icon size is a value of 20. With 50, you'll get a better view of the picture.
    fileChooserImagePreview true
    since 3.1.0b
    PictureUploadPolicy
    This parameter allows to control whether an preview is available for picture in the file chooser. If activated, the file chooser will open the preview in a separate thread, of high priority. This avoid blocking the applet while calculating the preview picture, when the user just double-clicked a picture file. This parameter is ignored for DefaultUploadPolicy.
    filenameEncoding null

    DefaultUploadPolicy
    Since 3.3.0, this parameter is no more used. The full applet upload HTTP request to the server is now correctly encoded.
    With null, the filename in the Content-Disposition header is not encoded. If not null, the applet tries to encode this filename with the given encoding. It's up to the receiver (the web site) to decode this encoding (see getUploadFilename(FileData, int).
    Example: if the "UTF8" encoding is choosen, the PHP function urldecode can be used to decode the filename.
    formdata null

    DefaultUploadPolicy
    Since 2.9.2rc4
    With this parameter, the name of a HTML form can be specified. If the specified form exists in the same document like the applet, all all form-variables are added as POST parameters to the applet's POST request.
    highQualityPreview false

    DefaultUploadPolicy
    If this parameter is set to true, the applet will call the BufferedImage.getScaledInstance(), instead of doing a basic scale transformation. This consume more CPU: on a PII 500MHz, the full screen go from around 5 seconds to between 12 and 20 seconds, for a picture created by my EOS20D (8,5M pixels). The standard preview (above the file list) seem to be displayed at the same speed, whatever is the value of this parameter.
    Note: when resizing is done before upload, the BufferedImage.getScaledInstance() is always called, so that the uploaded picture is of the best available quality.
    lang Navigator language

    DefaultUploadPolicy
    Should be something like en, fr... Currently only french and english are known from the applet. If anyone want to add another language ... Please translate the wjhk.jupload2.lang.lang_en, and send it back to .
    lookAndFeel
    since 2.5
    empty

    DefaultUploadPolicy
    This allows to control the look & feel of the applet. The authorized values are:
    • empty: uses the default look & feel. This is the same as java.
    • java: uses the java default look & feel. Same as empty.
    • system: uses the current system look and feel. The call will be :
      UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
    • Any valid String argument for UIManager.setLookAndFeel(String).
    maxChunkSize
    Since 2.7.1
    0
    Long.MAX_VALUE

    DefaultUploadPolicy
    This parameters defines the maximum size of an upload.
    • If not set, or set to a value of 0 or less, the chunk mode is disabled. That is: each file will be uploaded within being splitted in pieces.
    • If set to a value of 1 or more, the upload size will be never be more than maxChunkSize. A file bigger will be split in several part of maxChunkSize size, then the last part will contain the remaining, and will probably be smaller than maxChunkSize.

    How to build the server part: the server will have to 'guess' that the file is splitted, and then it will have to reconstruct the uploaded file. Here are the necessary informations:
    • When a file is chunked, the jupart and jufinal parameter are given in the URL (get parameters). This identify a chunk upload. If these parameters are not given, the file(s) is(are) uploaded in one piece.
    • jupart identify the part number: from 1 to N for a file being plitted in N pieces. The N-1 chunks should be maxChunkSize bytes long. The last one contains the remaining of the file.
    • jufinal is set to 0 for chunks from 1 to N-1. It is is set to 1 only for the last chunk (N, in this 'example').
    • The uploaded filename is not modified when the upload is chunked. Example: upload of the file bigPicture.jpeg, of 4,5 Mb, with chunk of 2Mb. The upload is splitted in three chunk. Chunk 1 and 2 are 2Mb long. The third one is 0,5Mb long. The uploaded filename for these three uploads is bigPicture.jpeg. It's up to the server part to read the jupart and jufinal get parameters, to understand that the upload is chunked.
    • Important: The server script must check the resulting filesize. If not, the client can send a file of any size, and fill the server hard drive.
    • The wwwroot/pages/parseRequest.jsp is a java example of a server page that can receive chunk upload. It stores each chunk is filename.partN (where N is the chunk number), then construct the final file, by concatenating all parts together.
    Note: If nbFilesPerRequest is different than 1, the applet will try to upload the files until the sum of their content length is less than maxChunkSize. The upload is triggered just before the sum of their content length is bigger then maxChunkSize.
    If one file is bigger than maxChunkSize, all previous files are uploaded (at once or not, depending on nbFilesPerRequest). Then the 'big' file is uploaded alone, splitted in chunk. Then upload goes on, file by file or not, depending on nbFilesPerRequest.
    maxFileSize
    Since 2.7.1
    0
    Long.MAX_VALUE

    DefaultUploadPolicy
    This parameter identify the maximum size that an uploaded file may have. It prevent the user to upload too big files. It is especially important when chunk upload is activated (see below maxChunkSize).
    • If maxChunkSize is not set, negative or 0, maxFileSize should be the maximum upload size of the server. In this case, it is useful only to display a message when the user select a file that will be refused by the server.
    • If chunk upload is activated, this parameter becomes really important: in this case the maximum file size of an uploaded file is ... the available space on the server hard drive! (see below, maxChunkSize).
    maxPicHeight Since 3.3.0: Integer.MAX_VALUE
    (was -1)

    PictureUploadPolicy
    This parameters allows the HTML page to control the maximum height for pictures. If a picture is to be download, and its height is bigger, the picture will be resized. The proportion between width and height of the resized picture are the same as those of the original picture. If both maxPicHeight and maxPicWidth are given, it can happen that the resized picture has a height lesser than maxPicHeight, so that width is no more than maxPicWidth.
    Precisions:
    If this parameter value is negative, then no control is done on the picture height.
    If the original picture is smaller than the maximum size, the picture is not enlarged.
    If the picture is resized, its other characteristics are kept (number of colors, ColorModel...). The picture format is ketp, if targetPictureFormat is empty. If the picture format is a destructive (like jpeg), the maximum available quality is choosed.
    See also maxPicWidth, realMaxPicHeight
    maxPicWidth Since 3.3.0: Integer.MAX_VALUE
    (was -1)

    PictureUploadPolicy
    Same as maxPicHeight, but for the maximum width of the uploaded picture.
    See also maxPicHeight, realMaxPicWidth
    nbFilesPerRequest -1

    DefaultUploadPolicy
    This allows the control of the maximal number of files that are uploaded in one HTTP upload to the server.
    If set to -1, there is no maximum. This means that all files are uploaded in the same HTTP request.
    If set to 5, for instance, and there are 6 files to upload, there will be two HTTP upload request to the server : 5 files in the first one, and that last file in a second HTTP request.
    pictureCompressionQuality 0.8
    since 3.1.0
    PictureUploadPolicy
    This parameter controls the picture compression quality, when writing the picture file. 1 means high quality picture, but big files. 0 means poor quality pictures, but small files. 0.8 is a good compromise for the web.
    It is different from the highQualityPreview, which controls the way picture are resized in memory.
    This parameter is currently applied only to jpg (and jpeg) pictures.
    pictureTransmitMetadata false since 3.3.0
    (was true before)

    since 3.2.0
    PictureUploadPolicy
    This parameter controls whether the applet transmit metadata of the original picture. This may prevent personal information to be thrown on the net.
    Note 1: This parameter is especially important for picture coming from the Canon EOS 20D, 30D and 40D: pictures shooted in portrait mode contain metadata that are incompatible with Java 1.6.0_3! The colors of transformed pictures become strange... Since 3.3.0: default to false, to avoid this annonying (and currently not explained) problem.
    Note 2: As of 3.2.0, this parameter blocks metadata only for pictures that are updated by the applet. Metadata from picture transmitted 'as is' are not removed. This is corrected in 3.3.0.
    postURL null since 1.9.2rc4, (was Mandatory before)

    DefaultUploadPolicy
    This parameter specifies the target URL toward which the files should be uploaded. Since version 1.9.2rc4 this parameter is not mandatory anymore. Instead, if omitted or a relative URL is given, the resulting URL is constructed from the applet's DocumentBaseURL. This means, that if the applet tag is dynamically constructed from a PHP script without specifying postURL, the same same script receives the subsequent POST request(s). If this URL may change during the applet execution time, you can call the setProperty applet method from javascript, or create a new UploadPolicy class and either : Note 1: in HTTP, the upload is done in the same user session, as the applet uses the cookies from the navigator. This allows right management during upload, on the server side.
    Note 2: FTP URL should looks like: ftp://username:password@myhost.com:21/directory
    Note 3: in FTP, you'll have to add the jakarta-commons-oro.jar and jakarta-commons-net.jar jar files in the applet ARCHIVE tag attribute. See the 'advanced_js_demo.html page for a sample. You'll have to put the two files coming from the JUpload distribution in the same directory as the wjhk.jupload.jar.
    realMaxPicHeight Since 3.3.0: Integer.MAX_VALUE
    (was -1)

    PictureUploadPolicy
    Since v2.8.1
    This parameters is about the same as maxPicHeight. It overrides it for pictures that must be transformed (currentlty only when the picture is rotated).
    The aim of this parameter, is to prevent the applet to resize picture, and let the server do it: it will be much quicker.
    This allows you to:
    • Put a 'big' maxPicHeight (or don't provide the parameter in the APPLET tag), and let the server resize the picture according to the real maxPicHeight. The maxPicHeight will be used when the picture is not tranformed by the user.
    • Put this realMaxHeight to the real configured maxPicHeight. The applet will then directly produce the final file, when it has to tranform the picture (picture rotation, for instance).

    See also maxPicHeight, realMaxPicWidth, maxChunkSize (to override any server upload size limitation).
    realMaxPicWidth Since 3.3.0: Integer.MAX_VALUE
    (was -1)

    PictureUploadPolicy
    Since v2.8.1
    Same as realMaxPicHeight, but for the maximum width of uploaded picture that must be transformed.
    See also maxPicWidth, realMaxPicHeight
    serverProtocol null since 2.9.2rc4
    (before: "HTTP/1.1")

    DefaultUploadPolicy
    This parameter allows the control of the protocol toward the server. It can be HTTP/0.9 (not tested), HTTP/1.0, HTTP/1.1 and FTP. HTTP supports https. Since version 2.9.2rc4, the default is null, introducing a new facility of automatically adjusting the protocol according to the server response.
    This parameter is really useful only in CoppermineUploadPolicy, as the coppermine application also controls that the requests send within an HTTP session uses the same HTTP protocol (as a protection to limit the 'steal' of session cookies).
    showLogWindow
    Since 3.0.2
    True

    DefaultUploadPolicy
    This parameter was formerly known as showStatusBar which now has a different purpose. If given with the False value, the log window will be hidden. The applet will still store all debug information in it. But the user won't see it any more. If a problem occurs, the urlToSendErrorTo can still be used to log all available information.
    showStatusBar True

    New meaning since 3.0.2
    DefaultUploadPolicy
    This parameter controls if the status bar is shown in the applet. If shown, the stausbar provides information about the current transfer speed and estimated time of completion. Before version 3.0.2, this parameter was used to control visibility of the log window. This is now controlled by showLogWindow.
    specificHeaders null

    Since 3.0.2
    DefaultUploadPolicy
    Allows the caller to add any header(s) to the applet. These headers will be sent with each HTTP request to the server. If you put several lines in this parameter, these parameter should be separated by the "n" strings (not the n character, but the character followed by the n character). No "n" at the end: it will be added by the applet.
    This allows an easy management of Basic HTTP authentication. Just add a header like this one:
    Authorization: Basic Base64EncodedString Where Base64EncodedString is the string "login:passord" encoded in Base 64.
    sslVerifyCert
    Since 3.0.2b1
    none
    DefaultUploadPolicy
    With this parameter, the handling of certificates when using SSL can be configured. There are 4 possible settings:
    • none (default): Any server cert is accepted, no cert-based client authentication is performed.
    • server: The server cert is verified against the local truststore and if that fails, a dialog pops up which asks the user if the certificate shall be accepted permanently, just for the current session or not at all (Just like any browser would do).
    • client: A user-certificate (which must be available in the local keystore) is used to perform client authentication.
    • strict: The combination of client and server.

    The location of the local truststore and keystore uses the normal JRE conventions. This means, that the system truststore is used for verifying server certs (usually in $JAVA_HOME/lib/security/cacerts) unless either the system property javax.net.ssl.trusStore specifies another location or a file .truststore exists in the user's home directory. If the user decides to permanently accept an untrusted certificate, the file .truststore in the user's home directory is written. The default keystore (for client certificates) is the file .keystore in the user's home directory. This can be overridden by setting the system property javax.net.ssl.keyStore. If the name of the keystore ends in .p12, it is assumed that the keystore is in PKCS12 format, otherwise the default format as specified in the JRE security-configuration is used.

    Important Note about client authentication:

    At the time of this writing, a serious bug exists in apache 2.0.x which prevents POST requests when SSL renegotiation is about to happen. Renegotiation is triggered by a location-based (or directory-based) change of the SSLVerifyClient directive in apache. Therefore you can not protect a sub-area of an otherwise unprotected SSL server. You can circumvent that by setting up a virtualhost which is configured to perform SSL client verification for the complete virtualhost. Attached to the bug report at ASF Bugzilla, there are several patches which claim to fix the problem. However in that same report, other users complain about those patches to be ineffective. Therefore, the author recommends avoiding re-negotiation alltogether by using the virtualhost aproach described above. It is the understanding of the author, that this bug has been fixed for apache 2.2, however the author did not verify that. Test-Reports from users running apache 2.2 are welcome.

    storeBufferedImage false
    Deprecated
    PictureUploadPolicy
    This parameter indicates that the preview image on the applet is kept in memory. It works really nice under eclise. But, once in the navigator, the applet runs very quickly out of memory. So I add a lot of calls to PictureFileData.freeMemory(String), but it doesn't change anything. Be careful to this parameter, and let it to the default value, unless you've well tested it under all your target client configurations.
    This parameter will probably never be correctly implemented.
    stringUploadError Since 3.2.0: "^ERROR: (.*)$" for all upload policies
    Empty string ("") [if using DefaultUploadPolicy]
    "ERROR: (.*)" [if using CopperminUploadPolicy]

    DefaultUploadPolicy
    Since 2.9.2rc4
    This string is a regular expression. It allows the applet to test that the server has detected an error in the upload. If this parameter is given to the applet, the upload thread will try to match this regular expression against each line of the server response body. If a group is found, it is considered as the error message, and will be displayed to the user.
    If the match is successfull once, the upload is considered to have failed. and JUploadExceptionUploadFailed is thrown. If the expression contains a hunt-group, the matching contents of that group is reported to the user. For example: If let the default value "^ERROR: (.*)$" here, the applet will find an error if at least one line returned in the server response begins with "ERROR: ". Then, all characters that follow are extracted as the error message. So, if the server response contains the line "ERROR: md5sum check failed", the string "md5sum check failed" is used for the exception message. But if it returns a line "maybe ERROR: is it an error?", then the applet won't find any error in the server response.
    stringUploadSuccess "^SUCCESS$"
    empty string ("") since 2.9.0
    (was ".* 200 OK$" before)

    DefaultUploadPolicy
    This string is a regular expression. It allows the applet to test that the server has accepted the upload. If this parameter is given to the applet, the upload thread will try to match this regular expression against each lines returned from the server.
    If the match is successfull once, the upload is considered to be a success. If not, a JUploadExceptionUploadFailed is thrown.
    The default test expression testes that the web server returns no HTTP error: 200 is the return code for a successfull HTTP request. It actually means that postURL is a valid URL, and that the applet was able to send a request to this URL: there should be no problem with the network configuration, like proxy, password proxy...).
    But it doesn't mean that the uploaded files have correctly be managed by the server. For instance, the URL can be http://sourceforge.net, which, of course, would not take your files into account.
    So, as soon as you know a regular expression that test the return from the target application (and not just a techical HTTP response code), change the stringUploadSuccess to this value. For instance, the default value will be matched if the HTTP body content of the server response contains one line that is exactly 'SUCCESS', without any other character. This 'success' means that the pictures have correctly uploaded to the server, and that he successfully managed the uploaded files.
    targetPictureFormat Empty String

    (to be implemented in PictureUploadPolicy)
    This parameter can contain any picture writer known by the JVM. For instance: jpeg, png, gif. All standard formats should be available. More information can be found on the java.sun.com web site.
    uploadPolicy DefaultUploadPolicy

    see UploadPolicyFactory
    This parameter contains the class name for the UploadPolicy that should be used. If it is not set, or if its value is unknown from UploadPolicyFactory.getUploadPolicy(JUploadApplet), the DefaultUploadPolicy is used.
    urlToSendErrorTo null

    DefaultUploadPolicy
    If this url is given, and an upload error occurs, the applet posts all debug output to this address. It's up to this URL to handle this message. It is possible to just store the file, or to log the error in a database, or to send a mail (like the mail.php script given with the coppermine pack).
    Note: Only http and https URL schemes are supported.

    HTML call example

    Below, an example of how to put the applet into a PHP page is shown:

                                         <applet name="JUpload" code="wjhk.jupload2.JUploadApplet"
                                           archive="plugins/jupload/wjhk.jupload.jar"
                                           <!-- Applet display size, on the navigator page -->
                                           width="500" height="700"
                                           <!-- The applet uses some javascript functions, so we must allow that : -->
                                           mayscript>
                                           <!-- No parameter is mandatory. We don't precise the UploadPolicy, so
                                                DefaultUploadPolicy is used. The applet behaves like the original
                                                JUpload. (jupload v1) -->
                                           <param name="postURL" value="http://some.host.com/youruploadpage.php">
                                           Java 1.5 or higher plugin required.
                                         </applet>