public class DbxDatastoreManager
extends java.lang.Object
DbxDatastoreManager.forAccount(com.dropbox.sync.android.DbxAccount)
.
The DbxDatastoreManager
automatically synchronizes datastore changes
with the Dropbox server in the background. Background syncing will remain active if there are
outstanding changes to upload or download, or if there are open datastores, or if there is a
DbxDatastoreManager.ListListener
registered. Otherwise, syncing will be paused to preserve battery life
until you access a DbxDatastore
or register a listener again.
A DbxDatastoreManager
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 |
DbxDatastoreManager.ListListener
A listener that will be called when there's a change to the list of
known datastores.
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
DEFAULT_DATASTORE_ID
The fixed ID of the default datastore, which will appear in the results
of
DbxDatastoreManager.listDatastores() . |
Modifier and Type | Method and Description |
---|---|
void |
addListListener(DbxDatastoreManager.ListListener l)
Registers a listener that will be called when there's a change
to the list of known datastores, as returned by
DbxDatastoreManager.listDatastores() . |
DbxDatastore |
createDatastore()
Create and opens a new datastore, assigning it a new unique ID.
|
void |
deleteDatastore(java.lang.String id)
Deletes a datastore by ID.
|
static DbxDatastoreManager |
forAccount(DbxAccount acct)
Returns the appropriate
DbxDatastoreManager for the given account, creating
it if necessary. |
boolean |
isShutDown()
Checks whether this instance has been shut down, either explicitly with
a call to
DbxDatastoreManager.shutDown() , or implicitly when its account was unlinked. |
java.util.Set<DbxDatastoreInfo> |
listDatastores()
Lists the
DbxDatastoreInfo for each of the user's datastores, including
the default datastore (with ID DbxDatastoreManager.DEFAULT_DATASTORE_ID ) if it has been created. |
DbxDatastore |
openDatastore(java.lang.String id)
Open an existing datastore by its ID.
|
DbxDatastore |
openDefaultDatastore()
Opens the default datastore, which will be created if it doesn't exist.
|
void |
removeListListener(DbxDatastoreManager.ListListener l)
Removes a listener previously registered with
DbxDatastoreManager.addListListener(com.dropbox.sync.android.DbxDatastoreManager.ListListener) . |
void |
shutDown()
Shuts down this
DbxDatastoreManager and stops background synchronization. |
public static java.lang.String DEFAULT_DATASTORE_ID
DbxDatastoreManager.listDatastores()
.public static DbxDatastoreManager forAccount(DbxAccount acct) throws DbxException.Unauthorized
DbxDatastoreManager
for the given account, creating
it if necessary. Multiple calls with the same account will return the same object, unless
you call DbxDatastoreManager.shutDown()
or the DbxAccount
has been unlinked.DbxException.Unauthorized
- if the account is unlinked.public void shutDown()
DbxDatastoreManager
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 your datastores are closed. Outstanding changes to unclosed datstores may be lost. Changes that were synced to datastores before they were closed but haven't yet been uploaded will remain queued for upload the next time the datastore is opened.
After this call, most DbxDatastoreManager
and DbxDatastore
methods will throw DbxException.ApiUsage
or IllegalStateException
.
You should get a new DbxDatastoreManager
via DbxDatastoreManager.forAccount(com.dropbox.sync.android.DbxAccount)
.
This method will have no effect if the DbxDatastoreManager
is already
shut down.
public boolean isShutDown()
DbxDatastoreManager.shutDown()
, or implicitly when its account was unlinked.public java.util.Set<DbxDatastoreInfo> listDatastores() throws DbxException
DbxDatastoreInfo
for each of the user's datastores, including
the default datastore (with ID DbxDatastoreManager.DEFAULT_DATASTORE_ID
) if it has been created.DbxException
- if there is a failure listing datastores.public DbxDatastore openDatastore(java.lang.String id) throws DbxException
The same datastore can't be opened more than once. You should generally keep a
datastore open only when the relevant part of your app is on the screen, to maximize
battery life. You must call DbxDatastore.close()
when you are finished with a
Datastore.
DbxException.NotFound
- if there is no datastore of the given ID.DbxException
- if there is a failure opening the datastore.public DbxDatastore openDefaultDatastore() throws DbxException
DbxDatastoreManager.DEFAULT_DATASTORE_ID
.
The same datastore can't be opened more than once. You should generally keep
a datastore open only when the relevant part of your app is on the screen, to maximize
battery life. You must call DbxDatastore.close()
when you are finished with a
Datastore.
DbxException
- if there is a failure opening the datastore.public DbxDatastore createDatastore() throws DbxException
The same datastore can't be opened more than once. You should generally keep
a datastore open only when the relevant part of your app is on the screen, to maximize
battery life. You must call DbxDatastore.close()
when you are finished with a
Datastore.
DbxException
- if there is a failure creating the datastore.public void deleteDatastore(java.lang.String id) throws DbxException
You must close open datastores before deleting them. The default datastore can never be deleted.
DbxException
- if there is a failure deleting the datastore.public void addListListener(DbxDatastoreManager.ListListener l)
DbxDatastoreManager.listDatastores()
.
Registering a listener will keep background sync running so that you can find out about new datastores appearing on the server. When your app isn't on the screen, you should remove your listener to save power.
Adding the same listener more than once will have no effect.
A single call to DbxDatastoreManager.removeListListener(com.dropbox.sync.android.DbxDatastoreManager.ListListener)
will cause it
to no longer be called. If the DbxDatastoreManager
is shut down,
this method will be ignored, and listeners will no longer
be called.
Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.
public void removeListListener(DbxDatastoreManager.ListListener l)
DbxDatastoreManager.addListListener(com.dropbox.sync.android.DbxDatastoreManager.ListListener)
.
Calling this method with a listener that was never added will have no
effect. If the DbxDatastoreManager
is shut down,
this method will be ignored, and listeners will no longer
be called.