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.

filetransfer-screenshot

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.

...

long maximumFileSizeInBytes = 1000 * 1024; long bytesTransferredPerRoundTrip = 10 * 1024;

FileDownloadTaskList fileUploadTaskList = new FileDownloadTaskList(maximumFileSizeInBytes, bytesTransferredPerRoundTrip, new IFileDownloadHandler() { public String 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.

...

ULCProgressPane progressPane = new ULCProgressPane(taskList);

final ULCDialog dialog = new ULCDialog(null, "File Download", true); dialog.getContentPane().add(progressPane); dialog.setVisible(true);

progressPane.addTaskControllerListener(new TaskControllerAdapter() { public void completed() { dialog.setVisible(false); }

public void stopped() { dialog.setVisible(false); }

public void error(Exception e) { dialog.setVisible(false); } });

progressPane.start();

...

How it is implemented

The FileDownloadTaskList (FileUploadTaskList) uses an instance of ULCFileDownloader (ULCFileUploader) for performing the actual up- / download task. The task list dynamically generates tasks until the up- / downloader instance notifies completion of the up- / download action.

Resources