This package contains the upload policies: they give you hook entry points, to override the default applet behaviour with a minimum of java code.

Creating a new upload policy: introduction

You'll find on this page a description of the {@link wjhk.jupload2.policies.UploadPolicy} methods, grouped by categories.

Note: Creating a new upload policy is mandatory, if you want to manage some other kind of {@link wjhk.jupload2.filedata.FileData}. You can then add some kind of 'before upload check', or have a specific applet behaviour, for instance be able to hear sound file before upload.

Presentation

To create a new upload policy, you need to create a new java class: the easiest way is to inherit from @link wjhk.jupload2.policies.DefaultUploadPolicy}. You can then override methods of the UploadPolicy interface that you need to update for your needs.

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. For instance, some attributes and methods from DefaultUploadPolicy are protected (not private), so that you can use them in your own upload policies.

Here is a sample description of the customization that you can do by using the creating a new policy, using the UploadPolicy interface. All methods are described in the next section of this page.

• Control files management:
  • Authorization (or not) to add a file to the list of files to upload, see UploadPolicy#createFileData(File, File). This allows the policy to validate files, before adding them to the list of files that must be displayed. The {@link wjhk.jupload2.policies.UploadPolicy#createFileData(File, File)} checks that the added files are valid pictures.
  • File preparation before upload (for instance to resize a picture, or encode a text file to a specific format)
• Display other buttons on the applet (or remove the default buttons), see UploadPolicy.createTopPanel(JButton, JButton, JButton, JPanel)
• Specific behaviour, on file selection. The wjhk.jupload2.policies.PictureUploadPolicy allows picture management. The UploadPolicy.onSelectFile(FileData) method is called when the user selects a file in the list. This allow the policy to do any action about this file. The PictureUploadPolicy.onSelectFile(FileData) displays a preview pictures on the top part of the applet.

Note: UploadPolicyFactory

The JuploadApplet asks the UploadPolicyFactory to create (instanciate) the needed UploadPolicy. That is:

Creation of a new UploadPolicy: detailed steps

To create a new UploadPolicy, you'll need to:

• Create a new class, implementing the UploadPolicy interface. The easiest way is to inherit from an existing UploadPolicy. This insure that your new policy will be compatible with next JUpload releases.
  Note: The upload policies are created by UploadPolicyFactory. Their constructor must:
  • Be public, to be called by this class,
  • Have one parameter: the current wjhk.jupload2.context.JUploadContext.
• Override some UploadPolicy methods, to have your specific behaviour.
• Don't change any other java code, so that your upload policy will work with next JUpload releases.
  Note: if you need another 'hook', to be able to add specific customization, please add a new Feature Request in sourceforge, I'll receive a notification mail.

Methods to control file management

FileData createFileData(File file, File root) throws JUploadExceptionStopAddingFiles

This methods creates a new {@link wjhk.jupload2.filedata.FileData} object. It returns null is no file data was created, for instance if this file didn't check some specific validation checks.
Note: use this method to use any FileData specific to your needs. See {@link wjhk.jupload2.policies.PictureUploadPolicy} for a sample of this.

void afterFileDropped(DropTargetDropEvent dropEvent)

Specific reaction of the applet, when file are dropped onto it.

Methods to control the applet GUI (display, behaviour)

JPanel createTopPanel(JButton browse, JButton remove, JButton removeAll, JUploadPanel mainPanel)

Allows the applet to change the way the top part of the applet is displayed, that is: the place where the Choose, remove, remove all buttons are. If you override this method, you must use the given button if you want these functionalities to work. If you don't put the browse button, for instance, the user won't be able to display a file chooser, unless you manage it yourself. See {@link wjhk.jupload2.policies.PictureUploadPolicy}, for a way to use the standard buttons, and add specific ones.

void addComponentsToJUploadPanel(JUploadPanel jUploadPanel)

Extension of the createTopPanel() idea. You can place any component of JUpload at any place ... or at no place. If you override this method, you'll have to call the {@link wjhk.jupload2.gui.JUploadPanel} getter to get core applet objects. These are:

JPanel createProgressPanel(JProgressBar progressBar, JButton uploadButton, JButton stopButton, JPanel mainPanel)

You probably won't have to override this method. Note that this method allows you to not display the stop and upload buttons.

JPanel createStatusBar(JLabel statusContent, JPanel mainPanel)

This method should not be used any more. Use the showStatusBar applet parameter instead.

void onFileSelected(FileData fileData)

Reaction of the applet, when a file is selected in the file list. For instance, {@link wjhk.jupload2.policies.PictureUploadPolicy} displays the selected picture in the preview component.

void onFileDoubleClicked(FileData fileData)

Reaction of the applet, when a file is double clicked. For instance, {@link wjhk.jupload2.policies.PictureUploadPolicy} opens a dialog box, that contain a full screen display of the current picture.

Methods to control the file chooser

