com.dropbox.core.v1

Class DbxClientV1

java.lang.Object

com.dropbox.core.v1.DbxClientV1

public final class DbxClientV1
extends java.lang.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	DbxClientV1.Downloader A pairing of a metadata and main content of a download.
static class	DbxClientV1.IODbxException A DbxException wrapped inside an IOException.
static class	DbxClientV1.Uploader For uploading file content to Dropbox.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	USER_AGENT_ID

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
long	chunkedUploadAppend(java.lang.String uploadId, long uploadOffset, byte[] data) Equivalent to chunkedUploadAppend(uploadId, uploadOffset, data, 0, data.length).
long	chunkedUploadAppend(java.lang.String uploadId, long uploadOffset, byte[] data, int dataOffset, int dataLength) Append data to a chunked upload session.
<E extends java.lang.Throwable> long	chunkedUploadAppend(java.lang.String uploadId, long uploadOffset, long chunkSize, DbxStreamWriter<E> writer) Append a chunk of data to a chunked upload session.
DbxEntry.File	chunkedUploadFinish(java.lang.String targetPath, DbxWriteMode writeMode, java.lang.String uploadId) Creates a file in the user's Dropbox at the given path, with file data previously uploaded via chunkedUploadFirst(byte[]) and chunkedUploadAppend(java.lang.String, long, byte[]).
java.lang.String	chunkedUploadFirst(byte[] data) Equivalent to chunkedUploadFirst(data, 0, data.length).
java.lang.String	chunkedUploadFirst(byte[] data, int dataOffset, int dataLength) Upload the first chunk of a multi-chunk upload.
<E extends java.lang.Throwable> java.lang.String	chunkedUploadFirst(int chunkSize, DbxStreamWriter<E> writer) Upload the first chunk of a multi-chunk upload.
DbxEntry	copy(java.lang.String fromPath, java.lang.String toPath) Copy a file or folder from one path in Dropbox to another path in Dropbox.
DbxEntry	copyFromCopyRef(java.lang.String copyRef, java.lang.String toPath) Create a file or folder at toPath based on the given copy ref (created with createCopyRef(java.lang.String)).
java.lang.String	createCopyRef(java.lang.String path) Creates and returns a "copy ref" to a file.
DbxEntry.Folder	createFolder(java.lang.String path) Create a new folder in Dropbox.
java.lang.String	createShareableUrl(java.lang.String path) Creates and returns a publicly-shareable URL to a file or folder's "preview page".
DbxUrlWithExpiration	createTemporaryDirectUrl(java.lang.String path) Creates and returns a publicly-shareable URL to a file's contents.
void	delete(java.lang.String path) Delete a file or folder from Dropbox.
void	disableAccessToken() Disable the access token that you constructed this DbxClientV1 with.
<T> T	doPost(java.lang.String host, java.lang.String path, java.lang.String[] params, java.util.ArrayList<HttpRequestor.Header> headers, DbxRequestUtil.ResponseHandler<T> handler)
<E extends java.lang.Throwable> DbxEntry.File	finishUploadFile(DbxClientV1.Uploader uploader, DbxStreamWriter<E> writer)
java.lang.String	getAccessToken() Returns the DbxAccessToken that was passed in to the constructor.
DbxAccountInfo	getAccountInfo() Retrieve the user's account information.
DbxDelta<DbxEntry>	getDelta(java.lang.String cursor) Same as getDelta(String, boolean) with includeMediaInfo set to false.
DbxDelta<DbxEntry>	getDelta(java.lang.String cursor, boolean includeMediaInfo) Return "delta" entries for the contents of a user's Dropbox.
<C> DbxDeltaC<C>	getDeltaC(Collector<DbxDeltaC.Entry<DbxEntry>,C> collector, java.lang.String cursor) Same as getDeltaC(Collector, String, boolean) with includeMediaInfo set to false.
<C> DbxDeltaC<C>	getDeltaC(Collector<DbxDeltaC.Entry<DbxEntry>,C> collector, java.lang.String cursor, boolean includeMediaInfo) A more generic version of getDelta(java.lang.String, boolean).
<C> DbxDeltaC<C>	getDeltaCWithPathPrefix(Collector<DbxDeltaC.Entry<DbxEntry>,C> collector, java.lang.String cursor, java.lang.String pathPrefix) Same as getDeltaCWithPathPrefix(Collector, String, String, boolean) with includeMediaInfo set to false.
<C> DbxDeltaC<C>	getDeltaCWithPathPrefix(Collector<DbxDeltaC.Entry<DbxEntry>,C> collector, java.lang.String cursor, java.lang.String pathPrefix, boolean includeMediaInfo) A more generic version of getDeltaWithPathPrefix(java.lang.String, java.lang.String, boolean).
java.lang.String	getDeltaLatestCursor() Same as getDeltaLatestCursor(boolean) with includeMediaInfo set to false.
java.lang.String	getDeltaLatestCursor(boolean includeMediaInfo) Get a cursor for the current state of a user's Dropbox folder.
java.lang.String	getDeltaLatestCursorWithPathPrefix(java.lang.String pathPrefix) Same as getDeltaLatestCursorWithPathPrefix(String, boolean) with includeMediaInfo set to false.
java.lang.String	getDeltaLatestCursorWithPathPrefix(java.lang.String pathPrefix, boolean includeMediaInfo) Same as getDeltaLatestCursor(boolean), except the cursor is limited to files and folders whose paths are equal to or under the specified pathPrefix.
DbxDelta<DbxEntry>	getDeltaWithPathPrefix(java.lang.String cursor, java.lang.String pathPrefix) Same as getDeltaWithPathPrefix(String, String, boolean) with includeMediaInfo set to false.
DbxDelta<DbxEntry>	getDeltaWithPathPrefix(java.lang.String cursor, java.lang.String pathPrefix, boolean includeMediaInfo) Same as getDelta(java.lang.String, boolean), except results are limited to files and folders whose paths are equal to or under the specified pathPrefix.
DbxEntry.File	getFile(java.lang.String path, java.lang.String rev, java.io.OutputStream target) Retrieves a file's content and writes it to the given OutputStream.
DbxHost	getHost() Returns the DbxHost that was passed in to the constructor.
DbxLongpollDeltaResult	getLongpollDelta(java.lang.String cursor, int timeout) Waits for changes to files on an account, starting from the state represented by cursor.
DbxEntry	getMetadata(java.lang.String path) Same as getMetadata(String, boolean) with includeMediaInfo set to false.
DbxEntry	getMetadata(java.lang.String path, boolean includeMediaInfo) Get the file or folder metadata for a given path.
DbxEntry.WithChildren	getMetadataWithChildren(java.lang.String path) Same as getMetadataWithChildren(String, boolean) with includeMediaInfo set to false.
DbxEntry.WithChildren	getMetadataWithChildren(java.lang.String path, boolean includeMediaInfo) 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(java.lang.String path, boolean includeMediaInfo, Collector<DbxEntry,? extends C> collector) Same as getMetadataWithChildren(java.lang.String, boolean) 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.
<C> DbxEntry.WithChildrenC<C>	getMetadataWithChildrenC(java.lang.String path, Collector<DbxEntry,? extends C> collector) Same as getMetadataWithChildrenC(String, boolean, Collector) with includeMediaInfo set to false.
Maybe<DbxEntry.WithChildren>	getMetadataWithChildrenIfChanged(java.lang.String path, boolean includeMediaInfo, java.lang.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).
Maybe<DbxEntry.WithChildren>	getMetadataWithChildrenIfChanged(java.lang.String path, java.lang.String previousFolderHash) Same as getMetadataWithChildrenIfChanged(String, boolean, String) with includeMediaInfo set to false.
<C> Maybe<DbxEntry.WithChildrenC<C>>	getMetadataWithChildrenIfChangedC(java.lang.String path, boolean includeMediaInfo, java.lang.String previousFolderHash, Collector<DbxEntry,? extends C> collector) Same as getMetadataWithChildrenIfChanged(java.lang.String, boolean, 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.
<C> Maybe<DbxEntry.WithChildrenC<C>>	getMetadataWithChildrenIfChangedC(java.lang.String path, java.lang.String previousFolderHash, Collector<DbxEntry,? extends C> collector) Same as getMetadataWithChildrenIfChangedC(String, boolean, String, Collector) with includeMediaInfo set to false.
DbxRequestConfig	getRequestConfig() Returns the DbxRequestConfig that was passed in to the constructor.
java.util.List<DbxEntry.File>	getRevisions(java.lang.String path) Gets the metadata for the current and past revisions of a file (up to some limit) at a given path.
DbxEntry.File	getThumbnail(DbxThumbnailSize sizeBound, DbxThumbnailFormat format, java.lang.String path, java.lang.String rev, java.io.OutputStream target) Downloads a thumbnail for the image file at the given path in Dropbox.
DbxEntry	move(java.lang.String fromPath, java.lang.String toPath) Move a file or folder from one path in Dropbox to another path in Dropbox.
DbxEntry.File	restoreFile(java.lang.String path, java.lang.String rev) Takes a copy of the file at the given revision and saves it over the current latest copy.
java.util.List<DbxEntry>	searchFileAndFolderNames(java.lang.String basePath, java.lang.String query) Returns metadata for all files and folders whose name matches the query string.
DbxClientV1.Downloader	startGetFile(java.lang.String path, java.lang.String rev) Retrieve a file's content and content metadata.
DbxClientV1.Downloader	startGetThumbnail(DbxThumbnailSize sizeBound, DbxThumbnailFormat format, java.lang.String path, java.lang.String rev) Similar to getThumbnail(com.dropbox.core.v1.DbxThumbnailSize, com.dropbox.core.v1.DbxThumbnailFormat, java.lang.String, java.lang.String, java.io.OutputStream), except the thumbnail contents are returned via a DbxClientV1.Downloader.
DbxClientV1.Uploader	startUploadFile(java.lang.String targetPath, DbxWriteMode writeMode, long numBytes) Start an API request to upload a file to Dropbox.
DbxClientV1.Uploader	startUploadFileChunked(int chunkSize, java.lang.String targetPath, DbxWriteMode writeMode, long numBytes) Similar to startUploadFile(java.lang.String, com.dropbox.core.v1.DbxWriteMode, long), except always uses the chunked upload API.
DbxClientV1.Uploader	startUploadFileChunked(java.lang.String targetPath, DbxWriteMode writeMode, long numBytes) Similar to startUploadFile(java.lang.String, com.dropbox.core.v1.DbxWriteMode, long), except always uses the chunked upload API.
DbxClientV1.Uploader	startUploadFileSingle(java.lang.String targetPath, DbxWriteMode writeMode, long numBytes) Similar to uploadFile(java.lang.String, com.dropbox.core.v1.DbxWriteMode, long, java.io.InputStream), except always uses the /files_put API call.
<E extends java.lang.Throwable> DbxEntry.File	uploadFile(java.lang.String targetPath, DbxWriteMode writeMode, long numBytes, DbxStreamWriter<E> writer) Upload file contents to Dropbox, getting contents from the given DbxStreamWriter.
DbxEntry.File	uploadFile(java.lang.String targetPath, DbxWriteMode writeMode, long numBytes, java.io.InputStream contents) A wrapper around uploadFile(String, DbxWriteMode, long, DbxStreamWriter) that lets you pass in an InputStream.
<E extends java.lang.Throwable> DbxEntry.File	uploadFileChunked(int chunkSize, java.lang.String targetPath, DbxWriteMode writeMode, long numBytes, DbxStreamWriter<E> writer) Similar to uploadFile(java.lang.String, com.dropbox.core.v1.DbxWriteMode, long, java.io.InputStream), except always uses the chunked upload API.
<E extends java.lang.Throwable> DbxEntry.File	uploadFileChunked(java.lang.String targetPath, DbxWriteMode writeMode, long numBytes, DbxStreamWriter<E> writer) Similar to uploadFile(java.lang.String, com.dropbox.core.v1.DbxWriteMode, long, java.io.InputStream), except always uses the chunked upload API.
<E extends java.lang.Throwable> DbxEntry.File	uploadFileSingle(java.lang.String targetPath, DbxWriteMode writeMode, long numBytes, DbxStreamWriter<E> writer)

Methods inherited from class java.lang.Object

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

Field Detail

USER_AGENT_ID

public static final java.lang.String USER_AGENT_ID

See Also:

Constant Field Values

Constructor Detail

DbxClientV1

public DbxClientV1(DbxRequestConfig requestConfig,
                   java.lang.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.

DbxClientV1

public DbxClientV1(DbxRequestConfig requestConfig,
                   java.lang.String accessToken,
                   DbxHost host)

The same as DbxClientV1(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 java.lang.String getAccessToken()

Returns the DbxAccessToken that was passed in to the constructor.

getHost

public DbxHost getHost()

Returns the DbxHost that was passed in to the constructor.

getMetadata

public DbxEntry getMetadata(java.lang.String path,
                            boolean includeMediaInfo)
                     throws DbxException

Get the file or folder metadata for a given path.

 DbxClientV1 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 DbxPathV1).

includeMediaInfo - If true, then if the return value is a DbxEntry.File, it might have its photoInfo and mediaInfo fields filled in.

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

getMetadata

public DbxEntry getMetadata(java.lang.String path)
                     throws DbxException

Same as getMetadata(String, boolean) with includeMediaInfo set to false.

Throws:

DbxException

getMetadataWithChildren

public DbxEntry.WithChildren getMetadataWithChildren(java.lang.String path,
                                                     boolean includeMediaInfo)
                                              throws DbxException

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

 DbxClientV1 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 DbxPathV1).

includeMediaInfo - If true, then if the return value is a DbxEntry.File, it might have its photoInfo and mediaInfo fields filled in.

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

getMetadataWithChildren

public DbxEntry.WithChildren getMetadataWithChildren(java.lang.String path)
                                              throws DbxException

Same as getMetadataWithChildren(String, boolean) with includeMediaInfo set to false.

Throws:

DbxException

getMetadataWithChildrenC

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

Same as getMetadataWithChildren(java.lang.String, boolean) 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

getMetadataWithChildrenC

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

Same as getMetadataWithChildrenC(String, boolean, Collector) with includeMediaInfo set to false.

Throws:

DbxException

getMetadataWithChildrenIfChanged

public Maybe<DbxEntry.WithChildren> getMetadataWithChildrenIfChanged(java.lang.String path,
                                                                     boolean includeMediaInfo,
                                                                     java.lang.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 DbxPathV1).

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

getMetadataWithChildrenIfChanged

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

Same as getMetadataWithChildrenIfChanged(String, boolean, String) with includeMediaInfo set to false.

Throws:

DbxException

getMetadataWithChildrenIfChangedC

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

Same as getMetadataWithChildrenIfChanged(java.lang.String, boolean, 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

getMetadataWithChildrenIfChangedC

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

Same as getMetadataWithChildrenIfChangedC(String, boolean, String, Collector) with includeMediaInfo set to false.

Throws:

DbxException

getAccountInfo

public DbxAccountInfo getAccountInfo()
                              throws DbxException

Retrieve the user's account information.

Throws:

DbxException

disableAccessToken

public void disableAccessToken()
                        throws DbxException

Disable the access token that you constructed this DbxClientV1 with. After calling this, API calls made with this DbxClientV1 will fail.

Throws:

DbxException

getFile

public DbxEntry.File getFile(java.lang.String path,
                             java.lang.String rev,
                             java.io.OutputStream target)
                      throws DbxException,
                             java.io.IOException

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

 DbxClientV1 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:

rev - The rev of the file to retrieve, or null if you want the latest revision of the file.

Returns:

The downloaded file's metadata, or null

Throws:

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

DbxException

startGetFile

public DbxClientV1.Downloader startGetFile(java.lang.String path,
                                           java.lang.String rev)
                                    throws DbxException

Retrieve a file's content and content metadata. You must call the DbxClientV1.Downloader's close() method; use a try/finally.

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

Parameters:

rev - The rev 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 DbxPathV1).

Returns:

An object that can be used to download the file contents, or null if there is no file at the requested path.

Throws:

DbxException

uploadFile

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

A wrapper around uploadFile(String, DbxWriteMode, long, DbxStreamWriter) that lets you pass in an InputStream. The entire stream contents will be uploaded.

 DbxClientV1 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 DbxPathV1). 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:

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

