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:
Closeable, AutoCloseable
Direct Known Subclasses:
AlphaUploadUploader, DocsCreateUploader, DocsUpdateUploader, PaperCreateUploader, PaperUpdateUploader, UploadSessionAppendBatchUploader, 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 Details

  • Method Details

    • newException

      protected abstract X newException(DbxWrappedException error)

    • uploadAndFinish

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

    • uploadAndFinish

      public R uploadAndFinish(InputStream in, IOUtil.ProgressListener progressListener) throws X, DbxException, 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
      IOException - if an error occurs reading the input stream.
      IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())

    • uploadAndFinish

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

    • uploadAndFinish

      public R uploadAndFinish(InputStream in, long limit, IOUtil.ProgressListener progressListener) throws X, DbxException, 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
      IOException - if an error occurs reading the input stream.
      IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())

    • 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 AutoCloseable
      Specified by:
      close in interface Closeable

    • 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 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:
      IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())
      See Also:

    • getOutputStream

      public 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:
      IllegalStateException - if this uploader has already been closed (see close()) or finished (see finish())
      See Also:

    • finish

      public R finish() throws X, 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())