JUploadFileChooser createFileChooser()

Allows the applet to change user another JFileChooser. Your specific file chooser should inherit from JUploadFileChooser

boolean fileFilterAccept(File file)

Called by the {@link wjhk.jupload2.gui.JUploadFileFilter}. This method contains the actual response to the { @link java.io.FileFilter#accept(File)} method of the FileFilter interface. It allows to control what can be displayed on the file chooser.

String fileFilterGetDescription()

The file filter description, in the file chooser. The default is to display the list of authorized extensions. This can be too large, if many extensions are authorized. You can then put here a more descriptive text.

Icon fileViewGetIcon(File file)

Returns the icon that must be displayed for this file on the file chooser. This method is called asynchroneously, so that long calculation won't block the applet. See an example in the {@link wjhk.jupload2.policies.PictureUploadPolicy}. This policy returns an icon created from the picture content.

Upload management

boolean isUploadReady()

Allows a control of the current upload policy, before any upload work starts. You'll probably have to override this method if you want to do pre-upload checks on files

void beforeUpload()

This method is called just before upload, for instance to allow any 'before upload' work, like computing some global information. See also the FileData.beforeUpload(), that is called for each file.

boolean checkUploadSuccess(int status, String msg, String body) throws JUploadException

You probably won't have to override this method, if you use the stringUploadSuccess and stringUploadError applet parameters. If not, this method allows you to check that upload is a success. That is: there is no error (for instance, page not found), and the server side application actually accepted the file(s).

void afterUpload(Exception e, String serverOutput) throws JUploadException

Allows the caller to free any resource used during upload. See also the FileData.afterUpload(), that is called for each file.

String getLastResponseBody()

This method is useful only in HTTP upload (not FTP, for instance). It allows any check or update of applet variables based on the server return. You probably should not have to override this method.

String getLastResponseMessage()

This method is useful only in HTTP upload (not FTP, for instance). It returns the full HTTP response, with headers. It allows any check or update of applet variables based on the server return. You probably should not have to override this method.

void addHeader(String header)

Add a header to the list of all header that must be added to all upload. Useful only when uploading in HTTP mode. If you override this method, you'll have to override the onAppendHeader(ByteArrayEncoder) method.

ByteArrayEncoder onAppendHeader(ByteArrayEncoder sb) throws JUploadIOException

Add header on the HTTP request, while this requet is being written to the server. If you override this method, you'll have to call super.onAppendHeader(ByteArrayEncoder) method.

String getSpecificHeaders()

Allows the upload policy to add specific headers. This is used only for HTTP upload.

String getFormdata()

Load data from an HTML form. These data will be set with each file in the upload. See also the {@link wjhk.jupload2.filedata.FileData#appendFileProperties(ByteArrayEncoder)} method, for a way to add data specific to one file.

Getters and setters

The last category of methods is the getters and setters. There is a getter for each applet parameter. Most of applet parameters also has a setter. You can override them to add some execution time calculation. For instance, {@link Coppermine#getPostURL()} calls the default getter, than the album id as a new parameter on the URL.

Here are the other getters:

void setProperty(String prop, String value) throws JUploadException

Allows to set any property. This can be called for any applet parameter. This method can be called from Javascript, to allow runtime control of applet state by the javascript.

JUploadApplet getApplet()

This important getter returns the JUploadApplet. From it, you can get any GUI component.

String getDateFormat()

Returns the current date format, so that all date/time are displayed by using the same format.

int getSslVerifyCert()

For SSL management. Standard code should be good enough.

Message display (debug, info, warning, error...)

void displayParameterStatus()

You should override this method, to display any parameter specific to your upload policy. See {@link wjhk.jupload2.policies.PictureUploadPolicy} for a sample.

void alert(String key)

You probably won't have to override this method. Displays an alert box, based on the key of the translated message.

void alertStr(String str)

You probably won't have to override this method. Displays an alert box.

void displayInfo(String info)

You probably won't have to override this method.. Will be renamed, as it just logged an info message.

void displayWarn(String warn)

You probably won't have to override this method. Will be renamed, as it just logs a warning.

void displayDebug(String debug, int minDebugLevel)

You probably won't have to override this method.. Will be renamed, as it just logs a debug message.

void displayErr(String err, Exception e)

You probably won't have to override this method. Will be renamed.

void displayErr(Exception e)

You probably won't have to override this method. Will be renamed.

void displayErr(String err)

You probably won't have to override this method. Will be renamed.

String getString(String key)

You probably won't have to override this method. Manages text translation.

Miscellaneous methods

Cursor setWaitCursor()

You can change the applet wait cursor, by overriding this method.

void setCursor(Cursor cursor)

I don't think you'll have to override this one...

void sendDebugInformation(String reason)

send the debug output to the urlToSendErrorTo applet parameter. Allows logging on the server ... if this calls succeed, which is not the case when the server has a big trouble.