DbxException

uploadFile

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

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

 DbxClientV1 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 DbxPathV1). 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 DbxClientV1.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.

Throws:

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

DbxException

E extends java.lang.Throwable

startUploadFile

public DbxClientV1.Uploader startUploadFile(java.lang.String targetPath,
                                            DbxWriteMode writeMode,
                                            long numBytes)
                                     throws DbxException

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

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

 DbxClientV1 dbxClient = ...
 DbxClientV1.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 DbxPathV1). 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 DbxClientV1.Uploader. Use -1 if you don't know ahead of time.

Throws:

DbxException

finishUploadFile

public <E extends java.lang.Throwable> DbxEntry.File finishUploadFile(DbxClientV1.Uploader uploader,
                                                                      DbxStreamWriter<E> writer)
                                                               throws DbxException,
                                                                      E extends java.lang.Throwable

Throws:

DbxException

E extends java.lang.Throwable

startUploadFileSingle

public DbxClientV1.Uploader startUploadFileSingle(java.lang.String targetPath,
                                                  DbxWriteMode writeMode,
                                                  long numBytes)
                                           throws DbxException

Similar to uploadFile(java.lang.String, com.dropbox.core.v1.DbxWriteMode, long, java.io.InputStream), except always uses the /files_put API call. One difference is that numBytes must not be negative.

