com.dropbox.client2

Class DropboxAPI.ChunkedUploader

java.lang.Object

com.dropbox.client2.DropboxAPI.ChunkedUploader

Enclosing class:

DropboxAPI<SESS_T extends Session>

public class DropboxAPI.ChunkedUploader
extends java.lang.Object

Represents a single chunked upload in progress. Uploads bytes from the given InputStream to dropbox using the chunked upload protocol. Completion of the upload can be detected by comparing the ChunkedUploader's offset against the expected size of the file being uploaded. Expected use:

     DropboxAPI api = ...
     File bigFile = new File("99mb.avi");
     FileInputStream in = new FileInputStream(bigFile);
     DropboxAPI.Entry uploadedFileMetadata;
     try {
         DropboxAPI.ChunkedUploader uploader = api.getChunkedUploader(in, bigFile.length());
         int retryCounter = 0;
         while(!uploader.isComplete()) {
             try {
                 uploader.upload();
             } catch (DropboxException e) {
                 if (retryCounter > MAX_RETRIES) break;  // Give up after a while.
                 retryCounter++;
                 // Maybe wait a few seconds before retrying?
             }
         }
         uploadedFileMetadata = uploader.finish("/Videos/99mb.avi", null);
     } finally {
         in.close();
     }
 

Method Summary

Methods

Modifier and Type	Method and Description
void	abort() Aborts this chunked upload if it was already in progress.
DropboxAPI.Entry	finish(java.lang.String path, java.lang.String parentRev) Completes a chunked upload, commiting the already uploaded file to Dropbox.
boolean	getActive() Whether or not this ChunkedUploader is active and has not yet been aborted.
long	getOffset() Returns the last-known byte offset that the server expects to receive.
boolean	isComplete() Whether or not this ChunkedUploader has completed its upload.
void	upload() Convenience wrapper around upload(ProgressListener) defaulting to a chunk size of 4 megabytes and no progress listener.
void	upload(ProgressListener listener) Uploads multiple chunks of data to the server until the upload is complete or an error occurs.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getOffset

public long getOffset()

Returns the last-known byte offset that the server expects to receive. Used to find the appropriate range of bytes to next upload. May be out of date if there has been a network failure between the server receiving an upload and acknowledging with a response.

Returns:

The last byte offset that was received from the server.

isComplete

public boolean isComplete()

Whether or not this ChunkedUploader has completed its upload. An upload is complete when the desired number of bytes has been uploaded from the InputStream.

getActive

public boolean getActive()

Whether or not this ChunkedUploader is active and has not yet been aborted. If you want to find out whether the upload has completed successfully, see isComplete().

abort

public void abort()

Aborts this chunked upload if it was already in progress. Actively aborts the in-progress http request if called in the middle of uploading a chunk. The original call to upload() will exit with a DropboxPartialFileException. An upload which is aborted cannot be resumed.

upload

public void upload()
            throws DropboxException,
                   java.io.IOException

Convenience wrapper around upload(ProgressListener) defaulting to a chunk size of 4 megabytes and no progress listener.

Throws:

DropboxException - If there was a transmission error

java.io.IOException - If there was a problem reading from the given InputStream.

DropboxPartialFileException - if the request was canceled before completion.

upload

public void upload(ProgressListener listener)
            throws DropboxException,
                   java.io.IOException

Uploads multiple chunks of data to the server until the upload is complete or an error occurs. This method makes multiple requests to Dropbox, uploading multiple chunks of data from the given ChunkedUploader's input stream. In the event of a network error or a server error, an IOException or DropboxServerException respectively will be thrown. This gives the user an opportunity to resume the upload by calling this method again, or aborting and abandoning it.

Parameters:

listener - A ProgressListener (can be null) that will be notified of upload progress. The progress notifications will be for the entire file.

Throws:

DropboxException - If there was a transmission error

java.io.IOException - If there was a problem reading from the given InputStream.

DropboxPartialFileException - if the request was canceled before completion.

finish

public DropboxAPI.Entry finish(java.lang.String path,
                      java.lang.String parentRev)
                        throws DropboxException

Completes a chunked upload, commiting the already uploaded file to Dropbox. The upload will not overwrite any existing version of the file, unless the latest version on the Dropbox server has the same rev as the parentRev given. Pass in null if you're expecting this to create a new file.

Parameters:

path - the full Dropbox path where to put the file, including directories and filename.

parentRev - the rev of the file at which the user started editing it (obtained from a metadata call), or null if this is a new upload. If null, or if it does not match the latest rev on the server, a copy of the file will be created and you'll receive the new metadata upon executing the request.

Returns:

an Entry containing the metadata of the committed file.

Throws:

DropboxException - if anything goes wrong.