com.ithit.webdav.server.resumableupload
Interface UploadProgress

public interface UploadProgress

Implemented on files and folders to report upload progress.

This interface should be implemented on files that can provide upload progress information to client application. Optionally it can be implemented on folder items.

Usually client application requests upload progress in following cases:

• If connection was broken (paused) and client would like to restore upload. Client will submit upload-progress request to get number of bytes successfully saved on server side and will start the upload from the next byte. Usually upload restoration could be achieved only by rich client applications (.NET, Java, etc).
• When thin client (AJAX or other) requires information about how much of the uploaded file was processed on server side. Unlike rich client, thin client application does not have any information about how much of the file was submitted to server. Thin client will submit upload-progress request to update its upload progress bar from time to time.

To check if folder or file supports upload-progress report and resumable upload feature the client application will submit OPTIONS request to that item. If the item implements UploadProgress interface Engine will add 'resumable-upload' token to DAV response header. See example below.

To get information about file upload progress client will submit REPORT request to that file with upload-progress type. The Engine will call getUploadProgress() method in this case. In case of file you will return an array that contains single item (this item implementing ResumableUpload) from UploadProgress method implementation. The engine will extract necessary info from the returned ResumableUpload interface and return it to client. The response will contain XML with information about upload progress for the requested file: url of the file, number or bytes uploaded, total size of the file and time when last save operation occurred.

The response returned by server Engine to client is a REPORT multistatus response that contains three properties for each file:

• ithit:bytes-uploaded - integer value. Number of bytes uploaded and saved in persistent storage. If upload was broken or paused the client application will usually start upload from the next byte returned in this property.
• ithit:last-chunk-saved - date\timein in RFC 1123 format. Indicates when last chunk was saved. May be used in admin applications and automatic maintenance tools to remove files that were not fully uploaded.
• ithit:total-content-length - integer value. Total file size that is being uploaded to server. Thin client applications may use this value for displaying upload progress.

See example of upload progress report below.

The client application can also submit upload-progress REPORT request to a folder. In this case from your getUploadProgress() property implementation you will return array of files that are being uploaded that reside in the folder's subtree. The response XML will contain info about each file from the array in a separate response tag. See example below.

If item does not support upload-progress report and server is based on IT Hit WebDAV Server Engine the server will respond with '403 Forbidden' to REPORT request. The body will contain <A:supported-report xmlns="DAV:"/> element. If server does not support REPORT verb you will get 405 Method Not Allowed response.

OPTIONS request is used to determine if folder or file supports resumable upload.

Request:

 OPTIONS /Folder/ HTTP/1.1
 Host: davserver
 Content-Length: 0
 

Response:

 HTTP/1.1 200 OK
 Content-Length: 0
 Accept-Ranges: none
 DAV: 1, 2, resumable-upload
 Public: OPTIONS, PROPFIND, PROPPATCH, COPY, MOVE, DELETE, MKCOL, LOCK, UNLOCK
 Allow: OPTIONS, PROPFIND, PROPPATCH, COPY, MOVE, DELETE, MKCOL, LOCK, UNLOCK
 

Upload progress report submitted over file contains info about single item.

Request:

 REPORT /LargeFile.doc HTTP/1.1
 Host: http://davserver/
 Content-Type: text/xml; charset=\"utf-8\"
 Content-length: 32

 <upload-progress xmlns='ithit'/>
 

Response:

 HTTP/1.1 207 Multi-Status
 Content-Length: 2452
 Content-Type: text/xml;charset=UTF-8

 <?xml version="1.0" encoding="utf-8" ?>
 <D:multistatus xmlns:D="DAV:">
 <D:response>
    <D:href>http://server:8580/LargeFile.doc</D:href>
    <D:propstat>
        <D:prop>
             <ithit:bytes-uploaded>20</ithit:bytes-uploaded>
             <ithit:last-chunk-saved>Wed, 23 May 2007 13:29:43 GMT</ithit:last-chunk-saved>
             <ithit:total-content-length>150742</ithit:total-content-length>
       </D:prop>
       <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
 </D:response>
 </D:multistatus>
 

If item on server based on IT Hit WebDAV Server Engine does not support upload-progress the server will respond with 403 Forbidden response.

Request:

 REPORT /LargeFile.doc HTTP/1.1
 Host: http://davserver/
 Content-Type: text/xml; charset=\"utf-8\"
 Content-length: 32
 
 <upload-progress xmlns='ithit'/>
 

Response:

 
 HTTP/1.1 403 Forbidden
 Content-Length: 31
 Content-Type: text/xml;charset=UTF-8

 <supported-report xmlns="DAV"/>
 

If server does not support REPORT verb (often non-IT Hit Engine) you will get 405 Method Not Allowed response.

Request:

 REPORT /LargeFile.doc HTTP/1.1
 Host: http://davserver/
 Content-Type: text/xml; charset=\"utf-8\"
 Content-length: 32

 <upload-progress xmlns='ithit'/>
 

Response:

 HTTP/1.1 405 Method Not Allowed
 Content-Length: 0
 Content-Type: text/xml;charset=UTF-8
 
 

Method Summary

java.util.List<? extends ResumableUpload>

getUploadProgress() Array of items that are being uploaded to this item subtree.

Method Detail

getUploadProgress

java.util.List<? extends ResumableUpload> getUploadProgress()
                                                            throws ServerException

Array of items that are being uploaded to this item subtree.

Engine calls HierarchyItem.getPath(), ResumableUpload.getLastChunkSaved(), ResumableUpload.getBytesUploaded(), ResumableUpload.getTotalContentLength() and returns this information to client.

Returns:

Return array with a single item if implemented on file items. Return all items that are being uploaded to this subtree if implemented on folder items.

Throws:

ServerException - - in case of an error.