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:

Closeable, AutoCloseable

Direct Known Subclasses:

UploadSessionAppendUploader, UploadSessionAppendV2Uploader, UploadSessionFinishUploader, UploadSessionStartUploader, UploadUploader

public abstract class DbxUploader<R,E,X extends DbxApiException>
extends Object
implements 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 and Description
protected	DbxUploader(HttpRequestor.Uploader httpUploader, StoneSerializer<R> responseSerializer, StoneSerializer<E> errorSerializer)

Method Summary

Modifier and Type	Method and 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.
OutputStream	getOutputStream() Returns an OutputStream that writes to the request body.
protected abstract X	newException(DbxWrappedException error)
R	uploadAndFinish(InputStream in) Uploads all bytes read from the given InputStream and returns the response.
R	uploadAndFinish(InputStream in, long limit) Uploads up to limit bytes read from the given InputStream and returns the response.

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)

Method Detail

newException

protected abstract X newException(DbxWrappedException error)

uploadAndFinish

public R uploadAndFinish(InputStream in)
                  throws X extends DbxApiException,
                         DbxException,
                         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

IOException - if an error occurs reading the input stream.

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

X extends DbxApiException

uploadAndFinish

public R uploadAndFinish(InputStream in,
                         long limit)
                  throws X extends DbxApiException,
                         DbxException,
                         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

IOException - if an error occurs reading the input stream.

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 Closeable

Specified by:

close in interface AutoCloseable

abort

public void abort()

Aborts this upload request and closes its underlying connection.

getOutputStream

public OutputStream getOutputStream()

Returns an OutputStream that writes to the request body. Remember to call finish() to complete the request and retrieve the response. Data writen 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:

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

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

X extends DbxApiException