com.dropbox.core

Class DbxClient

java.lang.Object

com.dropbox.core.DbxClient

public final class DbxClient
extends Object

Use this class to make remote calls to the Dropbox API. You'll need an access token first, normally acquired via DbxWebAuth.

This class has no mutable state, so it's thread safe as long as you pass in a thread safe HttpRequestor implementation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DbxClient.Downloader A pairing of the file content's metadata and an InputStream to read the file content.
static class	DbxClient.Uploader For uploading file content to Dropbox.

Constructor Summary

Constructors

Constructor and Description
DbxClient(DbxRequestConfig requestConfig, String accessToken)
DbxClient(DbxRequestConfig requestConfig, String accessToken, DbxHost host) The same as DbxClient(DbxRequestConfig, String) except you can also set the hostnames of the Dropbox API servers.

Method Summary

Methods

Modifier and Type	Method and Description
<T> T	doPost(String host, String path, String[] params, ArrayList<HttpRequestor.Header> headers, DbxRequestUtil.ResponseHandler<T> handler)
String	getAccessToken() Returns the DbxAccessToken that was passed in to the constructor.
DbxAccountInfo	getAccountInfo() Retrieve the user's account information.
DbxDelta<DbxEntry>	getDelta(String cursor) Return "delta" entries for the contents of a user's Dropbox.
<C> DbxDeltaC<C,DbxEntry>	getDeltaC(String cursor, Collector<DbxDeltaC.Entry<DbxEntry>,C> collector) This is a more generic version of getDelta(java.lang.String).
DbxEntry.File	getFile(String path, String revision, OutputStream target) Retrieves a file's content and writes it to the given OutputStream.
DbxEntry	getMetadata(String path) Get the file or folder metadata for a given path.
DbxEntry.WithChildren	getMetadataWithChildren(String path) Get the metadata for a given path; if the path refers to a folder, get all the children's metadata as well.
<C> DbxEntry.WithChildrenC<C>	getMetadataWithChildrenC(String path, Collector<DbxEntry,? extends C> collector) Same as getMetadataWithChildren(java.lang.String) except instead of always returning a list of DbxEntry objects, you specify a Collector that processes the DbxEntry objects one by one and aggregates them however you want.
Maybe<DbxEntry.WithChildren>	getMetadataWithChildrenIfChanged(String path, String previousFolderHash) Get the metadata for a given path and its children if anything has changed since the last time you got them (as determined by the value of DbxEntry.WithChildren.hash from the last result).
<C> Maybe<DbxEntry.WithChildrenC<C>>	getMetadataWithChildrenIfChangedC(String path, String previousFolderHash, Collector<DbxEntry,? extends C> collector) Same as getMetadataWithChildrenIfChanged(java.lang.String, java.lang.String) except instead of always returning a list of DbxEntry objects, you specify a Collector that processes the DbxEntry objects one by one and aggregates them however you want.
DbxRequestConfig	getRequestConfig() Returns the DbxRequestConfig that was passed in to the constructor.
DbxEntry.File	getThumbnail(DbxThumbnailSize size, DbxThumbnailFormat format, String path, String revision, OutputStream target)
DbxClient.Downloader	startGetFile(String path, String revision) Retrieve a file's content and content metadata.
DbxClient.Downloader	startGetThumbnail(DbxThumbnailSize size, DbxThumbnailFormat format, String path, String revision)
DbxClient.Uploader	startUploadFile(String targetPath, DbxWriteMode writeMode, long numBytes) Start an API request to upload a file to Dropbox.
<E extends Throwable> DbxEntry.File	uploadFile(String targetPath, DbxWriteMode writeMode, long numBytes, DbxStreamWriter<E> writer) Upload file contents to Dropbox, getting contents from the given DbxStreamWriter.
DbxEntry.File	uploadFile(String targetPath, DbxWriteMode writeMode, long numBytes, InputStream contents) A wrapper around uploadFile(String, DbxWriteMode, long, DbxStreamWriter) that lets you pass in an InputStream.

