com.dropbox.client2
Class DropboxAPI<SESS_T extends Session>

java.lang.Object
  extended by 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
static class DropboxAPI.Account
          Information about a user's account.
protected static class DropboxAPI.BasicUploadRequest
           
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
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
DropboxAPI(SESS_T session)
           
 
Method Summary
 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.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.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

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.

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.

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.

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 10,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