Throws:

DbxException

uploadFileSingle

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

Throws:

DbxException

E extends java.lang.Throwable

chunkedUploadFirst

public java.lang.String chunkedUploadFirst(byte[] data)
                                    throws DbxException

Equivalent to chunkedUploadFirst(data, 0, data.length).

Throws:

DbxException

chunkedUploadFirst

public java.lang.String chunkedUploadFirst(byte[] data,
                                           int dataOffset,
                                           int dataLength)
                                    throws DbxException

Upload the first chunk of a multi-chunk upload.

Parameters:

data - The data to append.

dataOffset - The start offset in data to read from.

dataLength - The number of bytes to read from data, starting from dataOffset.

Returns:

The ID designated by the Dropbox server to identify the chunked upload.

Throws:

DbxException

chunkedUploadFirst

public <E extends java.lang.Throwable> java.lang.String chunkedUploadFirst(int chunkSize,
                                                                           DbxStreamWriter<E> writer)
                                                                    throws DbxException,
                                                                           E extends java.lang.Throwable

Upload the first chunk of a multi-chunk upload.

Parameters:

chunkSize - The number of bytes you're going to upload in this chunk.

writer - A callback that will be called when it's time to actually write out the body of the chunk.

Returns:

The ID designated by the Dropbox server to identify the chunked upload.

