public class DbxFileSystem
extends java.lang.Object
DbxFileSystem.forAccount(com.dropbox.sync.android.DbxAccount)
.
A DbxFileSystem
allows you to list folders, and open or create files
as if they were local. You can also manipulate the directory structure
through creation, moves, renames, and deletes. The DbxFileSystem
automatically synchronizes changes with the Dropbox server in the
background. Local changes to the DbxFileSystem
are automatically
uploaded. Remote changes to file and folder info are automatically
downloaded. Remote changes to file content are downloaded when you open a
DbxFile
.
Background syncing will remain active if there are outstanding changes to upload
or download, if there are open files, or if there are any listeners registered via
DbxFileSystem.addPathListener(com.dropbox.sync.android.DbxFileSystem.PathListener, com.dropbox.sync.android.DbxPath, com.dropbox.sync.android.DbxFileSystem.PathListener.Mode)
or DbxFile.addListener(com.dropbox.sync.android.DbxFile.Listener)
. Otherwise, syncing will
be paused to preserve battery life until you access DbxFileSystem
again.
If syncing isn't active, and you want to ensure up-to-date data, call
DbxFileSystem.syncNowAndWait()
.
A DbxFileSystem
instance is tied to a linked user account, and will be shut down if
the account is unlinked. In this case, most methods will throw
DbxException.Unauthorized
.
Modifier and Type | Class and Description |
---|---|
static interface |
DbxFileSystem.PathListener
A listener to be called when there's a change at a given path, or
optionally to its descendants.
|
static interface |
DbxFileSystem.SyncStatusListener
A listener to be called when there's a change to the status of
background synchronization, as reported by
DbxFileSystem.getSyncStatus() . |
static class |
DbxFileSystem.ThumbFormat
Specifies the desired format when opening a thumbnail.
|
static class |
DbxFileSystem.ThumbSize
Specifies the desired size when opening a thumbnail.
|
Modifier and Type | Method and Description |
---|---|
void |
addPathListener(DbxFileSystem.PathListener l,
DbxPath path,
DbxFileSystem.PathListener.Mode mode)
Registers a listener that will be called when there's a change
to info or contents of a file or folder at the given path, or
optionally to its children or descendants.
|
void |
addSyncStatusListener(DbxFileSystem.SyncStatusListener l)
Registers a listener that will be called when there's a change
to the status of background synchronization, as returned by
DbxFileSystem.getSyncStatus() . |
void |
awaitFirstSync()
Waits for the first sync of this cache to be complete (as
defined by
DbxFileSystem.hasSynced() , so that valid file info is
available. |
DbxFile |
create(DbxPath path)
Creates a new file, including any nonexistent parent folders.
|
void |
createFolder(DbxPath folderPath)
Creates a new folder, including parent folders if
necessary.
|
void |
delete(DbxPath path)
Deletes a file, or recursively deletes a folder.
|
boolean |
exists(DbxPath path)
Checks whether a file or folder exists at the given path.
|
java.net.URL |
fetchShareLink(DbxPath path,
boolean shorten)
Returns a link to a specified file or folder in Dropbox,
suitable for sharing.
|
static DbxFileSystem |
forAccount(DbxAccount acct)
Returns the appropriate
DbxFileSystem for the given account, creating
it if necessary. |
DbxAccount |
getAccount()
Returns
DbxAccount associated with this DbxFileSystem . |
DbxFileInfo |
getFileInfo(DbxPath path)
Returns info about a given file or folder by path.
|
DbxSyncStatus |
getSyncStatus()
Returns the status of background synchronization.
|
boolean |
hasSynced()
Returns whether the cached state has ever been synced since
this app was first linked.
|
boolean |
isFile(DbxPath path)
Checks whether a file exists at the given path.
|
boolean |
isFolder(DbxPath path)
Checks whether a folder exists at the given path.
|
boolean |
isShutDown()
Checks whether this instance has been shut down, either explicitly with
a call to
DbxFileSystem.shutDown() , or implicitly when its account was unlinked. |
java.util.List<DbxFileInfo> |
listFolder(DbxPath path)
Lists the contents of a folder.
|
void |
move(DbxPath oldPath,
DbxPath newPath)
Moves a file or folder, including its contents, to a new location.
|
DbxFile |
open(DbxPath path)
Opens an existing file, using the latest cached revision if any exists,
or otherwise using the latest known version.
|
DbxFile |
openThumbnail(DbxPath path,
DbxFileSystem.ThumbSize size,
DbxFileSystem.ThumbFormat format)
Opens a thumbnail for existing file, using the latest cached thumbnail if any
exists, or otherwise using the latest known version of the file.
|
void |
removePathListener(DbxFileSystem.PathListener l,
DbxPath path,
DbxFileSystem.PathListener.Mode mode)
Removes a listener previously registered with
DbxFileSystem.addPathListener(com.dropbox.sync.android.DbxFileSystem.PathListener, com.dropbox.sync.android.DbxPath, com.dropbox.sync.android.DbxFileSystem.PathListener.Mode)
for a given combination of path and mode. |
void |
removePathListenerForAll(DbxFileSystem.PathListener l)
Unregisters a listener previously registered using
DbxFileSystem.addPathListener(com.dropbox.sync.android.DbxFileSystem.PathListener, com.dropbox.sync.android.DbxPath, com.dropbox.sync.android.DbxFileSystem.PathListener.Mode) ,
for all combinations of path and mode. |
void |
removeSyncStatusListener(DbxFileSystem.SyncStatusListener l)
Removes a listener previously registered with
DbxFileSystem.addSyncStatusListener(com.dropbox.sync.android.DbxFileSystem.SyncStatusListener) . |
void |
shutDown()
Shuts down this
DbxFileSystem and stops background synchronization. |
void |
syncNowAndWait()
Forces a check for new file info from the server, and waits for it
to complete.
|
public static DbxFileSystem forAccount(DbxAccount acct) throws DbxException.Unauthorized
DbxFileSystem
for the given account, creating
it if necessary.DbxException.Unauthorized
- if the account is unlinked.public void shutDown()
DbxFileSystem
and stops background synchronization.
It isn't necessary to call this method before an app terminates, but
you can call it to ensure that background synchronization is stopped
and resources are freed immediately.
Before shutting down you should ensure that all files are closed.
Outstanding changes to unclosed files may be lost. Local changes
to closed files that haven't yet been uploaded will remain queued
for upload the next time a DbxFileSystem
is created for
this account.
After this call, most DbxFileSystem
and DbxFile
methods will fail with DbxException.ApiUsage
. You should get
a new DbxFileSystem
via DbxFileSystem.forAccount(com.dropbox.sync.android.DbxAccount)
.
This method will have no effect if the DbxFileSystem is already shut down.
public boolean isShutDown()
DbxFileSystem.shutDown()
, or implicitly when its account was unlinked.public DbxAccount getAccount()
DbxAccount
associated with this DbxFileSystem
.public boolean hasSynced() throws DbxException
DbxFileSystem.listFolder(com.dropbox.sync.android.DbxPath)
will block, and any files you create may
conflict with files already on the server. Once
the first sync completes and cached state is available, this
value will remain true even after a restart.
Unlike DbxFileSystem.awaitFirstSync()
this method won't fail if
the sync fails, but will continue to return false until a
sync is successful.
DbxException
- if there's a failure getting status.public void awaitFirstSync() throws DbxException
DbxFileSystem.hasSynced()
, so that valid file info is
available.
This method will stop waiting if the first sync fails, and will throw an exception indicating the sync failure.
DbxException
- if the first sync fails.public void syncNowAndWait() throws DbxException
DbxException
- if the requested sync fails.public DbxSyncStatus getSyncStatus() throws DbxException
DbxException
- if there's a failure getting status.public void addSyncStatusListener(DbxFileSystem.SyncStatusListener l)
DbxFileSystem.getSyncStatus()
.
Adding the same listener more than once will have no effect.
A single call to DbxFileSystem.removeSyncStatusListener(com.dropbox.sync.android.DbxFileSystem.SyncStatusListener)
will cause it
to no longer be called. This method will be ignored, and listeners
won't be called if this DbxFileSystem
is shut down.
Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.
public void removeSyncStatusListener(DbxFileSystem.SyncStatusListener l)
DbxFileSystem.addSyncStatusListener(com.dropbox.sync.android.DbxFileSystem.SyncStatusListener)
.
Calling this method with a listener that was never added will have no
effect. This method will be ignored, and listeners won't be called if
this DbxFileSystem
is shut down.
public void addPathListener(DbxFileSystem.PathListener l, DbxPath path, DbxFileSystem.PathListener.Mode mode)
The same listener can be registered for a different combination
of path and type. Adding the same listener for the same
combination will have no additional effect. A single call to
DbxFileSystem.removePathListener(com.dropbox.sync.android.DbxFileSystem.PathListener, com.dropbox.sync.android.DbxPath, com.dropbox.sync.android.DbxFileSystem.PathListener.Mode)
with the same combination will remove it.
This method will be ignored, and listeners won't be called if this
DbxFileSystem
is shut down.
Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.
l
- the listener to register.path
- the path for which to listen.mode
- the type of events for which to listen.public void removePathListener(DbxFileSystem.PathListener l, DbxPath path, DbxFileSystem.PathListener.Mode mode)
DbxFileSystem.addPathListener(com.dropbox.sync.android.DbxFileSystem.PathListener, com.dropbox.sync.android.DbxPath, com.dropbox.sync.android.DbxFileSystem.PathListener.Mode)
for a given combination of path and mode.
This will remove the given listener for the given combination of path and type only, having no effect on distinct registrations of the same listener. Calling this method for a listener and parameter combination that was never registered will have no effect.
This method will be ignored, and listeners won't be called if this
DbxFileSystem
is shut down.
l
- the listener to register.path
- the path for which to listen.mode
- the type of events for which to listen.public void removePathListenerForAll(DbxFileSystem.PathListener l)
DbxFileSystem.addPathListener(com.dropbox.sync.android.DbxFileSystem.PathListener, com.dropbox.sync.android.DbxPath, com.dropbox.sync.android.DbxFileSystem.PathListener.Mode)
,
for all combinations of path and mode.
This will have no effect if the given listener was never registered.
This method will be ignored, and listeners won't be called if this
DbxFileSystem
is shut down.
public java.util.List<DbxFileInfo> listFolder(DbxPath path) throws DbxException
DbxFileSystem.hasSynced()
before returning.path
- the path to the folder.DbxException.NotFound
- if the folder doesn't exist.DbxException.InvalidParameter
- if the path refers to a file.DbxException
- if another failure occurs.public DbxFileInfo getFileInfo(DbxPath path) throws DbxException
DbxException.NotFound
- if the path doesn't exist.DbxException
- if another failure occurs.public boolean exists(DbxPath path) throws DbxException
path
- the path to check.DbxException
- if there's a failure checking file info.public boolean isFile(DbxPath path) throws DbxException
path
- the path to check.DbxException
- if there's a failure checking file info.public boolean isFolder(DbxPath path) throws DbxException
path
- the path to check.DbxException
- if there's a failure checking file info.public DbxFile open(DbxPath path) throws DbxException
DbxFile
to check the status of the download or update to a newer revision when it
becomes available.
This method will fail if the same file is already open, or if
the file doesn't exist. Use DbxFileSystem.create(DbxPath)
to create a new
file.
You must call DbxFile.close()
when you are finished with the file.
path
- the path to the file.DbxException.NotFound
- if the file doesn't exist.DbxException.InvalidParameter
- if the path refers to a folder.DbxException.AlreadyOpen
- if there's already a DbxFile
open for this file.DbxException
- if another failure occurs.public DbxFile create(DbxPath path) throws DbxException
DbxFile
to check the status of the upload, or check for newer
versions created on the server.
This method will fail if file already exists. Use DbxFileSystem.open(DbxPath)
to open an existing file.
You must call DbxFile.close()
when you are finished with the file.
path
- the path to the fileDbxException.Exists
- if the file already exists, or one
of its parents is a file rather than a folder.DbxException.InvalidParameter
- if the path refers to a folder.DbxException.AlreadyOpen
- if there's already a DbxFile
open for this file.DbxException
- if another failure occurs.public DbxFile openThumbnail(DbxPath path, DbxFileSystem.ThumbSize size, DbxFileSystem.ThumbFormat format) throws DbxException
DbxFile
to check the status of the download or update to
a newer thumbnail when it becomes available.
Thumbnails are generated on the server and cached separately. When offline
a thumbnail might be unavailable even if the file contents are available. If
a file is modified locally, the thumbnail won't be available until its
upload completes. Check the DbxFileInfo.thumbExists
field of the
file's info to see if a thumbnail is available for download.
The DbxFile
object representing a thumbnail is unrelated to any
DbxFile
opened on the file itself. Thumbnails are read-only - any
attempt to write will fail. It is possible to open multiple thumbnails (for
instance, of different sizes) on the same path.
You must call DbxFile.close()
when you are finished with the thumbnail.
path
- the path to the file.size
- the size of the thumbnail to open. The thumbnail is scaled (not cropped)
in a way which preserves the original images aspect ratio, to a size which fits within a
bounding box defined by this parameter.format
- the format for the thumbnail.DbxException.NotFound
- if the file doesn't exist.DbxException.InvalidParameter
- if the path refers to a folder.DbxException.NoThumb
- if there is no thumbnail available for this file.DbxException
- if another failure occurs.public void createFolder(DbxPath folderPath) throws DbxException
folderPath
- the path to the new folder.DbxException.Exists
- if there's a file in the way of the
specified folder.DbxException
- if another failure occurs.public void delete(DbxPath path) throws DbxException
path
- the path to the file or folder.DbxException.NotFound
- if the given path doesn't exist.DbxException.InvalidParameter
- if the given path is the root.DbxException
- if another failure occurs.public void move(DbxPath oldPath, DbxPath newPath) throws DbxException
oldPath
- the path of the file or folder.newPath
- the new path of the file or folder, including its
new name.DbxException.NotFound
- if the source path doesn't exist.DbxException.Exists
- if one of the parents of the new
path is a file rather than a folder.DbxException.InvalidParameter
- if either given path is the
root.DbxException
- if another failure occurs.public java.net.URL fetchShareLink(DbxPath path, boolean shorten) throws DbxException
This method makes a server request. It will fail if the app is offline. It shouldn't be called on the main UI thread.
path
- the path to the file or folder to share.shorten
- whether the URL should be shortened using the
Dropbox URL shortening service.DbxException.NotFound
- if the given file or folder
doesn't exist.DbxException
- if another failure occurs.