Package com.dropbox.core

Class DbxUploader<R,E,X extends DbxApiException>

java.lang.Object

com.dropbox.core.DbxUploader<R,E,X>

Type Parameters:

R - response type returned by server on request success

X - exception type returned by server on request failure

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

Direct Known Subclasses:

AlphaUploadUploader, DocsCreateUploader, DocsUpdateUploader, PaperCreateUploader, PaperUpdateUploader, UploadSessionAppendUploader, UploadSessionAppendV2Uploader, UploadSessionFinishUploader, UploadSessionStartUploader, UploadUploader

public abstract class DbxUploader<R,E,X extends DbxApiException>
extends java.lang.Object
implements java.io.Closeable

Class for completing upload requests. This class provides methods for uploading a request body and handling the server response. Example usage:

    FileInputStream in = new FileInputStream("test.txt");
    try {
        response = uploader.uploadAndFinish(in);
    } finally {
        in.close();
    }

Example using getOutputStream():

    try {
        OutputStream out = uploader.getOutputStream();
        out.write(data);
        response = uploader.finish();
    } finally {
        uploader.close();
    }

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	DbxUploader(HttpRequestor.Uploader httpUploader, StoneSerializer<R> responseSerializer, StoneSerializer<E> errorSerializer, java.lang.String userId)

Method Summary

Modifier and Type	Method	Description
void	abort()	Aborts this upload request and closes its underlying connection.
void	close()	Closes this upload request and releases its underlying resources.
R	finish()	Completes the request and returns response from the server.
java.io.OutputStream	getOutputStream()	Returns an OutputStream that writes to the request body.
java.io.OutputStream	getOutputStream(IOUtil.ProgressListener progressListener)	Returns an OutputStream that writes to the request body.
protected abstract X	newException(DbxWrappedException error)
R	uploadAndFinish(java.io.InputStream in)	Uploads all bytes read from the given InputStream and returns the response.
R	uploadAndFinish(java.io.InputStream in, long limit)	Uploads up to limit bytes read from the given InputStream and returns the response.
R	uploadAndFinish(java.io.InputStream in, long limit, IOUtil.ProgressListener progressListener)	This method is the same as uploadAndFinish(InputStream, long) except for it allows tracking the upload progress.
R	uploadAndFinish(java.io.InputStream in, IOUtil.ProgressListener progressListener)	This method is the same as uploadAndFinish(InputStream, long) except for it allow tracking the upload progress.

Methods inherited from class java.lang.Object

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

Constructor Detail

DbxUploader

protected DbxUploader(HttpRequestor.Uploader httpUploader,
                      StoneSerializer<R> responseSerializer,
                      StoneSerializer<E> errorSerializer,
                      java.lang.String userId)

Method Detail

newException

protected abstract X newException(DbxWrappedException error)

uploadAndFinish

public R uploadAndFinish(java.io.InputStream in)
                  throws X extends DbxApiException,
                         DbxException,
                         java.io.IOException

Uploads all bytes read from the given InputStream and returns the response. This method manages closing this uploader's resources, so no further calls to close() are necessary. The underlying OutputStream returned by getOutputStream() will be closed by this method. This method is the equivalent of

    try {
        OutputStream out = uploader.getOutputStream();
        // read from in, write to out
        response = uploader.finish();
    } finally {
        uploader.close();
    }
 

Parameters:

in - InputStream containing data to upload

Returns:

Response from server

Throws:

X - if the server sent an error response for the request

DbxException - if an error occurs uploading the data or reading the response

java.io.IOException - if an error occurs reading the input stream.

java.lang.IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())

X extends DbxApiException

uploadAndFinish

public R uploadAndFinish(java.io.InputStream in,
                         IOUtil.ProgressListener progressListener)
                  throws X extends DbxApiException,
                         DbxException,
                         java.io.IOException

This method is the same as uploadAndFinish(InputStream, long) except for it allow tracking the upload progress.