Throws:

DbxException

E extends java.lang.Throwable

chunkedUploadAppend

public long chunkedUploadAppend(java.lang.String uploadId,
                                long uploadOffset,
                                byte[] data)
                         throws DbxException

Equivalent to chunkedUploadAppend(uploadId, uploadOffset, data, 0, data.length).

Throws:

DbxException

chunkedUploadAppend

public long chunkedUploadAppend(java.lang.String uploadId,
                                long uploadOffset,
                                byte[] data,
                                int dataOffset,
                                int dataLength)
                         throws DbxException

Append data to a chunked upload session.

Parameters:

uploadId - The identifier returned by chunkedUploadFirst(byte[]) to identify the chunked upload session.

uploadOffset - The current number of bytes uploaded to the chunked upload session. The server checks this value to make sure it is correct. If it is correct, the contents of data is appended and -1 is returned. If it is incorrect, the correct offset is returned.

data - The data to append.

dataOffset - The start offset in data to read from.

dataLength - The number of bytes to read from data, starting from dataOffset.

Returns:

If everything goes correctly, returns -1. If the given offset didn't match the actual number of bytes in the chunked upload session, returns the correct number of bytes.

Throws:

DbxException

chunkedUploadAppend

public <E extends java.lang.Throwable> long chunkedUploadAppend(java.lang.String uploadId,
                                                                long uploadOffset,
                                                                long chunkSize,
                                                                DbxStreamWriter<E> writer)
                                                         throws DbxException,
                                                                E extends java.lang.Throwable