Methods inherited from class java.lang.Object

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

Constructor Detail

DbxClient

public DbxClient(DbxRequestConfig requestConfig,
         String accessToken)

Parameters:

accessToken - The OAuth 2 access token (that you got from Dropbox) that gives your app the ability to make Dropbox API calls against some particular user's account. The standard way to get one of these is to use DbxWebAuth to send your user through Dropbox's OAuth 2 authorization flow.

DbxClient

public DbxClient(DbxRequestConfig requestConfig,
         String accessToken,
         DbxHost host)

The same as DbxClient(DbxRequestConfig, String) except you can also set the hostnames of the Dropbox API servers. This is used in testing. You don't normally need to call this.

Method Detail

getRequestConfig

public DbxRequestConfig getRequestConfig()

Returns the DbxRequestConfig that was passed in to the constructor.

getAccessToken

public String getAccessToken()

Returns the DbxAccessToken that was passed in to the constructor.

getMetadata

public DbxEntry getMetadata(String path)
                     throws DbxException

Get the file or folder metadata for a given path.

 DbxClient dbxClient = ...
 DbxEntry entry = dbxClient.getMetadata("/Photos");
 if (entry == null) {
     System.out.println("No file or folder at that path.");
 } else {
     System.out.print(entry.toStringMultiline());
 }
 

Parameters:

path - The path to the file or folder (see DbxPath).

Returns:

If there is a file or folder at the given path, return the metadata for that path. If there is no file or folder there, return null.

Throws:

DbxException

getMetadataWithChildren

public DbxEntry.WithChildren getMetadataWithChildren(String path)
                                              throws DbxException

Get the metadata for a given path; if the path refers to a folder, get all the children's metadata as well.

 DbxClient dbxClient = ...
 DbxEntry entry = dbxClient.getMetadata("/Photos");
 if (entry == null) {
     System.out.println("No file or folder at that path.");
 } else {
     System.out.print(entry.toStringMultiline());
 }
 

Parameters:

path - The path (starting with "/") to the file or folder (see DbxPath).

Returns:

