com.dropbox.client2

Class DropboxAPI<SESS_T extends Session>

java.lang.Object

com.dropbox.client2.DropboxAPI<SESS_T>

public class DropboxAPI<SESS_T extends Session>
extends java.lang.Object

Location of the Dropbox API functions. The class is parameterized with the type of session it uses. This will be the same as the type of session you pass into the constructor.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DropboxAPI.Account Information about a user's account.
protected static class	DropboxAPI.BasicUploadRequest
class	DropboxAPI.ChunkedUploader Represents a single chunked upload in progress.
protected static class	DropboxAPI.ChunkedUploadRequest Class representing the uploading of a single chunk of data to Dropbox using the long upload protocol.
static class	DropboxAPI.ChunkedUploadResponse Represents Dropbox's response to a call to the /chunked_upload endpoint, which contains the uploadId of the upload as well as the expected file offset.
static class	DropboxAPI.CreatedCopyRef
static class	DropboxAPI.DeltaEntry<MD> A single entry in a DeltaPage.
static class	DropboxAPI.DeltaPage<MD> A page of DeltaEntrys (returned by delta).
static class	DropboxAPI.DropboxFileInfo Contains info describing a downloaded file.
static class	DropboxAPI.DropboxInputStream An InputStream for a file download that includes the associated DropboxAPI.DropboxFileInfo.
static class	DropboxAPI.DropboxLink Contains a link to a Dropbox stream or share and its expiration date.
static class	DropboxAPI.Entry A metadata entry that describes a file or folder.
static class	DropboxAPI.RequestAndResponse Holds an HttpUriRequest and the associated HttpResponse.
static class	DropboxAPI.ThumbFormat Represents the image format of thumbnails that the API can return.
static class	DropboxAPI.ThumbSize Represents the size of thumbnails that the API can return.
static interface	DropboxAPI.UploadRequest A request to upload a file to Dropbox.

Field Summary

Fields

Modifier and Type	Field and Description
static long	MAX_UPLOAD_SIZE The max upload file size that Dropbox servers can handle, in bytes.
protected static int	METADATA_DEFAULT_LIMIT
static java.lang.String	SDK_VERSION The version of this Dropbox SDK.
protected SESS_T	session
static int	VERSION The version of the API that this code uses.

Constructor Summary

Constructors

Constructor and Description
DropboxAPI(SESS_T session)

Method Summary

Methods

