Package wjhk.jupload2.policies

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

See: Description

Interface Summary

Interface	Description
UploadPolicy	This package contains upload policies, which allow easy configuration of the applet behavior.

Class Summary

Class	Description
AAFUploadPolicy
CoppermineUploadPolicy	Specific UploadPolicy for the coppermine picture gallery.
CustomizedNbFilesPerRequestUploadPolicy	Deprecated This class is of no use, as it actually behaves exactly as the DefaultUploadPolicy.
DefaultUploadPolicy	This class implements all UploadPolicy methods.
FileByFileUploadPolicy	Deprecated You can use the applet, without the uploadPolicy applet parameter, and put the nbFilesPerRequest to 1.
FilesTogetherUploadPolicy	Upload policy that is a simple box.
PictureUploadPolicy	This class add handling of pictures to upload.
SilverpeasUploadPolicy	Personnalised Policy with no button : use only DragAndDrop or Copy/Paste with automatic upload.
SuperSimpleUploadPolicy	A SuperSimpleUploadPolicy - see https://sourceforge.net/tracker/?
UploadPolicyFactory	This class is used to control creation of the uploadPolicy instance, according to applet parameters (or System properties).

Package wjhk.jupload2.policies Description

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

This pages describes how to create a new upload policy, to adapt the applet to your needs, without interfering with the core applet, that is: with having compatibility with future JUpload versions. Here are other links on this subject:

See UploadPolicy for the list of applet parameters

howto customize for a presentation of the main ways to adapt the applet to your needs.

Creating a new upload policy: introduction

Creating a new upload policy, allows you to change the applet behaviour, and still use the core applet function. This insures you that your development will remain compatible with next applet versions.

You'll find on this page a description of the UploadPolicy methods, grouped by categories.

Note: Creating a new upload policy is mandatory, if you want to manage some other kind of 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.

Note: the best way is to not modify the JUpload package, and create a specific jar file containing your added code. See, below, the Creating a new UploadPolicy: compilation and deployment part.

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 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:

During initialization of the applet, the UploadPolicyFactory.getUploadPolicy() method is called. This method checks the uploadPolicy parameter. If this uploadPolicy is unknown or not set, the DefaultUploadPolicy is used. If a specific uploadPolicy is found, it can of course read specific parameters from the APPLET tag.

Then, UploadPolicyFactory.getUploadPolicy() creates the class implementing the UploadPolicy factory, and returns the reference to this class.

The upload policy can not be changed while the applet is running.

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.

Creating a new UploadPolicy: compilation and deployment

The best way to override the JUpload policy, is to create a separate project, dedicated to your specific code. For compilation, the JUpload applet would need to be on its buid path. Then, compile your code and pack it into a jar file. This jar file would contain only your specific code.

You'll then have to sign your jar file. To simplify user's life, you should sign JUpload with the same certificate.

Then, put the two jar file in the applet classpath, by having something like this:

<APPLET CODE="wjhk.jupload2.JUploadApplet" ARCHIVE="wjhk.jupload.jar, yourspecificjarfile.jar" NAME="jupload" MAYSCRIPT="" height="300" width="640">
   <param name="postURL" value="upload_dummy.html">
   <param name="maxChunkSize" value="500000">
   <param name="uploadPolicy" value="your.package.yourUploadPolicyClassName">
Java 1.5 or higher plugin required.
</applet>

Methods to control file management

FileData createFileData(File file, File root) throws JUploadExceptionStopAddingFiles

This methods creates a new 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 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)

This methods are used to control what the JUploadFileChooser has to do.

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 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 JUploadPanel getter to get core applet objects. These are:

Standard buttons: browseButton, removeButton, removeAllButton, stopButton, uploadButton.

Drag'n drop listener: dndListener, to manage files dropped on the applet

The log output: jLogWindowPane

The progress bar, which indicated the upload progress (from 0 to 100%): progressBar.

The status label, where upload speed is indicated:

The file panel, that contains the list of files to upload: filePanel.

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, 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, PictureUploadPolicy opens a dialog box, that contain a full screen display of the current picture.

Methods to control the file chooser

This methods are used to control what the JUploadFileChooser has to do.

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 JUploadFileFilter. This method contains the actual response to the 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 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 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, 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 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.