If there is no file or folder at the given path, return null. Otherwise, return the metadata for that path and the metadata for all its immediate children (if it's a folder).

Throws:

DbxException

getMetadataWithChildrenC

public <C> DbxEntry.WithChildrenC<C> getMetadataWithChildrenC(String path,
                                                     Collector<DbxEntry,? extends C> collector)
                                                   throws DbxException

Same as getMetadataWithChildren(java.lang.String) except instead of always returning a list of DbxEntry objects, you specify a Collector that processes the DbxEntry objects one by one and aggregates them however you want.

This allows your to process the DbxEntry values as they arrive, instead of having to wait for the entire API call to finish before processing the first one. Be careful, though, because the API call may fail in the middle (after you've already processed some entries). Make sure your code can handle that situation. For example, if you're inserting stuff into a database as they arrive, you might want do everything in a transaction and commit only if the entire call succeeds.

Throws:

DbxException

getMetadataWithChildrenIfChanged

public Maybe<DbxEntry.WithChildren> getMetadataWithChildrenIfChanged(String path,
                                                            String previousFolderHash)
                                                              throws DbxException

Get the metadata for a given path and its children if anything has changed since the last time you got them (as determined by the value of DbxEntry.WithChildren.hash from the last result).

Parameters:

path - The path (starting with "/") to the file or folder (see DbxPath).

previousFolderHash - The value of DbxEntry.WithChildren.hash from the last time you got the metadata for this folder (and children).

Returns:

Never returns null. If the folder at the given path hasn't changed since you last retrieved it (i.e. its contents match previousFolderHash), return Maybe.Nothing. If it doesn't match previousFolderHash return either Maybe.Just(null) if there's nothing there or Maybe.Just with the metadata.

Throws:

DbxException

getMetadataWithChildrenIfChangedC

public <C> Maybe<DbxEntry.WithChildrenC<C>> getMetadataWithChildrenIfChangedC(String path,
                                                                     String previousFolderHash,
                                                                     Collector<DbxEntry,? extends C> collector)
                                                                   throws DbxException

Same as getMetadataWithChildrenIfChanged(java.lang.String, java.lang.String) except instead of always returning a list of DbxEntry objects, you specify a Collector that processes the DbxEntry objects one by one and aggregates them however you want.

This allows your to process the DbxEntry values as they arrive, instead of having to wait for the entire API call to finish before processing the first one. Be careful, though, because the API call may fail in the middle (after you've already processed some entries). Make sure your code can handle that situation. For example, if you're inserting stuff into a database as they arrive, you might want do everything in a transaction and commit only if the entire call succeeds.

Throws:

DbxException

getAccountInfo

public DbxAccountInfo getAccountInfo()
                              throws DbxException

Retrieve the user's account information.

Throws:

DbxException

getFile

public DbxEntry.File getFile(String path,
                    String revision,
                    OutputStream target)
                      throws DbxException,
                             IOException

Retrieves a file's content and writes it to the given OutputStream.

 DbxClient dbxClient = ...
 DbxEntry.File md;
 File target = new File("Copy of House.jpeg");
 OutputStream out = new FileOutputStream(target);
 try {
     md = dbxClient.getFile("/Photos/House.jpeg", out);
 }
 finally {
     out.close();
 }
 

Parameters:

revision - The DbxEntry.File.revisionrevision} of the file to retrieve, or null if you want the latest revision of the file.

Throws:

IOException - If there's an error writing to target.

DbxException

startGetFile

public DbxClient.Downloader startGetFile(String path,
                                String revision)
                                  throws DbxException

Retrieve a file's content and content metadata. Returns a DbxClient.Downloader which is just an InputStream (can be used to read the file contents) and a DbxEntry.File (the file's metadata).

You need to close the DbxClient.Downloader yourself. Use a try/finally to make sure you close it in all cases.

 DbxClient dbxClient = ...
 DbxClient.Downloader downloader = dbxClient.getFileStart("/ReadMe.txt")
 try {
     printStream(downloader.body)
 }
 finally {
     downloader.close()
 }
 

Parameters:

revision - The DbxEntry.File.revisionrevision} of the file to retrieve, or null if you want the latest revision of the file.

path - The path (starting with "/") to the file or folder on Dropbox. (see DbxPath).

Throws:

DbxException

uploadFile

public DbxEntry.File uploadFile(String targetPath,
                       DbxWriteMode writeMode,
                       long numBytes,
                       InputStream contents)
                         throws DbxException,
                                IOException

A wrapper around uploadFile(String, DbxWriteMode, long, DbxStreamWriter) that lets you pass in an InputStream. The entire stream contents will be uploaded and the stream will be closed automatically (whether or not the upload succeeds or fails).

 DbxClient dbxClient = ...
 File f = new File("ReadMe.txt")
 dbxClient.uploadFile("/ReadMe.txt", DbxWriteMode.add(), f.length(), new FileInputStream(f))
 

Parameters:

targetPath - The path to the file on Dropbox (see DbxPath). If a file at that path already exists on Dropbox, then the writeMode parameter will determine what happens.

writeMode - Determines what to do if there's already a file at the given targetPath.

numBytes - The number of bytes in the given stream. Use -1 if you don't know.

contents - The source of file contents. This stream will be automatically closed (whether or not the upload succeeds).

Throws:

IOException - If there's an error reading from in.

DbxException

uploadFile

public <E extends Throwable> DbxEntry.File uploadFile(String targetPath,
                                             DbxWriteMode writeMode,
                                             long numBytes,
                                             DbxStreamWriter<E> writer)
                         throws DbxException,
                                E extends Throwable

