com.dropbox.core.v2.files

Class DbxUserFilesRequests

java.lang.Object

com.dropbox.core.v2.files.DbxUserFilesRequests

public class DbxUserFilesRequests
extends Object

Routes in namespace "files".

Constructor Summary

Constructors

Constructor and Description
DbxUserFilesRequests(DbxRawClientV2 client)

Method Summary

Modifier and Type	Method and Description
Metadata	copy(String fromPath, String toPath) Copy a file or folder to a different location in the user's Dropbox.
LaunchEmptyResult	copyBatch(List<RelocationPath> entries) Copy multiple files or folders to different locations at once in the user's Dropbox.
CopyBatchBuilder	copyBatchBuilder(List<RelocationPath> entries) Copy multiple files or folders to different locations at once in the user's Dropbox.
RelocationBatchJobStatus	copyBatchCheck(String asyncJobId) Returns the status of an asynchronous job for copyBatch(List).
CopyBuilder	copyBuilder(String fromPath, String toPath) Copy a file or folder to a different location in the user's Dropbox.
GetCopyReferenceResult	copyReferenceGet(String path) Get a copy reference to a file or folder.
SaveCopyReferenceResult	copyReferenceSave(String copyReference, String path) Save a copy reference returned by copyReferenceGet(String) to the user's Dropbox.
FolderMetadata	createFolder(String path) Create a folder at a given path.
FolderMetadata	createFolder(String path, boolean autorename) Create a folder at a given path.
Metadata	delete(String path) Delete the file or folder at a given path.
LaunchEmptyResult	deleteBatch(List<DeleteArg> entries) Delete multiple files/folders at once.
DeleteBatchJobStatus	deleteBatchCheck(String asyncJobId) Returns the status of an asynchronous job for deleteBatch(List).
DbxDownloader<FileMetadata>	download(String path) Download a file from a user's Dropbox.
DbxDownloader<FileMetadata>	download(String path, String rev) Download a file from a user's Dropbox.
DownloadBuilder	downloadBuilder(String path) Download a file from a user's Dropbox.
Metadata	getMetadata(String path) Returns the metadata for a file or folder.
GetMetadataBuilder	getMetadataBuilder(String path) Returns the metadata for a file or folder.
DbxDownloader<FileMetadata>	getPreview(String path) Get a preview for a file.
DbxDownloader<FileMetadata>	getPreview(String path, String rev) Get a preview for a file.
GetPreviewBuilder	getPreviewBuilder(String path) Get a preview for a file.
GetTemporaryLinkResult	getTemporaryLink(String path) Get a temporary link to stream content of a file.
DbxDownloader<FileMetadata>	getThumbnail(String path) Get a thumbnail for an image.
GetThumbnailBuilder	getThumbnailBuilder(String path) Get a thumbnail for an image.
ListFolderResult	listFolder(String path) Starts returning the contents of a folder.
ListFolderBuilder	listFolderBuilder(String path) Starts returning the contents of a folder.
ListFolderResult	listFolderContinue(String cursor) Once a cursor has been retrieved from listFolder(String), use this to paginate through all files and retrieve updates to the folder, following the same rules as documented for listFolder(String).
ListFolderGetLatestCursorResult	listFolderGetLatestCursor(String path) A way to quickly get a cursor for the folder's state.
ListFolderGetLatestCursorBuilder	listFolderGetLatestCursorBuilder(String path) A way to quickly get a cursor for the folder's state.
ListFolderLongpollResult	listFolderLongpoll(String cursor) A longpoll endpoint to wait for changes on an account.
ListFolderLongpollResult	listFolderLongpoll(String cursor, long timeout) A longpoll endpoint to wait for changes on an account.
ListRevisionsResult	listRevisions(String path) Return revisions of a file.
ListRevisionsResult	listRevisions(String path, long limit) Return revisions of a file.
Metadata	move(String fromPath, String toPath) Move a file or folder to a different location in the user's Dropbox.
LaunchEmptyResult	moveBatch(List<RelocationPath> entries) Move multiple files or folders to different locations at once in the user's Dropbox.
MoveBatchBuilder	moveBatchBuilder(List<RelocationPath> entries) Move multiple files or folders to different locations at once in the user's Dropbox.
RelocationBatchJobStatus	moveBatchCheck(String asyncJobId) Returns the status of an asynchronous job for moveBatch(List).
MoveBuilder	moveBuilder(String fromPath, String toPath) Move a file or folder to a different location in the user's Dropbox.
void	permanentlyDelete(String path) Permanently delete the file or folder at a given path (see https://www.dropbox.com/en/help/40).
FileMetadata	restore(String path, String rev) Restore a file to a specific revision.
SaveUrlResult	saveUrl(String path, String url) Save a specified URL into a file in user's Dropbox.
SaveUrlJobStatus	saveUrlCheckJobStatus(String asyncJobId) Check the status of a saveUrl(String,String) job.
SearchResult	search(String path, String query) Searches for files and folders.
SearchBuilder	searchBuilder(String path, String query) Searches for files and folders.
UploadUploader	upload(String path) Create a new file with the contents provided in the request.
UploadBuilder	uploadBuilder(String path) Create a new file with the contents provided in the request.
UploadSessionAppendUploader	uploadSessionAppend(String sessionId, long offset) Deprecated. use uploadSessionAppendV2(UploadSessionCursor,boolean) instead.
UploadSessionAppendV2Uploader	uploadSessionAppendV2(UploadSessionCursor cursor) Append more data to an upload session.
UploadSessionAppendV2Uploader	uploadSessionAppendV2(UploadSessionCursor cursor, boolean close) Append more data to an upload session.
UploadSessionFinishUploader	uploadSessionFinish(UploadSessionCursor cursor, CommitInfo commit) Finish an upload session and save the uploaded data to the given file path.
LaunchEmptyResult	uploadSessionFinishBatch(List<UploadSessionFinishArg> entries) This route helps you commit many files at once into a user's Dropbox.
UploadSessionFinishBatchJobStatus	uploadSessionFinishBatchCheck(String asyncJobId) Returns the status of an asynchronous job for uploadSessionFinishBatch(List).
UploadSessionStartUploader	uploadSessionStart() Upload sessions allow you to upload a single file in one or more requests, for example where the size of the file is greater than 150 MB.
UploadSessionStartUploader	uploadSessionStart(boolean close) Upload sessions allow you to upload a single file in one or more requests, for example where the size of the file is greater than 150 MB.

Methods inherited from class java.lang.Object

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

Constructor Detail

DbxUserFilesRequests

public DbxUserFilesRequests(DbxRawClientV2 client)

Method Detail

copy

public Metadata copy(String fromPath,
                     String toPath)
              throws RelocationErrorException,
                     DbxException

Copy a file or folder to a different location in the user's Dropbox. If the source path is a folder all its contents will be copied.

The default values for the optional request parameters will be used. See CopyBuilder for more details.

Parameters:

fromPath - Path in the user's Dropbox to be copied or moved. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

toPath - Path in the user's Dropbox that is the destination. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Metadata for a file or folder.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

RelocationErrorException

DbxException

copyBuilder

public CopyBuilder copyBuilder(String fromPath,
                               String toPath)

Copy a file or folder to a different location in the user's Dropbox. If the source path is a folder all its contents will be copied.

Parameters:

fromPath - Path in the user's Dropbox to be copied or moved. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

toPath - Path in the user's Dropbox that is the destination. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Request builder for configuring request parameters and completing the request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

copyBatch

public LaunchEmptyResult copyBatch(List<RelocationPath> entries)
                            throws DbxApiException,
                                   DbxException

Copy multiple files or folders to different locations at once in the user's Dropbox. If RelocationBatchArg.getAllowSharedFolder() is false, this route is atomic. If on entry failes, the whole transaction will abort. If RelocationBatchArg.getAllowSharedFolder() is true, not atomicity is guaranteed, but you will be able to copy the contents of shared folders to new locations. This route will return job ID immediately and do the async copy job in background. Please use copyBatchCheck(String) to check the job status.

The default values for the optional request parameters will be used. See CopyBatchBuilder for more details.

Parameters:

entries - List of entries to be moved or copied. Each entry is RelocationPath. Must not contain a null item and not be null.

Returns:

Result returned by methods that may either launch an asynchronous job or complete synchronously. Upon synchronous completion of the job, no additional information is returned.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DbxApiException

DbxException

copyBatchBuilder

public CopyBatchBuilder copyBatchBuilder(List<RelocationPath> entries)

Copy multiple files or folders to different locations at once in the user's Dropbox. If RelocationBatchArg.getAllowSharedFolder() is false, this route is atomic. If on entry failes, the whole transaction will abort. If RelocationBatchArg.getAllowSharedFolder() is true, not atomicity is guaranteed, but you will be able to copy the contents of shared folders to new locations. This route will return job ID immediately and do the async copy job in background. Please use copyBatchCheck(String) to check the job status.

Parameters:

entries - List of entries to be moved or copied. Each entry is RelocationPath. Must not contain a null item and not be null.

Returns:

Request builder for configuring request parameters and completing the request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

copyBatchCheck

public RelocationBatchJobStatus copyBatchCheck(String asyncJobId)
                                        throws PollErrorException,
                                               DbxException

Returns the status of an asynchronous job for copyBatch(List). If success, it returns list of results for each entry.

Parameters:

asyncJobId - Id of the asynchronous job. This is the value of a response returned from the method that launched the job. Must have length of at least 1 and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

PollErrorException

DbxException

copyReferenceGet

public GetCopyReferenceResult copyReferenceGet(String path)
                                        throws GetCopyReferenceErrorException,
                                               DbxException

Get a copy reference to a file or folder. This reference string can be used to save that file or folder to another user's Dropbox by passing it to copyReferenceSave(String,String).

Parameters:

path - The path to the file or folder you want to get a copy reference to. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

GetCopyReferenceErrorException

DbxException

copyReferenceSave

public SaveCopyReferenceResult copyReferenceSave(String copyReference,
                                                 String path)
                                          throws SaveCopyReferenceErrorException,
                                                 DbxException

Save a copy reference returned by copyReferenceGet(String) to the user's Dropbox.

Parameters:

copyReference - A copy reference returned by copyReferenceGet(String). Must not be null.

path - Path in the user's Dropbox that is the destination. Must match pattern "/(.|[\\r\\n])*" and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

SaveCopyReferenceErrorException

DbxException

createFolder

public FolderMetadata createFolder(String path)
                            throws CreateFolderErrorException,
                                   DbxException

Create a folder at a given path.

The autorename request parameter will default to false (see createFolder(String,boolean)).

Parameters:

path - Path in the user's Dropbox to create. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

CreateFolderErrorException

DbxException

createFolder

public FolderMetadata createFolder(String path,
                                   boolean autorename)
                            throws CreateFolderErrorException,
                                   DbxException

Create a folder at a given path.

Parameters:

path - Path in the user's Dropbox to create. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

autorename - If there's a conflict, have the Dropbox server try to autorename the folder to avoid the conflict.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

CreateFolderErrorException

DbxException

delete

public Metadata delete(String path)
                throws DeleteErrorException,
                       DbxException

Delete the file or folder at a given path. If the path is a folder, all its contents will be deleted too. A successful response indicates that the file or folder was deleted. The returned metadata will be the corresponding FileMetadata or FolderMetadata for the item at time of deletion, and not a DeletedMetadata object.

Parameters:

path - Path in the user's Dropbox to delete. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Metadata for a file or folder.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DeleteErrorException

DbxException

deleteBatch

public LaunchEmptyResult deleteBatch(List<DeleteArg> entries)
                              throws DbxApiException,
                                     DbxException

Delete multiple files/folders at once. This route is asynchronous, which returns a job ID immediately and runs the delete batch asynchronously. Use deleteBatchCheck(String) to check the job status.

Parameters:

entries - Must not contain a null item and not be null.

Returns:

Result returned by methods that may either launch an asynchronous job or complete synchronously. Upon synchronous completion of the job, no additional information is returned.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DbxApiException

DbxException

deleteBatchCheck

public DeleteBatchJobStatus deleteBatchCheck(String asyncJobId)
                                      throws PollErrorException,
                                             DbxException

Returns the status of an asynchronous job for deleteBatch(List). If success, it returns list of result for each entry.

Parameters:

asyncJobId - Id of the asynchronous job. This is the value of a response returned from the method that launched the job. Must have length of at least 1 and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

PollErrorException

DbxException

download

public DbxDownloader<FileMetadata> download(String path)
                                     throws DownloadErrorException,
                                            DbxException

Download a file from a user's Dropbox.

Parameters:

path - The path of the file to download. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Downloader used to download the response body and view the server response.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DownloadErrorException

DbxException

download

public DbxDownloader<FileMetadata> download(String path,
                                            String rev)
                                     throws DownloadErrorException,
                                            DbxException

Download a file from a user's Dropbox.

Parameters:

path - The path of the file to download. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

rev - Deprecated. Please specify revision in the path argument to download(String,String) instead. Must have length of at least 9 and match pattern "[0-9a-f]+".

Returns:

Downloader used to download the response body and view the server response.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DownloadErrorException

DbxException

downloadBuilder

public DownloadBuilder downloadBuilder(String path)

Download a file from a user's Dropbox.

Parameters:

path - The path of the file to download. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Downloader builder for configuring the request parameters and instantiating a downloader.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

getMetadata

public Metadata getMetadata(String path)
                     throws GetMetadataErrorException,
                            DbxException

Returns the metadata for a file or folder. Note: Metadata for the root folder is unsupported.

The default values for the optional request parameters will be used. See GetMetadataBuilder for more details.

Parameters:

path - The path of a file or folder on Dropbox. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Metadata for a file or folder.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

GetMetadataErrorException

DbxException

getMetadataBuilder

public GetMetadataBuilder getMetadataBuilder(String path)

Returns the metadata for a file or folder. Note: Metadata for the root folder is unsupported.

Parameters:

path - The path of a file or folder on Dropbox. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Request builder for configuring request parameters and completing the request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

getPreview

public DbxDownloader<FileMetadata> getPreview(String path)
                                       throws PreviewErrorException,
                                              DbxException

Get a preview for a file. Currently previews are only generated for the files with the following extensions: .doc, .docx, .docm, .ppt, .pps, .ppsx, .ppsm, .pptx, .pptm, .xls, .xlsx, .xlsm, .rtf.

Parameters:

path - The path of the file to preview. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Downloader used to download the response body and view the server response.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

PreviewErrorException

DbxException

getPreview

public DbxDownloader<FileMetadata> getPreview(String path,
                                              String rev)
                                       throws PreviewErrorException,
                                              DbxException

Get a preview for a file. Currently previews are only generated for the files with the following extensions: .doc, .docx, .docm, .ppt, .pps, .ppsx, .ppsm, .pptx, .pptm, .xls, .xlsx, .xlsm, .rtf.

Parameters:

path - The path of the file to preview. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

rev - Deprecated. Please specify revision in the path argument to getPreview(String,String) instead. Must have length of at least 9 and match pattern "[0-9a-f]+".

Returns:

Downloader used to download the response body and view the server response.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

PreviewErrorException

DbxException

getPreviewBuilder

public GetPreviewBuilder getPreviewBuilder(String path)

Get a preview for a file. Currently previews are only generated for the files with the following extensions: .doc, .docx, .docm, .ppt, .pps, .ppsx, .ppsm, .pptx, .pptm, .xls, .xlsx, .xlsm, .rtf.

Parameters:

path - The path of the file to preview. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Downloader builder for configuring the request parameters and instantiating a downloader.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

getTemporaryLink

public GetTemporaryLinkResult getTemporaryLink(String path)
                                        throws GetTemporaryLinkErrorException,
                                               DbxException

Get a temporary link to stream content of a file. This link will expire in four hours and afterwards you will get 410 Gone. Content-Type of the link is determined automatically by the file's mime type.

Parameters:

path - The path to the file you want a temporary link to. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

GetTemporaryLinkErrorException

DbxException

getThumbnail

public DbxDownloader<FileMetadata> getThumbnail(String path)
                                         throws ThumbnailErrorException,
                                                DbxException

Get a thumbnail for an image. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB in size won't be converted to a thumbnail.

The default values for the optional request parameters will be used. See GetThumbnailBuilder for more details.

Parameters:

path - The path to the image file you want to thumbnail. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Downloader used to download the response body and view the server response.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

ThumbnailErrorException

DbxException

getThumbnailBuilder

public GetThumbnailBuilder getThumbnailBuilder(String path)

Get a thumbnail for an image. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB in size won't be converted to a thumbnail.

Parameters:

path - The path to the image file you want to thumbnail. Must match pattern "(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Downloader builder for configuring the request parameters and instantiating a downloader.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

listFolder

public ListFolderResult listFolder(String path)
                            throws ListFolderErrorException,
                                   DbxException

Starts returning the contents of a folder. If the result's ListFolderResult.getHasMore() field is true, call listFolderContinue(String) with the returned ListFolderResult.getCursor() to retrieve more entries. If you're using ListFolderArg.getRecursive() set to true to keep a local cache of the contents of a Dropbox account, iterate through each entry in order and process them as follows to keep your local state in sync: For each FileMetadata, store the new entry at the given path in your local state. If the required parent folders don't exist yet, create them. If there's already something else at the given path, replace it and remove all its children. For each FolderMetadata, store the new entry at the given path in your local state. If the required parent folders don't exist yet, create them. If there's already something else at the given path, replace it but leave the children as they are. Check the new entry's FolderSharingInfo.getReadOnly() and set all its children's read-only statuses to match. For each DeletedMetadata, if your local state has something at the given path, remove it and all its children. If there's nothing at the given path, ignore this entry.

The default values for the optional request parameters will be used. See ListFolderBuilder for more details.

Parameters:

path - The path to the folder you want to see the contents of. Must match pattern "(/(.|[\\r\\n])*)?|(ns:[0-9]+(/.*)?)" and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

ListFolderErrorException

DbxException

listFolderBuilder

public ListFolderBuilder listFolderBuilder(String path)

Starts returning the contents of a folder. If the result's ListFolderResult.getHasMore() field is true, call listFolderContinue(String) with the returned ListFolderResult.getCursor() to retrieve more entries. If you're using ListFolderArg.getRecursive() set to true to keep a local cache of the contents of a Dropbox account, iterate through each entry in order and process them as follows to keep your local state in sync: For each FileMetadata, store the new entry at the given path in your local state. If the required parent folders don't exist yet, create them. If there's already something else at the given path, replace it and remove all its children. For each FolderMetadata, store the new entry at the given path in your local state. If the required parent folders don't exist yet, create them. If there's already something else at the given path, replace it but leave the children as they are. Check the new entry's FolderSharingInfo.getReadOnly() and set all its children's read-only statuses to match. For each DeletedMetadata, if your local state has something at the given path, remove it and all its children. If there's nothing at the given path, ignore this entry.

Parameters:

path - The path to the folder you want to see the contents of. Must match pattern "(/(.|[\\r\\n])*)?|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Request builder for configuring request parameters and completing the request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

listFolderContinue

public ListFolderResult listFolderContinue(String cursor)
                                    throws ListFolderContinueErrorException,
                                           DbxException

Once a cursor has been retrieved from listFolder(String), use this to paginate through all files and retrieve updates to the folder, following the same rules as documented for listFolder(String).

Parameters:

cursor - The cursor returned by your last call to listFolder(String) or listFolderContinue(String). Must have length of at least 1 and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

ListFolderContinueErrorException

DbxException

listFolderGetLatestCursor

public ListFolderGetLatestCursorResult listFolderGetLatestCursor(String path)
                                                          throws ListFolderErrorException,
                                                                 DbxException

A way to quickly get a cursor for the folder's state. Unlike listFolder(String), listFolderGetLatestCursor(String) doesn't return any entries. This endpoint is for app which only needs to know about new files and modifications and doesn't need to know about files that already exist in Dropbox.

The default values for the optional request parameters will be used. See ListFolderGetLatestCursorBuilder for more details.

Parameters:

path - The path to the folder you want to see the contents of. Must match pattern "(/(.|[\\r\\n])*)?|(ns:[0-9]+(/.*)?)" and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

ListFolderErrorException

DbxException

listFolderGetLatestCursorBuilder

public ListFolderGetLatestCursorBuilder listFolderGetLatestCursorBuilder(String path)

A way to quickly get a cursor for the folder's state. Unlike listFolder(String), listFolderGetLatestCursor(String) doesn't return any entries. This endpoint is for app which only needs to know about new files and modifications and doesn't need to know about files that already exist in Dropbox.

Parameters:

path - The path to the folder you want to see the contents of. Must match pattern "(/(.|[\\r\\n])*)?|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Request builder for configuring request parameters and completing the request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

listFolderLongpoll

public ListFolderLongpollResult listFolderLongpoll(String cursor)
                                            throws ListFolderLongpollErrorException,
                                                   DbxException

A longpoll endpoint to wait for changes on an account. In conjunction with listFolderContinue(String), this call gives you a low-latency way to monitor an account for file changes. The connection will block until there are changes available or a timeout occurs. This endpoint is useful mostly for client-side apps. If you're looking for server-side notifications, check out our webhooks documentation.

The timeout request parameter will default to 30L (see listFolderLongpoll(String,long)).

Parameters:

cursor - A cursor as returned by listFolder(String) or listFolderContinue(String). Cursors retrieved by setting ListFolderArg.getIncludeMediaInfo() to true are not supported. Must have length of at least 1 and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

ListFolderLongpollErrorException

DbxException

listFolderLongpoll

public ListFolderLongpollResult listFolderLongpoll(String cursor,
                                                   long timeout)
                                            throws ListFolderLongpollErrorException,
                                                   DbxException

A longpoll endpoint to wait for changes on an account. In conjunction with listFolderContinue(String), this call gives you a low-latency way to monitor an account for file changes. The connection will block until there are changes available or a timeout occurs. This endpoint is useful mostly for client-side apps. If you're looking for server-side notifications, check out our webhooks documentation.

Parameters:

cursor - A cursor as returned by listFolder(String) or listFolderContinue(String). Cursors retrieved by setting ListFolderArg.getIncludeMediaInfo() to true are not supported. Must have length of at least 1 and not be null.

timeout - A timeout in seconds. The request will block for at most this length of time, plus up to 90 seconds of random jitter added to avoid the thundering herd problem. Care should be taken when using this parameter, as some network infrastructure does not support long timeouts. Must be greater than or equal to 30 and be less than or equal to 480.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

ListFolderLongpollErrorException

DbxException

listRevisions

public ListRevisionsResult listRevisions(String path)
                                  throws ListRevisionsErrorException,
                                         DbxException

Return revisions of a file.

The limit request parameter will default to 10L (see listRevisions(String,long)).

Parameters:

path - The path to the file you want to see the revisions of. Must match pattern "/(.|[\\r\\n])*|id:.*|(ns:[0-9]+(/.*)?)" and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

ListRevisionsErrorException

DbxException

listRevisions

public ListRevisionsResult listRevisions(String path,
                                         long limit)
                                  throws ListRevisionsErrorException,
                                         DbxException

Return revisions of a file.

Parameters:

path - The path to the file you want to see the revisions of. Must match pattern "/(.|[\\r\\n])*|id:.*|(ns:[0-9]+(/.*)?)" and not be null.

limit - The maximum number of revision entries returned. Must be greater than or equal to 1 and be less than or equal to 100.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

ListRevisionsErrorException

DbxException

move

public Metadata move(String fromPath,
                     String toPath)
              throws RelocationErrorException,
                     DbxException

Move a file or folder to a different location in the user's Dropbox. If the source path is a folder all its contents will be moved.

The default values for the optional request parameters will be used. See MoveBuilder for more details.

Parameters:

fromPath - Path in the user's Dropbox to be copied or moved. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

toPath - Path in the user's Dropbox that is the destination. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Metadata for a file or folder.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

RelocationErrorException

DbxException

moveBuilder

public MoveBuilder moveBuilder(String fromPath,
                               String toPath)

Move a file or folder to a different location in the user's Dropbox. If the source path is a folder all its contents will be moved.

Parameters:

fromPath - Path in the user's Dropbox to be copied or moved. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

toPath - Path in the user's Dropbox that is the destination. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Request builder for configuring request parameters and completing the request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

moveBatch

public LaunchEmptyResult moveBatch(List<RelocationPath> entries)
                            throws DbxApiException,
                                   DbxException

Move multiple files or folders to different locations at once in the user's Dropbox. This route is 'all or nothing', which means if one entry fails, the whole transaction will abort. This route will return job ID immediately and do the async moving job in background. Please use moveBatchCheck(String) to check the job status.

The default values for the optional request parameters will be used. See MoveBatchBuilder for more details.

Parameters:

entries - List of entries to be moved or copied. Each entry is RelocationPath. Must not contain a null item and not be null.

Returns:

Result returned by methods that may either launch an asynchronous job or complete synchronously. Upon synchronous completion of the job, no additional information is returned.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DbxApiException

DbxException

moveBatchBuilder

public MoveBatchBuilder moveBatchBuilder(List<RelocationPath> entries)

Move multiple files or folders to different locations at once in the user's Dropbox. This route is 'all or nothing', which means if one entry fails, the whole transaction will abort. This route will return job ID immediately and do the async moving job in background. Please use moveBatchCheck(String) to check the job status.

Parameters:

entries - List of entries to be moved or copied. Each entry is RelocationPath. Must not contain a null item and not be null.

Returns:

Request builder for configuring request parameters and completing the request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

moveBatchCheck

public RelocationBatchJobStatus moveBatchCheck(String asyncJobId)
                                        throws PollErrorException,
                                               DbxException

Returns the status of an asynchronous job for moveBatch(List). If success, it returns list of results for each entry.

Parameters:

asyncJobId - Id of the asynchronous job. This is the value of a response returned from the method that launched the job. Must have length of at least 1 and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

PollErrorException

DbxException

permanentlyDelete

public void permanentlyDelete(String path)
                       throws DeleteErrorException,
                              DbxException

Permanently delete the file or folder at a given path (see https://www.dropbox.com/en/help/40). Note: This endpoint is only available for Dropbox Business apps.

Parameters:

path - Path in the user's Dropbox to delete. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DeleteErrorException

DbxException

restore

public FileMetadata restore(String path,
                            String rev)
                     throws RestoreErrorException,
                            DbxException

Restore a file to a specific revision.

Parameters:

path - The path to the file you want to restore. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

rev - The revision to restore for the file. Must have length of at least 9, match pattern "[0-9a-f]+", and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

RestoreErrorException

DbxException

saveUrl

public SaveUrlResult saveUrl(String path,
                             String url)
                      throws SaveUrlErrorException,
                             DbxException

Save a specified URL into a file in user's Dropbox. If the given path already exists, the file will be renamed to avoid the conflict (e.g. myfile (1).txt).

Parameters:

path - The path in Dropbox where the URL will be saved to. Must match pattern "/(.|[\\r\\n])*" and not be null.

url - The URL to be saved. Must not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

SaveUrlErrorException

DbxException

saveUrlCheckJobStatus

public SaveUrlJobStatus saveUrlCheckJobStatus(String asyncJobId)
                                       throws PollErrorException,
                                              DbxException

Check the status of a saveUrl(String,String) job.

Parameters:

asyncJobId - Id of the asynchronous job. This is the value of a response returned from the method that launched the job. Must have length of at least 1 and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

PollErrorException

DbxException

search

public SearchResult search(String path,
                           String query)
                    throws SearchErrorException,
                           DbxException

Searches for files and folders. Note: Recent changes may not immediately be reflected in search results due to a short delay in indexing.

The default values for the optional request parameters will be used. See SearchBuilder for more details.

Parameters:

path - The path in the user's Dropbox to search. Should probably be a folder. Must match pattern "(/(.|[\\r\\n])*)?|(ns:[0-9]+(/.*)?)" and not be null.

query - The string to search for. The search string is split on spaces into multiple tokens. For file name searching, the last token is used for prefix matching (i.e. "bat c" matches "bat cave" but not "batman car"). Must not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

SearchErrorException

DbxException

searchBuilder

public SearchBuilder searchBuilder(String path,
                                   String query)

Searches for files and folders. Note: Recent changes may not immediately be reflected in search results due to a short delay in indexing.

Parameters:

path - The path in the user's Dropbox to search. Should probably be a folder. Must match pattern "(/(.|[\\r\\n])*)?|(ns:[0-9]+(/.*)?)" and not be null.

query - The string to search for. The search string is split on spaces into multiple tokens. For file name searching, the last token is used for prefix matching (i.e. "bat c" matches "bat cave" but not "batman car"). Must not be null.

Returns:

Request builder for configuring request parameters and completing the request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

upload

public UploadUploader upload(String path)
                      throws DbxException

Create a new file with the contents provided in the request. Do not use this to upload a file larger than 150 MB. Instead, create an upload session with uploadSessionStart(boolean).

The default values for the optional request parameters will be used. See UploadBuilder for more details.

Parameters:

path - Path in the user's Dropbox to save the file. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Uploader used to upload the request body and finish request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DbxException

uploadBuilder

public UploadBuilder uploadBuilder(String path)

Create a new file with the contents provided in the request. Do not use this to upload a file larger than 150 MB. Instead, create an upload session with uploadSessionStart(boolean).

Parameters:

path - Path in the user's Dropbox to save the file. Must match pattern "(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)" and not be null.

Returns:

Uploader builder for configuring request parameters and instantiating an uploader.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

uploadSessionAppend

@Deprecated
public UploadSessionAppendUploader uploadSessionAppend(String sessionId,
                                                                   long offset)
                                                            throws DbxException

Deprecated. use uploadSessionAppendV2(UploadSessionCursor,boolean) instead.

Append more data to an upload session. A single request should not upload more than 150 MB of file contents.

Parameters:

sessionId - The upload session ID (returned by uploadSessionStart(boolean)). Must not be null.

offset - The amount of data that has been uploaded so far. We use this to make sure upload data isn't lost or duplicated in the event of a network error.

Returns:

Uploader used to upload the request body and finish request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DbxException

uploadSessionAppendV2

public UploadSessionAppendV2Uploader uploadSessionAppendV2(UploadSessionCursor cursor)
                                                    throws DbxException

Append more data to an upload session. When the parameter close is set, this call will close the session. A single request should not upload more than 150 MB of file contents.

The close request parameter will default to false (see uploadSessionAppendV2(UploadSessionCursor,boolean)).

Parameters:

cursor - Contains the upload session ID and the offset. Must not be null.

Returns:

Uploader used to upload the request body and finish request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DbxException

uploadSessionAppendV2

public UploadSessionAppendV2Uploader uploadSessionAppendV2(UploadSessionCursor cursor,
                                                           boolean close)
                                                    throws DbxException

Append more data to an upload session. When the parameter close is set, this call will close the session. A single request should not upload more than 150 MB of file contents.

Parameters:

cursor - Contains the upload session ID and the offset. Must not be null.

close - If true, the current session will be closed, at which point you won't be able to call uploadSessionAppendV2(UploadSessionCursor,boolean) anymore with the current session.

Returns:

Uploader used to upload the request body and finish request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DbxException

uploadSessionFinish

public UploadSessionFinishUploader uploadSessionFinish(UploadSessionCursor cursor,
                                                       CommitInfo commit)
                                                throws DbxException

Finish an upload session and save the uploaded data to the given file path. A single request should not upload more than 150 MB of file contents.

Parameters:

cursor - Contains the upload session ID and the offset. Must not be null.

commit - Contains the path and other optional modifiers for the commit. Must not be null.

Returns:

Uploader used to upload the request body and finish request.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DbxException

uploadSessionFinishBatch

public LaunchEmptyResult uploadSessionFinishBatch(List<UploadSessionFinishArg> entries)
                                           throws DbxApiException,
                                                  DbxException

This route helps you commit many files at once into a user's Dropbox. Use uploadSessionStart(boolean) and uploadSessionAppendV2(UploadSessionCursor,boolean) to upload file contents. We recommend uploading many files in parallel to increase throughput. Once the file contents have been uploaded, rather than calling uploadSessionFinish(UploadSessionCursor,CommitInfo), use this route to finish all your upload sessions in a single request. the close argument to uploadSessionStart(boolean) or the close argument to uploadSessionAppendV2(UploadSessionCursor,boolean) needs to be true for the last uploadSessionStart(boolean) or uploadSessionAppendV2(UploadSessionCursor,boolean) call. This route will return a job_id immediately and do the async commit job in background. Use uploadSessionFinishBatchCheck(String) to check the job status. For the same account, this route should be executed serially. That means you should not start the next job before current job finishes. We allow up to 1000 entries in a single request.

Parameters:

entries - Commit information for each file in the batch. Must contain at most 1000 items, not contain a null item, and not be null.

Returns:

Result returned by methods that may either launch an asynchronous job or complete synchronously. Upon synchronous completion of the job, no additional information is returned.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

DbxApiException

DbxException

uploadSessionFinishBatchCheck

public UploadSessionFinishBatchJobStatus uploadSessionFinishBatchCheck(String asyncJobId)
                                                                throws PollErrorException,
                                                                       DbxException

Returns the status of an asynchronous job for uploadSessionFinishBatch(List). If success, it returns list of result for each entry.

Parameters:

asyncJobId - Id of the asynchronous job. This is the value of a response returned from the method that launched the job. Must have length of at least 1 and not be null.

Throws:

IllegalArgumentException - If any argument does not meet its preconditions.

PollErrorException

DbxException

uploadSessionStart

public UploadSessionStartUploader uploadSessionStart()
                                              throws DbxException

Upload sessions allow you to upload a single file in one or more requests, for example where the size of the file is greater than 150 MB. This call starts a new upload session with the given data. You can then use uploadSessionAppendV2(UploadSessionCursor,boolean) to add more data and uploadSessionFinish(UploadSessionCursor,CommitInfo) to save all the data to a file in Dropbox. A single request should not upload more than 150 MB of file contents.

The close request parameter will default to false (see uploadSessionStart(boolean)).

Returns:

Uploader used to upload the request body and finish request.

Throws:

DbxException

uploadSessionStart

public UploadSessionStartUploader uploadSessionStart(boolean close)
                                              throws DbxException

Upload sessions allow you to upload a single file in one or more requests, for example where the size of the file is greater than 150 MB. This call starts a new upload session with the given data. You can then use uploadSessionAppendV2(UploadSessionCursor,boolean) to add more data and uploadSessionFinish(UploadSessionCursor,CommitInfo) to save all the data to a file in Dropbox. A single request should not upload more than 150 MB of file contents.

Parameters:

close - If true, the current session will be closed, at which point you won't be able to call uploadSessionAppendV2(UploadSessionCursor,boolean) anymore with the current session.

Returns:

Uploader used to upload the request body and finish request.

Throws:

DbxException