Append a chunk of data to a chunked upload session.

Parameters:

uploadId - The identifier returned by chunkedUploadFirst(byte[]) to identify the chunked upload session.

uploadOffset - The current number of bytes uploaded to the chunked upload session. The server checks this value to make sure it is correct. If it is correct, the contents of data is appended and -1 is returned. If it is incorrect, the correct offset is returned.

chunkSize - The size of the chunk.

writer - A callback that will be called when it's time to actually write out the body of the chunk.

Returns:

If everything goes correctly, returns -1. If the given offset didn't match the actual number of bytes in the chunked upload session, returns the correct number of bytes.

Throws:

DbxException

E extends java.lang.Throwable

chunkedUploadFinish

public DbxEntry.File chunkedUploadFinish(java.lang.String targetPath,
                                         DbxWriteMode writeMode,
                                         java.lang.String uploadId)
                                  throws DbxException

Creates a file in the user's Dropbox at the given path, with file data previously uploaded via chunkedUploadFirst(byte[]) and chunkedUploadAppend(java.lang.String, long, byte[]).

Parameters:

targetPath - The path to the file on Dropbox (see DbxPathV1). 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.

uploadId - The identifier returned by chunkedUploadFirst(byte[]) to identify the uploaded data.

Throws:

DbxException

startUploadFileChunked