Upload file contents to Dropbox, getting contents from the given DbxStreamWriter.

 DbxClient dbxClient = ...
 // Create a file on Dropbox with 100 3-digit random numbers, one per line.
 final int numRandoms = 100;
 int fileSize = numRandoms * 4;  3 digits, plus a newline
 dbxClient.uploadFile("/Randoms.txt", DbxWriteMode.add(), fileSize,
     new DbxStreamWriter<RuntimeException>() {
         public void write(OutputStream out) throws IOException
         {
             Random rand = new Random();
             PrintWriter pw = new PrintWriter(out);
             for (int i = 0; i < numRandoms; i++) {
                 pw.printf("%03d\n", rand.nextInt(1000));
             }
             pw.flush();
         }
     });
 

Parameters:

targetPath - The path to the file on Dropbox (see DbxPath). If a file at that path already exists on Dropbox, then the writeMode parameter will determine what happens.

writeMode - Determines what to do if there's already a file at the given targetPath.

numBytes - The number of bytes you're going to upload via the returned DbxClient.Uploader. Use -1 if you don't know ahead of time.

writer - A callback that will be called when it's time to actually write out the body of the file. We will always call DbxStreamWriter.close() on it (whether or not the upload succeeds) so you can put resource cleanup code in it (for example, closing an InputStream).

Throws:

E - If writer.write() throws an exception, it will propagate out of this function.

DbxException

E extends Throwable

startUploadFile

public DbxClient.Uploader startUploadFile(String targetPath,
                                 DbxWriteMode writeMode,
                                 long numBytes)
                                   throws DbxException

Start an API request to upload a file to Dropbox. Returns a DbxClient.Uploader object that lets you actually send the file contents via DbxClient.Uploader.body. When you're done copying the file body, call DbxClient.Uploader.finish().

You need to close the DbxClient.Uploader when you're done with it. Use a try/finally to make sure you close it in all cases.

 DbxClient dbxClient = ...
 DbxClient.Uploader uploader = dbxClient.startUploadFile(...)
 DbxEntry.File md;
 try {
     writeMyData(uploader.body);
     md = uploader.finish();
 }
 finally {
     uploader.close();
 }
 

Parameters:

targetPath - The path to the file on Dropbox (see DbxPath). If a file at that path already exists on Dropbox, then the writeMode parameter will determine what happens.

writeMode - Determines what to do if there's already a file at the given targetPath.

numBytes - The number of bytes you're going to upload via the returned DbxClient.Uploader. Use -1 if you don't know ahead of time.

Throws:

DbxException

getDelta

public DbxDelta<DbxEntry> getDelta(String cursor)
                            throws DbxException

Return "delta" entries for the contents of a user's Dropbox. This lets you efficiently keep up with the latest state of the files and folders. See DbxDelta for more documentation on what each entry means.

To start, pass in null for cursor. For subsequent calls To get the next set of delta entries, pass in the cursor returned by the previous call.

To catch up to the current state, keep calling this method until the returned object's hasMore field is false.

If your app is a "Full Dropbox" app, this will return all entries for the user's entire Dropbox folder. If your app is an "App Folder" app, this will only return entries for the App Folder's contents.

Throws:

DbxException

getDeltaC

public <C> DbxDeltaC<C,DbxEntry> getDeltaC(String cursor,
                                  Collector<DbxDeltaC.Entry<DbxEntry>,C> collector)
                                throws DbxException

This is a more generic version of getDelta(java.lang.String). It allows you to specify a collector, which lets you process the delta entries as they arrive over the network, and aggregate them however you want.

Throws:

DbxException

getThumbnail

public DbxEntry.File getThumbnail(DbxThumbnailSize size,
                         DbxThumbnailFormat format,
                         String path,
                         String revision,
                         OutputStream target)
                           throws DbxException,
                                  IOException

Throws:

DbxException

IOException

startGetThumbnail

public DbxClient.Downloader startGetThumbnail(DbxThumbnailSize size,
                                     DbxThumbnailFormat format,
                                     String path,
                                     String revision)
                                       throws DbxException

Throws:

DbxException

doPost

public <T> T doPost(String host,
           String path,
           String[] params,
           ArrayList<HttpRequestor.Header> headers,
           DbxRequestUtil.ResponseHandler<T> handler)
         throws DbxException

Throws:

DbxException