Modifier and Type	Method and Description
DropboxAPI.Account	accountInfo() Returns the DropboxAPI.Account associated with the current Session.
DropboxAPI.Entry	addFromCopyRef(java.lang.String sourceCopyRef, java.lang.String targetPath) Creates a file in the Dropbox that the client is currently connected to, using the contents from a CopyRef created with createCopyRef().
protected void	assertAuthenticated() Throws a DropboxUnlinkedException if the session in this instance is not linked.
DropboxAPI.ChunkedUploadRequest	chunkedUploadRequest(java.io.InputStream is, long length, ProgressListener listener, long offset, java.lang.String uploadId) Creates a request that can upload a single chunk of data to the server via the chunked upload protocol.
DropboxAPI.Entry	copy(java.lang.String fromPath, java.lang.String toPath) Copies a file or folder (and all of the folder's contents) from one path to another.
DropboxAPI.CreatedCopyRef	createCopyRef(java.lang.String sourcePath) Creates a reference to a path that can be used with addFromCopyRef() to copy the contents of the file at that path to a different Dropbox account.
DropboxAPI.Entry	createFolder(java.lang.String path) Creates a new Dropbox folder.
void	delete(java.lang.String path) Deletes a file or folder (and all of the folder's contents).
DropboxAPI.DeltaPage<DropboxAPI.Entry>	delta(java.lang.String cursor) A way of letting you keep up with changes to files and folders in a user's Dropbox.
DropboxAPI.ChunkedUploader	getChunkedUploader(java.io.InputStream is) Identical to getChunkedUploader(InputStream, long), but sets length to -1, meaning the entire inputstream will be read.
DropboxAPI.ChunkedUploader	getChunkedUploader(java.io.InputStream is, long length) Identical to getChunkedUploader(InputStream, long, int), but provides a default chunkSize of 4mb
DropboxAPI.ChunkedUploader	getChunkedUploader(java.io.InputStream is, long length, int chunkSize) Creates a ChunkedUploader using this DropboxAPI's credentials, to upload a file using the chunked upload protocol.
DropboxAPI.DropboxFileInfo	getFile(java.lang.String path, java.lang.String rev, java.io.OutputStream os, ProgressListener listener) Downloads a file from Dropbox, copying it to the output stream.
DropboxAPI.DropboxInputStream	getFileStream(java.lang.String path, java.lang.String rev) Downloads a file from Dropbox.
protected static boolean	getFromMapAsBoolean(java.util.Map<java.lang.String,java.lang.Object> map, java.lang.String name) Helper function to read boolean JSON return values
protected static long	getFromMapAsLong(java.util.Map<java.lang.String,java.lang.Object> map, java.lang.String name) Helper function to read long JSON return values
SESS_T	getSession() Returns the Session that this API is using.
DropboxAPI.DropboxFileInfo	getThumbnail(java.lang.String path, java.io.OutputStream os, DropboxAPI.ThumbSize size, DropboxAPI.ThumbFormat format, ProgressListener listener) Downloads a thumbnail from Dropbox, copying it to the output stream.
DropboxAPI.DropboxInputStream	getThumbnailStream(java.lang.String path, DropboxAPI.ThumbSize size, DropboxAPI.ThumbFormat format) Downloads a thumbnail from Dropbox.
DropboxAPI.DropboxLink	media(java.lang.String path, boolean ssl) Returns a DropboxAPI.DropboxLink for a stream of the given file path (for streaming media files).
DropboxAPI.Entry	metadata(java.lang.String path, int fileLimit, java.lang.String hash, boolean list, java.lang.String rev) Returns the metadata for a file, or for a directory and (optionally) its immediate children.
DropboxAPI.Entry	move(java.lang.String fromPath, java.lang.String toPath) Moves a file or folder (and all of the folder's contents) from one path to another.
DropboxAPI.Entry	putFile(java.lang.String path, java.io.InputStream is, long length, java.lang.String parentRev, ProgressListener listener) Uploads a file to Dropbox.
DropboxAPI.Entry	putFileOverwrite(java.lang.String path, java.io.InputStream is, long length, ProgressListener listener) Uploads a file to Dropbox.
DropboxAPI.UploadRequest	putFileOverwriteRequest(java.lang.String path, java.io.InputStream is, long length, ProgressListener listener) Creates a request to upload a file to Dropbox, which you can then upload() or abort().
DropboxAPI.UploadRequest	putFileRequest(java.lang.String path, java.io.InputStream is, long length, java.lang.String parentRev, ProgressListener listener) Creates a request to upload a file to Dropbox, which you can then upload() or abort().
DropboxAPI.Entry	restore(java.lang.String path, java.lang.String rev) Restores a file to a previous rev.
java.util.List<DropboxAPI.Entry>	revisions(java.lang.String path, int revLimit) Returns a list of metadata for all revs of the path.
java.util.List<DropboxAPI.Entry>	search(java.lang.String path, java.lang.String query, int fileLimit, boolean includeDeleted) Searches a directory for entries matching the query.
DropboxAPI.DropboxLink	share(java.lang.String path) Generates a DropboxAPI.DropboxLink for sharing the specified directory or file.

Methods inherited from class java.lang.Object

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

Field Detail

VERSION

public static final int VERSION

The version of the API that this code uses.

See Also:

Constant Field Values

SDK_VERSION

public static final java.lang.String SDK_VERSION

The version of this Dropbox SDK.

MAX_UPLOAD_SIZE

public static final long MAX_UPLOAD_SIZE

The max upload file size that Dropbox servers can handle, in bytes.

See Also:

Constant Field Values

METADATA_DEFAULT_LIMIT

protected static final int METADATA_DEFAULT_LIMIT

See Also:

Constant Field Values

session

protected final SESS_T extends Session session

Constructor Detail

DropboxAPI

public DropboxAPI(SESS_T session)

Method Detail

getChunkedUploader

public DropboxAPI.ChunkedUploader getChunkedUploader(java.io.InputStream is)

Identical to getChunkedUploader(InputStream, long), but sets length to -1, meaning the entire inputstream will be read.

getChunkedUploader

public DropboxAPI.ChunkedUploader getChunkedUploader(java.io.InputStream is,
                                            long length)

Identical to getChunkedUploader(InputStream, long, int), but provides a default chunkSize of 4mb

getChunkedUploader

public DropboxAPI.ChunkedUploader getChunkedUploader(java.io.InputStream is,
                                            long length,
                                            int chunkSize)

Creates a ChunkedUploader using this DropboxAPI's credentials, to upload a file using the chunked upload protocol.

Parameters:

is - An inputstream providing the source of the data to be uploaded

length - The number of bytes to upload. If set to -1, the inputstream is read until exhaustion.

chunkSize - The default size of each chunk to be uploaded.

Returns:

A ChunkedUploader object which can be used to upload the file to Dropbox.

chunkedUploadRequest

public DropboxAPI.ChunkedUploadRequest chunkedUploadRequest(java.io.InputStream is,
                                                   long length,
                                                   ProgressListener listener,
                                                   long offset,
                                                   java.lang.String uploadId)

Creates a request that can upload a single chunk of data to the server via the chunked upload protocol. This request reads the InputStream and advances it by an amount equal to the number of bytes uploaded. For most users, the DropboxAPI.ChunkedUploader object provides an easier interface to use and should provide most of the functionality needed. If offset is 0 and uploadId is null, a new chunked upload is created on the server.

Parameters:

is - A stream containing the data to be uploaded.

length - The number of bytes to upload.

listener - A ProgressListener (can be null) that will be notified of upload progress. The progress will be for this individual file chunk (starting at zero bytes and ending at length bytes).

offset - The offset into the file that the contents of the these bytes belongs to.

uploadId - The unique ID identifying this upload to the server.

Returns:

A ChunkedUploadRequest which can be used to upload a single chunk of data to Dropbox.

getSession

public SESS_T getSession()

Returns the Session that this API is using.

accountInfo

public DropboxAPI.Account accountInfo()
                               throws DropboxException

Returns the DropboxAPI.Account associated with the current Session.

Returns:

the current session's DropboxAPI.Account.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code.

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

getFile

public DropboxAPI.DropboxFileInfo getFile(java.lang.String path,
                                 java.lang.String rev,
                                 java.io.OutputStream os,
                                 ProgressListener listener)
                                   throws DropboxException

Downloads a file from Dropbox, copying it to the output stream. Returns the DropboxAPI.DropboxFileInfo for the file. A typical use of getFile() would be:

FileOutputStream outputStream = null;
try {
    File file = new File("/path/to/new/file.txt");
    outputStream = new FileOutputStream(file);
    DropboxFileInfo info = mDBApi.getFile("/testing.txt", null, outputStream, null);
} catch (Exception e e) {
    System.out.println("Something went wrong: " + e);
} finally {
    if (outputStream != null) {
        try {
            outputStream.close();
        } catch (IOException e) {}
    }
}

which would retrieve the file /testing.txt in Dropbox and save it to the file /path/to/new/file.txt on the local filesystem

Parameters:

path - the Dropbox path to the file.

rev - the revision (from the file's metadata) of the file to download, or null to get the latest version.

os - the OutputStream to write the file to.

listener - an optional ProgressListener to receive progress updates as the file downloads, or null.

Returns:

the DropboxAPI.DropboxFileInfo for the downloaded file.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 404 (path not found) and 400 (bad rev).

DropboxPartialFileException - if a network error occurs during the download.

DropboxIOException - for some network-related errors.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

getFileStream

public DropboxAPI.DropboxInputStream getFileStream(java.lang.String path,
                                          java.lang.String rev)
                                            throws DropboxException

Downloads a file from Dropbox. Returns a DropboxAPI.DropboxInputStream via which the file contents can be read from the network. You must close the stream when you're done with it to release all resources. You can also cancel the download by closing the returned DropboxAPI.DropboxInputStream at any time.

Parameters:

path - the Dropbox path to the file.

rev - the revision (from the file's metadata) of the file to download, or null to get the latest version.

Returns:

a DropboxAPI.DropboxInputStream from which to read the file contents. The contents are retrieved from the network and not stored locally.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 404 (path not found) and 400 (bad rev).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

putFile

public DropboxAPI.Entry putFile(java.lang.String path,
                       java.io.InputStream is,
                       long length,
                       java.lang.String parentRev,
                       ProgressListener listener)
                         throws DropboxException

Uploads a file to Dropbox. The upload will not overwrite any existing version of the file, unless the latest version on the Dropbox server has the same rev as the parentRev given. Pass in null if you're expecting this to create a new file. Note: use putFileRequest() if you want to be able to cancel the upload. A typical usage of putFile() would be:

 FileInputStream inputStream = null;
 try {
     File file = new File("/path/to/file.txt");
     inputStream = new FileInputStream(file);
     Entry newEntry = mDBApi.putFile("/testing.txt", inputStream,
             file.length(), null, null);
 } catch (Exception e) {
     System.out.println("Something went wrong: " + e);
 } finally {
     if (inputStream != null) {
         try {
             inputStream.close();
         } catch (IOException e) {}
     }
 }
 

which would read the file /path/to/filetxt off the local filesystem and store it in Dropbox as testing.txt.

Parameters:

path - the full Dropbox path where to put the file, including directories and filename.

is - the InputStream from which to upload.

length - the amount of bytes to read from the InputStream.

parentRev - the rev of the file at which the user started editing it (obtained from a metadata call), or null if this is a new upload. If null, or if it does not match the latest rev on the server, a copy of the file will be created and you'll receive the new metadata upon executing the request.

listener - an optional ProgressListener to receive upload progress updates, or null.

Returns:

a metadata DropboxAPI.Entry representing the uploaded file.

Throws:

java.lang.IllegalArgumentException - if the file does not exist.

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxFileSizeException - if the file is bigger than the maximum allowed by the API. See DropboxAPI.MAX_UPLOAD_SIZE.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 404 (path to upload not found), 507 (user over quota), and 400 (unexpected parent rev).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

putFileRequest

public DropboxAPI.UploadRequest putFileRequest(java.lang.String path,
                                      java.io.InputStream is,
                                      long length,
                                      java.lang.String parentRev,
                                      ProgressListener listener)
                                        throws DropboxException

Creates a request to upload a file to Dropbox, which you can then upload() or abort(). The upload will not overwrite any existing version of the file, unless the latest version has the same rev as the parentRev given. Pass in null if you're expecting this to create a new file.

Parameters:

path - the full Dropbox path where to put the file, including directories and filename.

is - the InputStream from which to upload.

length - the amount of bytes to read from the InputStream.

parentRev - the rev of the file at which the user started editing it (obtained from a metadata call), or null if this is a new upload. If null, or if it does not match the latest rev on the server, a copy of the file will be created and you'll receive the new metadata upon executing the request.

listener - an optional ProgressListener to receive upload progress updates, or null.

Returns:

an DropboxAPI.UploadRequest.

Throws:

java.lang.IllegalArgumentException - if the file does not exist.

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxFileSizeException - if the file is bigger than the maximum allowed by the API. See DropboxAPI.MAX_UPLOAD_SIZE.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

putFileOverwrite

public DropboxAPI.Entry putFileOverwrite(java.lang.String path,
                                java.io.InputStream is,
                                long length,
                                ProgressListener listener)
                                  throws DropboxException

Uploads a file to Dropbox. The upload will overwrite any existing version of the file. Use putFileRequest() if you want to be able to cancel the upload. If you expect the user to be able to edit a file remotely and locally, then conflicts may arise and you won't want to use this call: see putFileRequest instead.

Parameters:

path - the full Dropbox path where to put the file, including directories and filename.

is - the InputStream from which to upload.

length - the amount of bytes to read from the InputStream.

listener - an optional ProgressListener to receive upload progress updates, or null.

Returns:

a metadata DropboxAPI.Entry representing the uploaded file.

Throws:

java.lang.IllegalArgumentException - if the file does not exist.

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxFileSizeException - if the file is bigger than the maximum allowed by the API. See DropboxAPI.MAX_UPLOAD_SIZE.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 404 (path to upload not found), 507 (user over quota), and 400 (unexpected parent rev).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

putFileOverwriteRequest

public DropboxAPI.UploadRequest putFileOverwriteRequest(java.lang.String path,
                                               java.io.InputStream is,
                                               long length,
                                               ProgressListener listener)
                                                 throws DropboxException

Creates a request to upload a file to Dropbox, which you can then upload() or abort(). The upload will overwrite any existing version of the file. If you expect the user to be able to edit a file remotely and locally, then conflicts may arise and you won't want to use this call: see putFileRequest instead.

Parameters:

path - the full Dropbox path where to put the file, including directories and filename.

is - the InputStream from which to upload.

length - the amount of bytes to read from the InputStream.

listener - an optional ProgressListener to receive upload progress updates, or null.

Returns:

an DropboxAPI.UploadRequest.

Throws:

java.lang.IllegalArgumentException - if the file does not exist locally.

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxFileSizeException - if the file is bigger than the maximum allowed by the API. See DropboxAPI.MAX_UPLOAD_SIZE.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

getThumbnail

public DropboxAPI.DropboxFileInfo getThumbnail(java.lang.String path,
                                      java.io.OutputStream os,
                                      DropboxAPI.ThumbSize size,
                                      DropboxAPI.ThumbFormat format,
                                      ProgressListener listener)
                                        throws DropboxException

Downloads a thumbnail from Dropbox, copying it to the output stream. Returns the DropboxAPI.DropboxFileInfo for the downloaded thumbnail.

Parameters:

path - the Dropbox path to the file for which you want to get a thumbnail.

os - the OutputStream to write the thumbnail to.

size - the size of the thumbnail to download.

format - the image format of the thumbnail to download.

listener - an optional ProgressListener to receive progress updates as the thumbnail downloads, or null.

Returns:

the DropboxAPI.DropboxFileInfo for the downloaded thumbnail.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 404 (path not found or can't be thumbnailed), 415 (this type of file can't be thumbnailed), and 500 (internal error while creating thumbnail).

DropboxPartialFileException - if a network error occurs during the download.

DropboxIOException - for some network-related errors.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

getThumbnailStream

public DropboxAPI.DropboxInputStream getThumbnailStream(java.lang.String path,
                                               DropboxAPI.ThumbSize size,
                                               DropboxAPI.ThumbFormat format)
                                                 throws DropboxException

Downloads a thumbnail from Dropbox. Returns a DropboxAPI.DropboxInputStream via which the thumbnail can be read from the network. You must close the stream when you're done with it to release all resources. You can also cancel the thumbnail download by closing the returned DropboxAPI.DropboxInputStream at any time.

Parameters:

path - the Dropbox path to the file for which you want to get a thumbnail.

size - the size of the thumbnail to download.

format - the image format of the thumbnail to download.

Returns:

a DropboxAPI.DropboxInputStream from which to read the thumbnail. The contents are retrieved from the network and not stored locally.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 404 (path not found or can't be thumbnailed), 415 (this type of file can't be thumbnailed), and 500 (internal error while creating thumbnail)

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

metadata

public DropboxAPI.Entry metadata(java.lang.String path,
                        int fileLimit,
                        java.lang.String hash,
                        boolean list,
                        java.lang.String rev)
                          throws DropboxException

Returns the metadata for a file, or for a directory and (optionally) its immediate children. A typical usage of metadata is:

 try {
     Entry existingEntry = mDBApi.metadata("/testing.txt", 1, null, false, null);
     // do stuff with the Entry
 } catch (DropboxException e) {
     System.out.println("Something went wrong: " + e);
 }
 

Which would return an Entry containing the metadata for the file /testing.txt in the user's Dropbox.

Parameters:

path - the Dropbox path to the file or directory for which to get metadata.

fileLimit - the maximum number of children to return for a directory. Default is 25,000 if you pass in 0 or less. If there are too many entries to return, you will get a 406 DropboxServerException. Pass in 1 if getting metadata for a file.

hash - if you previously got metadata for a directory and have it stored, pass in the returned hash. If the directory has not changed since you got the hash, a 304 DropboxServerException will be thrown. Pass in null for files or unknown directories.

list - if true, returns metadata for a directory's immediate children, or just the directory entry itself if false. Ignored for files.

rev - optionally gets metadata for a file at a prior rev (does not apply to folders). Use null for the latest metadata.

Returns:

a metadata DropboxAPI.Entry.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 304 (contents haven't changed based on the hash), 404 (path not found or unknown rev for path), and 406 (too many entries to return).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

revisions

public java.util.List<DropboxAPI.Entry> revisions(java.lang.String path,
                                         int revLimit)
                                           throws DropboxException

Returns a list of metadata for all revs of the path.

Parameters:

path - the Dropbox path to the file for which to get revisions (directories are not supported).

revLimit - the maximum number of revisions to return. Default is 1,000 if you pass in 0 or less, and 1,000 is the most that will ever be returned.

Returns:

a list of metadata entries.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error code you can expect from this call is 404 (no revisions found for path).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

search

public java.util.List<DropboxAPI.Entry> search(java.lang.String path,
                                      java.lang.String query,
                                      int fileLimit,
                                      boolean includeDeleted)
                                        throws DropboxException

Searches a directory for entries matching the query.

Parameters:

path - the Dropbox directory to search in.

query - the query to search for (minimum 3 characters).

fileLimit - the maximum number of file entries to return. Default is 10,000 if you pass in 0 or less, and 1,000 is the most that will ever be returned.

includeDeleted - whether to include deleted files in search results.

Returns:

a list of metadata entries of matching files.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code.

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

move

public DropboxAPI.Entry move(java.lang.String fromPath,
                    java.lang.String toPath)
                      throws DropboxException

Moves a file or folder (and all of the folder's contents) from one path to another.

Parameters:

fromPath - the Dropbox path to move from.

toPath - the full Dropbox path to move to (not just a directory).

Returns:

a metadata DropboxAPI.Entry.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 403 (operation is forbidden), 404 (path not found), and 507 (user over quota).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

copy

public DropboxAPI.Entry copy(java.lang.String fromPath,
                    java.lang.String toPath)
                      throws DropboxException

Copies a file or folder (and all of the folder's contents) from one path to another.

Parameters:

fromPath - the Dropbox path to copy from.

toPath - the full Dropbox path to copy to (not just a directory).

Returns:

a metadata DropboxAPI.Entry.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 403 (operation is forbidden), 404 (path not found), and 507 (user over quota).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

createFolder

public DropboxAPI.Entry createFolder(java.lang.String path)
                              throws DropboxException

Creates a new Dropbox folder.

Parameters:

path - the Dropbox path to the new folder.

Returns:

a metadata DropboxAPI.Entry for the new folder.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 403 (something already exists at that path), 404 (path not found), and 507 (user over quota).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

delete

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

Deletes a file or folder (and all of the folder's contents). After deletion, metadata calls may still return this file or folder for some time, but the metadata DropboxAPI.Entry's isDeleted attribute will be set to true.

Parameters:

path - the Dropbox path to delete.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error code you can expect from this call is 404 (path not found).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

restore

public DropboxAPI.Entry restore(java.lang.String path,
                       java.lang.String rev)
                         throws DropboxException

Restores a file to a previous rev.

Parameters:

path - the Dropbox path to the file to restore.

rev - the rev to restore to (obtained from a metadata or revisions call).

Returns:

a metadata DropboxAPI.Entry for the newly restored file.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error code you can expect from this call is 404 (path not found or unknown revision).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

media

public DropboxAPI.DropboxLink media(java.lang.String path,
                           boolean ssl)
                             throws DropboxException

Returns a DropboxAPI.DropboxLink for a stream of the given file path (for streaming media files).

Parameters:

path - the Dropbox path of the file for which to get a streaming link.

ssl - whether the streaming URL is https or http. Some Android and other platforms won't play https streams, so false converts the link to an http link before returning it.

Returns:

a DropboxAPI.DropboxLink for streaming the file.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error code you can expect from this call is 404 (path not found).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

share

public DropboxAPI.DropboxLink share(java.lang.String path)
                             throws DropboxException

Generates a DropboxAPI.DropboxLink for sharing the specified directory or file.

Parameters:

path - the Dropbox path to share, either a directory or file.

Returns:

a DropboxAPI.DropboxLink for the path.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error code you can expect from this call is 404 (path not found).

DropboxIOException - if any network-related error occurs.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

getFromMapAsBoolean

protected static boolean getFromMapAsBoolean(java.util.Map<java.lang.String,java.lang.Object> map,
                          java.lang.String name)

Helper function to read boolean JSON return values

Parameters:

map - the one to read from

name - the parameter name to read

Returns:

the value, with false as a default if no parameter set

delta

public DropboxAPI.DeltaPage<DropboxAPI.Entry> delta(java.lang.String cursor)
                                             throws DropboxException

A way of letting you keep up with changes to files and folders in a user's Dropbox. You can periodically call this function to get a list of "delta entries", which are instructions on how to update your local state to match the server's state.

Parameters:

cursor - On the first call, you should pass in null. On subsequent calls, pass in the cursor returned by the previous call.

Returns:

A single DeltaPage of results. The hasMore field will tell you whether the server has more pages of results to return. If the server doesn't have more results, you can wait a bit (say, 5 or 10 minutes) and poll again.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

createCopyRef

public DropboxAPI.CreatedCopyRef createCopyRef(java.lang.String sourcePath)
                                        throws DropboxException

Creates a reference to a path that can be used with addFromCopyRef() to copy the contents of the file at that path to a different Dropbox account. This is more efficient than copying the content

Parameters:

sourcePath - The full path to the file that you want a

Returns:

A string representation of the file pointer.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

addFromCopyRef

public DropboxAPI.Entry addFromCopyRef(java.lang.String sourceCopyRef,
                              java.lang.String targetPath)
                                throws DropboxException

Creates a file in the Dropbox that the client is currently connected to, using the contents from a CopyRef created with createCopyRef(). The CreatedCopyRef can be for a file in a different Dropbox account.

Parameters:

sourceCopyRef - The copy-ref to use as the source of the file data (comes from CreatedCopyRef.copyRef, which is created through createCopyRef()).

targetPath - The path that you want to create the file at.

Returns:

The DropboxAPI.Entry for the new file.

Throws:

DropboxUnlinkedException - if you have not set an access token pair on the session, or if the user has revoked access.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

assertAuthenticated

protected void assertAuthenticated()
                            throws DropboxUnlinkedException

Throws a DropboxUnlinkedException if the session in this instance is not linked.

Throws:

DropboxUnlinkedException

getFromMapAsLong

protected static long getFromMapAsLong(java.util.Map<java.lang.String,java.lang.Object> map,
                    java.lang.String name)

Helper function to read long JSON return values

Parameters:

map - the one to read from

name - the parameter name to read

Returns:

the value, with 0 as a default if no parameter set