Parameters:

in - InputStream containing data to upload

progressListener - OUtil.ProgressListener to track the upload progress. Only support OKHttpRequester and StandardHttpRequester.

Returns:

Response from server

Throws:

X - if the server sent an error response for the request

DbxException - if an error occurs uploading the data or reading the response

java.io.IOException - if an error occurs reading the input stream.

java.lang.IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())

X extends DbxApiException

uploadAndFinish

public R uploadAndFinish(java.io.InputStream in,
                         long limit)
                  throws X extends DbxApiException,
                         DbxException,
                         java.io.IOException

Uploads up to limit bytes read from the given InputStream and returns the response. This method upload bytes from the given InputStream until limit bytes have been read or end-of-stream is detected. Use uploadAndFinish(InputStream) to upload the entire stream. This method manages closing this uploader's resources, so no further calls to close() are necessary. The underlying OutputStream returned by getOutputStream() will be closed by this method. This method is the equivalent of

    try {
        OutputStream out = uploader.getOutputStream();
        // read at most `limit` bytes from in, write to out
        response = uploader.finish();
    } finally {
        uploader.close();
    }
 

Parameters:

in - InputStream containing data to upload

limit - Maximum number of bytes to read from the given InputStream

Returns:

Response from server

Throws:

X - if the server sent an error response for the request

DbxException - if an error occurs uploading the data or reading the response

java.io.IOException - if an error occurs reading the input stream.

java.lang.IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())

X extends DbxApiException

uploadAndFinish

public R uploadAndFinish(java.io.InputStream in,
                         long limit,
                         IOUtil.ProgressListener progressListener)
                  throws X extends DbxApiException,
                         DbxException,
                         java.io.IOException

This method is the same as uploadAndFinish(InputStream, long) except for it allows tracking the upload progress.

Parameters:

in - InputStream containing data to upload

limit - Maximum number of bytes to read from the given InputStream

progressListener - OUtil.ProgressListener to track the upload progress. Only support OKHttpRequester and StandardHttpRequester.

Returns:

Response from server

Throws:

X - if the server sent an error response for the request

DbxException - if an error occurs uploading the data or reading the response

java.io.IOException - if an error occurs reading the input stream.

java.lang.IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())

X extends DbxApiException

close

public void close()

Closes this upload request and releases its underlying resources. This method should always be called to allow for proper resource deallocation.

    try {
        OutputStream out = uploader.getOutputStream();
        out.write(data);
        response = uploader.finish();
    } finally {
        uploader.close();
    }
 

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

abort

public void abort()

Aborts this upload request and closes its underlying connection.

getOutputStream

public java.io.OutputStream getOutputStream()

Returns an OutputStream that writes to the request body. Remember to call finish() to complete the request and retrieve the response. Data written to this stream will be uploaded. Typically you will not need this method and can use the more convenient uploadAndFinish(InputStream).

Returns:

Request body output stream.

Throws:

java.lang.IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())

See Also:

uploadAndFinish(InputStream)

getOutputStream

public java.io.OutputStream getOutputStream(IOUtil.ProgressListener progressListener)

Returns an OutputStream that writes to the request body. Remember to call finish() to complete the request and retrieve the response. Data written to this stream will be uploaded. Typically you will not need this method and can use the more convenient uploadAndFinish(InputStream).

Parameters:

progressListener - IOUtil.ProgressListener to track the upload progress. Only support OKHttpRequester and StandardHttpRequester.

Returns:

Request body output stream.

Throws:

java.lang.IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())

See Also:

uploadAndFinish(InputStream)

finish

public R finish()
         throws X extends DbxApiException,
                DbxException

Completes the request and returns response from the server. This method should be called after writing data to the upload OutputStream (see getOutputStream()).

Returns:

Response from server

Throws:

X - if the server sent an error response for the request

DbxException - if an error occurs sending the upload or reading the response

java.lang.IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())

X extends DbxApiException