public DbxClientV1.Uploader startUploadFileChunked(java.lang.String targetPath,
                                                   DbxWriteMode writeMode,
                                                   long numBytes)

Similar to startUploadFile(java.lang.String, com.dropbox.core.v1.DbxWriteMode, long), except always uses the chunked upload API.

startUploadFileChunked

public DbxClientV1.Uploader startUploadFileChunked(int chunkSize,
                                                   java.lang.String targetPath,
                                                   DbxWriteMode writeMode,
                                                   long numBytes)

Similar to startUploadFile(java.lang.String, com.dropbox.core.v1.DbxWriteMode, long), except always uses the chunked upload API.

uploadFileChunked

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

Similar to uploadFile(java.lang.String, com.dropbox.core.v1.DbxWriteMode, long, java.io.InputStream), except always uses the chunked upload API.

Throws:

DbxException

E extends java.lang.Throwable

uploadFileChunked

public <E extends java.lang.Throwable> DbxEntry.File uploadFileChunked(int chunkSize,
                                                                       java.lang.String targetPath,
                                                                       DbxWriteMode writeMode,
                                                                       long numBytes,
                                                                       DbxStreamWriter<E> writer)
                                                                throws DbxException,
                                                                       E extends java.lang.Throwable

Similar to uploadFile(java.lang.String, com.dropbox.core.v1.DbxWriteMode, long, java.io.InputStream), except always uses the chunked upload API.

Throws:

DbxException

E extends java.lang.Throwable

getDelta

public DbxDelta<DbxEntry> getDelta(java.lang.String cursor,
                                   boolean includeMediaInfo)
                            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

getDelta

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

Same as getDelta(String, boolean) with includeMediaInfo set to false.

Throws:

DbxException

getDeltaC

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

A more generic version of getDelta(java.lang.String, boolean). You provide a collector, which lets you process the delta entries as they arrive over the network.

Throws:

DbxException

getDeltaC

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

Same as getDeltaC(Collector, String, boolean) with includeMediaInfo set to false.

Throws:

DbxException

getDeltaWithPathPrefix

public DbxDelta<DbxEntry> getDeltaWithPathPrefix(java.lang.String cursor,
                                                 java.lang.String pathPrefix,
                                                 boolean includeMediaInfo)
                                          throws DbxException

Same as getDelta(java.lang.String, boolean), except results are limited to files and folders whose paths are equal to or under the specified pathPrefix.

The pathPrefix is fixed for a given cursor. Whatever pathPrefix you use on the first call to getDelta() must also be passed in on subsequent calls that use the returned cursor.

Parameters:

pathPrefix - A path on Dropbox to limit results to.

Throws:

DbxException

getDeltaWithPathPrefix

public DbxDelta<DbxEntry> getDeltaWithPathPrefix(java.lang.String cursor,
                                                 java.lang.String pathPrefix)
                                          throws DbxException

