File Transfer

Purpose

This extension provides support for transferring large files between the client and the server in multiple steps. Unlike
"standard" ULC, the file gets transferred in multiple server round-trips. The progress of the file up- / download is
visualized using a progress dialog.

Please note: the file transfer direction is always named from the server's point of view (as ULC is a server-side technology):

FileDownloadTaskList and IFileDownloadHandler are used to download a file from the client down to the server, performing a file upload from the client's point of view

FileUploadTaskList and IFileUploadHandler are used to upload a from file the server up to the client, performing a file download from the client's point of view

When mentioning the file transfer action to the client (e.g. on the progress dialog), the terms familiar to the user from his/her point of view are used.

How to use

Create an instance of FileDownloadTaskList (FileUploadTaskList) and configure it with an implementation
of the IFileDownloadHandler (IFileUploadHandler) interface.

Both task list are also configured with the "chunk size", the amount of bytes to be transferred in a single server round-trip. For each server round-trip, the progress visualization gets updated. Thus, there is a trade-off between a small amount of bytes with a "fluid" progress visualization and the number of server round-trips required to up- / download the whole file. The smaller the amount of bytes per server round-trip and the more frequent the progress visualization has to be updated, the more server round-trips are executed. The best numbers depend on the deplyoment scenario: in an intranet
environment, executing more server round-trips is often acceptable as bandwidth is assumed to be high and latency low. On the contrary, in an internet environment with small bandwidths and high latency, sending more bytes in a single server round-trip and thus, reducing the "visual experience" may be the better solution.

For file downloads (to the server), a maximum file size can be specified in order to prevent the server from being "blown up" by a client sending a huge file to the server. Whenever the client provides a file that is larger than the maximum limit, the onFailure() callback of IFileDownloadHandler (IFileUploadHandler) is invoked.

FileDownloadTaskList fileUploadTaskList = new FileDownloadTaskList(maximumFileSizeInBytes, bytesTransferredPerRoundTrip, new IFileDownloadHandler() {
publicString getClientFilePath() { // the path of the file to be read on the client
return filePath;
}

public void onSuccess(byte[] downloadedBytes) {
// use byte array representing the downloaded file content
// for further processing on the server
}

public void onFailure(Exception reason) {
// show error dialog
}

public void onCancel() {
// do nothing ???
}
});

...

Use an instance of ULCPrgressPane to control and visualize the file up- / download action

The ULCProgressPane is part of the Contributions/Extensions/Progress Pane extension. Then, add the ULCProgressPane as the
content pane to a modal dialog and start the action. In addition, an implementation of ITaskControllerListener can be used to
hide the progress dialog whenever the file transfer has completed, failed or been cancelled by the user.