Package com.dropbox.core.v1

Class DbxClientV1

  • public final class DbxClientV1
extends java.lang.Object
    Use this class to make remote calls to the Dropbox API. You'll need an access token first, normally acquired via DbxWebAuth.

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

    • Constructor Detail

      • DbxClientV1

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

    • Method Detail

      • getRequestConfig

        public DbxRequestConfig getRequestConfig()
        Returns the DbxRequestConfig that was passed in to the constructor.

      • getAccessToken

        public java.lang.String getAccessToken()
        Returns the DbxAccessToken that was passed in to the constructor.

      • getHost

        public DbxHost getHost()
        Returns the DbxHost that was passed in to the constructor.

      • getMetadata

        public DbxEntry getMetadata​(java.lang.String path,
                            boolean includeMediaInfo)
                     throws DbxException
        Get the file or folder metadata for a given path. 
         DbxClientV1 dbxClient = ...
 DbxEntry entry = dbxClient.getMetadata("/Photos");
 if (entry == null) {
     System.out.println("No file or folder at that path.");
 } else {
     System.out.print(entry.toStringMultiline());
 }
        Parameters:
        path - The path to the file or folder (see DbxPathV1).
        includeMediaInfo - If true, then if the return value is a DbxEntry.File, it might have its photoInfo and mediaInfo fields filled in.
        Returns:
        If there is a file or folder at the given path, return the metadata for that path. If there is no file or folder there, return null.
        Throws:
        DbxException

      • getMetadataWithChildren

        public DbxEntry.WithChildren getMetadataWithChildren​(java.lang.String path,
                                                     boolean includeMediaInfo)
                                              throws DbxException
        Get the metadata for a given path; if the path refers to a folder, get all the children's metadata as well. 
         DbxClientV1 dbxClient = ...
 DbxEntry entry = dbxClient.getMetadata("/Photos");
 if (entry == null) {
     System.out.println("No file or folder at that path.");
 } else {
     System.out.print(entry.toStringMultiline());
 }
        Parameters:
        path - The path (starting with "/") to the file or folder (see DbxPathV1).
        includeMediaInfo - If true, then if the return value is a DbxEntry.File, it might have its photoInfo and mediaInfo fields filled in.
        Returns:
        If there is no file or folder at the given path, return null. Otherwise, return the metadata for that path and the metadata for all its immediate children (if it's a folder).
        Throws:
        DbxException

      • getMetadataWithChildrenC

        public <C> DbxEntry.WithChildrenC<C> getMetadataWithChildrenC​(java.lang.String path,
                                                              boolean includeMediaInfo,
                                                              Collector<DbxEntry,​? extends C> collector)
                                                       throws DbxException
        Same as getMetadataWithChildren(java.lang.String, boolean) except instead of always returning a list of DbxEntry objects, you specify a Collector that processes the DbxEntry objects one by one and aggregates them however you want.

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

        Throws:
        DbxException

      • getMetadataWithChildrenIfChanged

        public Maybe<DbxEntry.WithChildren> getMetadataWithChildrenIfChanged​(java.lang.String path,
                                                                     boolean includeMediaInfo,
                                                                     java.lang.String previousFolderHash)
                                                              throws DbxException
        Get the metadata for a given path and its children if anything has changed since the last time you got them (as determined by the value of DbxEntry.WithChildren.hash from the last result).
        Parameters:
        path - The path (starting with "/") to the file or folder (see DbxPathV1).
        previousFolderHash - The value of DbxEntry.WithChildren.hash from the last time you got the metadata for this folder (and children).
        Returns:
        Never returns null. If the folder at the given path hasn't changed since you last retrieved it (i.e. its contents match previousFolderHash), return Maybe.Nothing. If it doesn't match previousFolderHash return either Maybe.Just(null) if there's nothing there or Maybe.Just with the metadata.
        Throws:
        DbxException

      • getMetadataWithChildrenIfChangedC

        public <C> Maybe<DbxEntry.WithChildrenC<C>> getMetadataWithChildrenIfChangedC​(java.lang.String path,
                                                                              boolean includeMediaInfo,
                                                                              java.lang.String previousFolderHash,
                                                                              Collector<DbxEntry,​? extends C> collector)
                                                                       throws DbxException
        Same as getMetadataWithChildrenIfChanged(java.lang.String, boolean, java.lang.String) except instead of always returning a list of DbxEntry objects, you specify a Collector that processes the DbxEntry objects one by one and aggregates them however you want.

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

        Throws:
        DbxException

      • disableAccessToken

        public void disableAccessToken()
                        throws DbxException
        Disable the access token that you constructed this DbxClientV1 with. After calling this, API calls made with this DbxClientV1 will fail.
        Throws:
        DbxException

      • getFile

        public DbxEntry.File getFile​(java.lang.String path,
                             java.lang.String rev,
                             java.io.OutputStream target)
                      throws DbxException,
                             java.io.IOException
        Retrieves a file's content and writes it to the given OutputStream. 
         DbxClientV1 dbxClient = ...
 DbxEntry.File md;
 File target = new File("Copy of House.jpeg");
 OutputStream out = new FileOutputStream(target);
 try {
     md = dbxClient.getFile("/Photos/House.jpeg", out);
 }
 finally {
     out.close();
 }
        Parameters:
        rev - The rev of the file to retrieve, or null if you want the latest revision of the file.
        Returns:
        The downloaded file's metadata, or null
        Throws:
        java.io.IOException - If there's an error writing to target.
        DbxException

      • startGetFile

        public DbxClientV1.Downloader startGetFile​(java.lang.String path,
                                           java.lang.String rev)
                                    throws DbxException
        Retrieve a file's content and content metadata. You must call the DbxClientV1.Downloader's close() method; use a try/finally. 
         DbxClientV1 dbxClient = ...
 DbxClientV1.Downloader downloader = dbxClient.startGetFile("/ReadMe.txt")
 try {
     printStream(downloader.body)
 }
 finally {
     downloader.close()
 }
        Parameters:
        rev - The rev of the file to retrieve, or null if you want the latest revision of the file.
        path - The path (starting with "/") to the file or folder on Dropbox. (see DbxPathV1).
        Returns:
        An object that can be used to download the file contents, or null if there is no file at the requested path.
        Throws:
        DbxException

      • uploadFile

        public DbxEntry.File uploadFile​(java.lang.String targetPath,
                                DbxWriteMode writeMode,
                                long numBytes,
                                java.io.InputStream contents)
                         throws DbxException,
                                java.io.IOException
        A wrapper around uploadFile(String, DbxWriteMode, long, DbxStreamWriter) that lets you pass in an InputStream. The entire stream contents will be uploaded. 
         DbxClientV1 dbxClient = ...
 File f = new File("ReadMe.txt")
 dbxClient.uploadFile("/ReadMe.txt", DbxWriteMode.add(), f.length(), new FileInputStream(f))
        Parameters:
        targetPath - The path to the file on Dropbox (see DbxPathV1). If a file at that path already exists on Dropbox, then the writeMode parameter will determine what happens.
        writeMode - Determines what to do if there's already a file at the given targetPath.
        numBytes - The number of bytes in the given stream. Use -1 if you don't know.
        contents - The source of file contents. This stream will be automatically closed (whether or not the upload succeeds).
        Throws:
        java.io.IOException - If there's an error reading from in.
        DbxException

      • uploadFile

        public <E extends java.lang.Throwable> DbxEntry.File uploadFile​(java.lang.String targetPath,
                                                                DbxWriteMode writeMode,
                                                                long numBytes,
                                                                DbxStreamWriter<E> writer)
                                                         throws DbxException,
                                                                E extends java.lang.Throwable
        Upload file contents to Dropbox, getting contents from the given DbxStreamWriter. 
         DbxClientV1 dbxClient = ...
 // Create a file on Dropbox with 100 3-digit random numbers, one per line.
 final int numRandoms = 100;
 int fileSize = numRandoms * 4;  3 digits, plus a newline
 dbxClient.uploadFile("/Randoms.txt", DbxWriteMode.add(), fileSize,
     new DbxStreamWriter<RuntimeException>() {
         public void write(OutputStream out) throws IOException
         {
             Random rand = new Random();
             PrintWriter pw = new PrintWriter(out);
             for (int i = 0; i < numRandoms; i++) {
                 pw.printf("%03d\n", rand.nextInt(1000));
             }
             pw.flush();
         }
     });
        Parameters:
        targetPath - The path to the file on Dropbox (see DbxPathV1). If a file at that path already exists on Dropbox, then the writeMode parameter will determine what happens.
        writeMode - Determines what to do if there's already a file at the given targetPath.
        numBytes - The number of bytes you're going to upload via the returned DbxClientV1.Uploader. Use -1 if you don't know ahead of time.
        writer - A callback that will be called when it's time to actually write out the body of the file.
        Throws:
        E - If writer.write() throws an exception, it will propagate out of this function.
        DbxException
        E extends java.lang.Throwable

      • startUploadFile

        public DbxClientV1.Uploader startUploadFile​(java.lang.String targetPath,
                                            DbxWriteMode writeMode,
                                            long numBytes)
                                     throws DbxException
        Start an API request to upload a file to Dropbox. Returns a DbxClientV1.Uploader object that lets you actually send the file contents via DbxClientV1.Uploader.getBody(). When you're done copying the file body, call DbxClientV1.Uploader.finish().

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

         DbxClientV1 dbxClient = ...
 DbxClientV1.Uploader uploader = dbxClient.startUploadFile(...)
 DbxEntry.File md;
 try {
     writeMyData(uploader.body);
     md = uploader.finish();
 }
 finally {
     uploader.close();
 }
        Parameters:
        targetPath - The path to the file on Dropbox (see DbxPathV1). If a file at that path already exists on Dropbox, then the writeMode parameter will determine what happens.
        writeMode - Determines what to do if there's already a file at the given targetPath.
        numBytes - The number of bytes you're going to upload via the returned DbxClientV1.Uploader. Use -1 if you don't know ahead of time.
        Throws:
        DbxException

      • chunkedUploadFirst

        public java.lang.String chunkedUploadFirst​(byte[] data,
                                           int dataOffset,
                                           int dataLength)
                                    throws DbxException
        Upload the first chunk of a multi-chunk upload.
        Parameters:
        data - The data to append.
        dataOffset - The start offset in data to read from.
        dataLength - The number of bytes to read from data, starting from dataOffset.
        Returns:
        The ID designated by the Dropbox server to identify the chunked upload.
        Throws:
        DbxException

      • chunkedUploadFirst

        public <E extends java.lang.Throwable> java.lang.String chunkedUploadFirst​(int chunkSize,
                                                                           DbxStreamWriter<E> writer)
                                                                    throws DbxException,
                                                                           E extends java.lang.Throwable
        Upload the first chunk of a multi-chunk upload.
        Parameters:
        chunkSize - The number of bytes you're going to upload in this chunk.
        writer - A callback that will be called when it's time to actually write out the body of the chunk.
        Returns:
        The ID designated by the Dropbox server to identify the chunked upload.
        Throws:
        DbxException
        E extends java.lang.Throwable

      • chunkedUploadAppend

        public long chunkedUploadAppend​(java.lang.String uploadId,
                                long uploadOffset,
                                byte[] data,
                                int dataOffset,
                                int dataLength)
                         throws DbxException
        Append data to a chunked upload session.
        Parameters:
        uploadId - The identifier returned by chunkedUploadFirst(byte[]) to identify the chunked upload session.
        uploadOffset - The current number of bytes uploaded to the chunked upload session. The server checks this value to make sure it is correct. If it is correct, the contents of data is appended and -1 is returned. If it is incorrect, the correct offset is returned.
        data - The data to append.
        dataOffset - The start offset in data to read from.
        dataLength - The number of bytes to read from data, starting from dataOffset.
        Returns:
        If everything goes correctly, returns -1. If the given offset didn't match the actual number of bytes in the chunked upload session, returns the correct number of bytes.
        Throws:
        DbxException

      • chunkedUploadAppend

        public <E extends java.lang.Throwable> long chunkedUploadAppend​(java.lang.String uploadId,
                                                                long uploadOffset,
                                                                long chunkSize,
                                                                DbxStreamWriter<E> writer)
                                                         throws DbxException,
                                                                E extends java.lang.Throwable
        Append a chunk of data to a chunked upload session.
        Parameters:
        uploadId - The identifier returned by chunkedUploadFirst(byte[]) to identify the chunked upload session.
        uploadOffset - The current number of bytes uploaded to the chunked upload session. The server checks this value to make sure it is correct. If it is correct, the contents of data is appended and -1 is returned. If it is incorrect, the correct offset is returned.
        chunkSize - The size of the chunk.
        writer - A callback that will be called when it's time to actually write out the body of the chunk.
        Returns:
        If everything goes correctly, returns -1. If the given offset didn't match the actual number of bytes in the chunked upload session, returns the correct number of bytes.
        Throws:
        DbxException
        E extends java.lang.Throwable

      • getDelta

        public DbxDelta<DbxEntry> getDelta​(java.lang.String cursor,
                                   boolean includeMediaInfo)
                            throws DbxException
        Return "delta" entries for the contents of a user's Dropbox. This lets you efficiently keep up with the latest state of the files and folders. See DbxDelta for more documentation on what each entry means.

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

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

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

        Throws:
        DbxException

      • getDeltaWithPathPrefix

        public DbxDelta<DbxEntry> getDeltaWithPathPrefix​(java.lang.String cursor,
                                                 java.lang.String pathPrefix,
                                                 boolean includeMediaInfo)
                                          throws DbxException
        Same as getDelta(java.lang.String, boolean), except results are limited to files and folders whose paths are equal to or under the specified pathPrefix.

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

        Parameters:
        pathPrefix - A path on Dropbox to limit results to.
        Throws:
        DbxException

      • getDeltaLatestCursor

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

      • getDeltaLatestCursorWithPathPrefix

        public java.lang.String getDeltaLatestCursorWithPathPrefix​(java.lang.String pathPrefix,
                                                           boolean includeMediaInfo)
                                                    throws DbxException
        Same as getDeltaLatestCursor(boolean), except the cursor is limited to files and folders whose paths are equal to or under the specified pathPrefix.
        Parameters:
        pathPrefix - A path on Dropbox to limit the cursor to.
        Throws:
        DbxException

      • getLongpollDelta

        public DbxLongpollDeltaResult getLongpollDelta​(java.lang.String cursor,
                                               int timeout)
                                        throws DbxException
        Waits for changes to files on an account, starting from the state represented by cursor.
        Parameters:
        cursor - A cursor returned by ono of the "delta" methods.
        timeout - How long poll should run before timing out, in seconds.
        Throws:
        DbxException

      • getThumbnail

        public DbxEntry.File getThumbnail​(DbxThumbnailSize sizeBound,
                                  DbxThumbnailFormat format,
                                  java.lang.String path,
                                  java.lang.String rev,
                                  java.io.OutputStream target)
                           throws DbxException,
                                  java.io.IOException
        Downloads a thumbnail for the image file at the given path in Dropbox.
        Parameters:
        sizeBound - The returned thumbnail will never be greater than the dimensions given here.
        format - The image format to use for thumbnail data.
        path - The path to the image file on Dropbox.
        rev - The rev of the file on Dropbox or null if you want the latest revision of the file.
        target - The stream to write the thumbnail image data to.
        Returns:
        The metadata for the original file (not the thumbnail) or null if there is no file at that path.
        Throws:
        DbxException
        java.io.IOException

      • getRevisions

        public java.util.List<DbxEntry.File> getRevisions​(java.lang.String path)
                                           throws DbxException
        Gets the metadata for the current and past revisions of a file (up to some limit) at a given path.
        Parameters:
        path - The Dropbox path that you want file revision metadata for.
        Returns:
        A list of metadata objects, one for each file revision.
        Throws:
        DbxException

      • restoreFile

        public DbxEntry.File restoreFile​(java.lang.String path,
                                 java.lang.String rev)
                          throws DbxException
        Takes a copy of the file at the given revision and saves it over the current latest copy. This will create a new revision, but the file contents will match the revision you specified.
        Parameters:
        path - The Dropbox path of the file to restore.
        rev - The revision of the file you want to use to overwrite the latest revision.
        Returns:
        If the specified path/rev couldn't be found, return null. Otherwise, return metadata for the newly-created latest revision of the file.
        Throws:
        DbxException

      • searchFileAndFolderNames

        public java.util.List<DbxEntry> searchFileAndFolderNames​(java.lang.String basePath,
                                                         java.lang.String query)
                                                  throws DbxException
        Returns metadata for all files and folders whose name matches the query string.
        Parameters:
        basePath - The path to search under (recursively). Pass in "/" to search everything.
        query - A space-separated list of substrings to search for. A file matches only if it contains all the substrings.
        Returns:
        The list of metadata entries that match the search query.
        Throws:
        DbxException

      • createShareableUrl

        public java.lang.String createShareableUrl​(java.lang.String path)
                                    throws DbxException
        Creates and returns a publicly-shareable URL to a file or folder's "preview page". This URL can be used without authentication. The preview page may contain a thumbnail or some other preview of the file, along with a link to download the actual filel.
        Parameters:
        path - The Dropbox path to a file or folder.
        Returns:
        If there is no file or folder at that path, return null. Otherwise return a shareable URL.
        Throws:
        DbxException

      • createTemporaryDirectUrl

        public DbxUrlWithExpiration createTemporaryDirectUrl​(java.lang.String path)
                                              throws DbxException
        Creates and returns a publicly-shareable URL to a file's contents. This URL can be used without authentication. This link will stop working after a few hours.
        Parameters:
        path - The Dropbox path to a file.
        Returns:
        If there is no file at that path, return null. Otherwise return a shareable URL along with the expiration time.
        Throws:
        DbxException

      • createCopyRef

        public java.lang.String createCopyRef​(java.lang.String path)
                               throws DbxException
        Creates and returns a "copy ref" to a file. A copy ref can be used to copy a file across different Dropbox accounts without downloading and re-uploading.

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

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

        Parameters:
        path - The Dropbox path to a file.
        Returns:
        The copy ref's identifier, suitable for passing in to copyFromCopyRef(java.lang.String, java.lang.String), or null if the specified path does not exist.
        Throws:
        DbxException

      • copy

        public DbxEntry copy​(java.lang.String fromPath,
                     java.lang.String toPath)
              throws DbxException
        Copy a file or folder from one path in Dropbox to another path in Dropbox.
        Returns:
        If successful, returns the metadata for new copy of the file or folder, otherwise returns null.
        Throws:
        DbxException

      • createFolder

        public DbxEntry.Folder createFolder​(java.lang.String path)
                             throws DbxException
        Create a new folder in Dropbox.
        Returns:
        If successful, returns the metadata for the newly created folder, otherwise returns null.
        Throws:
        DbxException

      • delete

        public void delete​(java.lang.String path)
            throws DbxException
        Delete a file or folder from Dropbox.
        Throws:
        DbxException

      • move

        public DbxEntry move​(java.lang.String fromPath,
                     java.lang.String toPath)
              throws DbxException
        Move a file or folder from one path in Dropbox to another path in Dropbox.
        Returns:
        If successful, returns the metadata for the file or folder at its new location, otherwise returns null.
        Throws:
        DbxException