Same as getDeltaWithPathPrefix(String, String, boolean) with includeMediaInfo set to false.

Throws:

DbxException

getDeltaCWithPathPrefix

public <C> DbxDeltaC<C> getDeltaCWithPathPrefix(Collector<DbxDeltaC.Entry<DbxEntry>,C> collector,
                                                java.lang.String cursor,
                                                java.lang.String pathPrefix,
                                                boolean includeMediaInfo)
                                         throws DbxException

A more generic version of getDeltaWithPathPrefix(java.lang.String, java.lang.String, boolean). You provide a collector, which lets you process the delta entries as they arrive over the network.

Throws:

DbxException

getDeltaCWithPathPrefix

public <C> DbxDeltaC<C> getDeltaCWithPathPrefix(Collector<DbxDeltaC.Entry<DbxEntry>,C> collector,
                                                java.lang.String cursor,
                                                java.lang.String pathPrefix)
                                         throws DbxException

Same as getDeltaCWithPathPrefix(Collector, String, String, boolean) with includeMediaInfo set to false.

Throws:

DbxException

getDeltaLatestCursor

public java.lang.String getDeltaLatestCursor(boolean includeMediaInfo)
                                      throws DbxException

Get a cursor for the current state of a user's Dropbox folder. Can be passed to getDelta(java.lang.String, boolean) to retrieve changes since this method was called.

Throws:

DbxException

getDeltaLatestCursor

public java.lang.String getDeltaLatestCursor()
                                      throws DbxException

Same as getDeltaLatestCursor(boolean) with includeMediaInfo set to false.

Throws:

DbxException

getDeltaLatestCursorWithPathPrefix

public java.lang.String getDeltaLatestCursorWithPathPrefix(java.lang.String pathPrefix,
                                                           boolean includeMediaInfo)
                                                    throws DbxException

Same as getDeltaLatestCursor(boolean), except the cursor is limited to files and folders whose paths are equal to or under the specified pathPrefix.

Parameters:

pathPrefix - A path on Dropbox to limit the cursor to.

Throws:

DbxException

getDeltaLatestCursorWithPathPrefix

public java.lang.String getDeltaLatestCursorWithPathPrefix(java.lang.String pathPrefix)
                                                    throws DbxException

Same as getDeltaLatestCursorWithPathPrefix(String, boolean) with includeMediaInfo set to false.

Throws:

DbxException

getLongpollDelta

public DbxLongpollDeltaResult getLongpollDelta(java.lang.String cursor,
                                               int timeout)
                                        throws DbxException

Waits for changes to files on an account, starting from the state represented by cursor.

Parameters:

cursor - A cursor returned by ono of the "delta" methods.

timeout - How long poll should run before timing out, in seconds.

Throws:

DbxException

getThumbnail

public DbxEntry.File getThumbnail(DbxThumbnailSize sizeBound,
                                  DbxThumbnailFormat format,
                                  java.lang.String path,
                                  java.lang.String rev,
                                  java.io.OutputStream target)
                           throws DbxException,
                                  java.io.IOException

Downloads a thumbnail for the image file at the given path in Dropbox.

Parameters:

sizeBound - The returned thumbnail will never be greater than the dimensions given here.

format - The image format to use for thumbnail data.

path - The path to the image file on Dropbox.

rev - The rev of the file on Dropbox or null if you want the latest revision of the file.

target - The stream to write the thumbnail image data to.

Returns:

The metadata for the original file (not the thumbnail) or null if there is no file at that path.

Throws:

DbxException

java.io.IOException

startGetThumbnail

public DbxClientV1.Downloader startGetThumbnail(DbxThumbnailSize sizeBound,
                                                DbxThumbnailFormat format,
                                                java.lang.String path,
                                                java.lang.String rev)
                                         throws DbxException

Similar to getThumbnail(com.dropbox.core.v1.DbxThumbnailSize, com.dropbox.core.v1.DbxThumbnailFormat, java.lang.String, java.lang.String, java.io.OutputStream), except the thumbnail contents are returned via a DbxClientV1.Downloader.

Throws:

DbxException

getRevisions

public java.util.List<DbxEntry.File> getRevisions(java.lang.String path)
                                           throws DbxException

Gets the metadata for the current and past revisions of a file (up to some limit) at a given path.

Parameters:

path - The Dropbox path that you want file revision metadata for.

Returns:

A list of metadata objects, one for each file revision.

Throws:

DbxException

restoreFile

public DbxEntry.File restoreFile(java.lang.String path,
                                 java.lang.String rev)
                          throws DbxException

Takes a copy of the file at the given revision and saves it over the current latest copy. This will create a new revision, but the file contents will match the revision you specified.

Parameters:

path - The Dropbox path of the file to restore.

rev - The revision of the file you want to use to overwrite the latest revision.

Returns:

If the specified path/rev couldn't be found, return null. Otherwise, return metadata for the newly-created latest revision of the file.

Throws:

DbxException

searchFileAndFolderNames

public java.util.List<DbxEntry> searchFileAndFolderNames(java.lang.String basePath,
                                                         java.lang.String query)
                                                  throws DbxException

Returns metadata for all files and folders whose name matches the query string.

Parameters:

basePath - The path to search under (recursively). Pass in "/" to search everything.

query - A space-separated list of substrings to search for. A file matches only if it contains all the substrings.

Returns:

The list of metadata entries that match the search query.

Throws:

DbxException

createShareableUrl

public java.lang.String createShareableUrl(java.lang.String path)
                                    throws DbxException

Creates and returns a publicly-shareable URL to a file or folder's "preview page". This URL can be used without authentication. The preview page may contain a thumbnail or some other preview of the file, along with a link to download the actual filel.

Parameters:

path - The Dropbox path to a file or folder.

Returns:

If there is no file or folder at that path, return null. Otherwise return a shareable URL.

Throws:

DbxException

createTemporaryDirectUrl

public DbxUrlWithExpiration createTemporaryDirectUrl(java.lang.String path)
                                              throws DbxException

Creates and returns a publicly-shareable URL to a file's contents. This URL can be used without authentication. This link will stop working after a few hours.

Parameters:

path - The Dropbox path to a file.

Returns:

If there is no file at that path, return null. Otherwise return a shareable URL along with the expiration time.

Throws:

DbxException

createCopyRef

public java.lang.String createCopyRef(java.lang.String path)
                               throws DbxException

Creates and returns a "copy ref" to a file. A copy ref can be used to copy a file across different Dropbox accounts without downloading and re-uploading.

For example, create a DbxClientV1 using the access token from one account and call createCopyRef. Then, create a DbxClientV1 using the access token for another account and call copyFromCopyRef using the copy ref.

A copy ref created by an app can only be used by that app.

Parameters:

path - The Dropbox path to a file.

Returns:

The copy ref's identifier, suitable for passing in to copyFromCopyRef(java.lang.String, java.lang.String), or null if the specified path does not exist.

Throws:

DbxException

copy

public DbxEntry copy(java.lang.String fromPath,
                     java.lang.String toPath)
              throws DbxException

Copy a file or folder from one path in Dropbox to another path in Dropbox.

Returns:

If successful, returns the metadata for new copy of the file or folder, otherwise returns null.

Throws:

DbxException

copyFromCopyRef

public DbxEntry copyFromCopyRef(java.lang.String copyRef,
                                java.lang.String toPath)
                         throws DbxException

Create a file or folder at toPath based on the given copy ref (created with createCopyRef(java.lang.String)).

Throws:

DbxException

createFolder

public DbxEntry.Folder createFolder(java.lang.String path)
                             throws DbxException

Create a new folder in Dropbox.

Returns:

If successful, returns the metadata for the newly created folder, otherwise returns null.

Throws:

DbxException

delete

public void delete(java.lang.String path)
            throws DbxException

Delete a file or folder from Dropbox.

Throws:

DbxException

move

public DbxEntry move(java.lang.String fromPath,
                     java.lang.String toPath)
              throws DbxException

Move a file or folder from one path in Dropbox to another path in Dropbox.

Returns:

If successful, returns the metadata for the file or folder at its new location, otherwise returns null.

Throws:

DbxException

doPost

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

Throws:

DbxException