public class DbxDatastore
extends java.lang.Object
DbxDatastore
lets you interact
with tables and records. To get an instance, call DbxDatastore.openDefault(com.dropbox.sync.android.DbxAccount)
,
DbxDatastoreManager.createDatastore()
, or DbxDatastoreManager.openDatastore(java.lang.String)
.
A DbxDatastore
will automatically synchronizes datastore changes
with the Dropbox server in the background. Local changes to a DbxDatastore
are visible immediately through the methods of the object, but not saved to disk until you
call DbxDatastore.sync()
. After DbxDatastore.sync()
the changes are automatically uploaded, and will
continue uploading even after the DbxDatastore
is closed. Remote changes to an open
DbxDatastore
are automatically downloaded and will become visible on the next
call to DbxDatastore.sync()
, which will also resolve any conflict with your local changes.
When a datastore is open it will monitor for remote changes, reported in DbxDatastore.getSyncStatus()
or to any DbxDatastore.SyncStatusListener
you register. You should generally keep a datastore open
only when the relevant part of your app is on the screen.
You must call DbxDatastore.close()
when you are finished with a datastore.
After a datastore is closed, any outstanding uploads will proceed in the background as
long as your app is running (or until the DbxDatastoreManager
is shut down or the
DbxAccount
unlinked).
Modifier and Type | Class and Description |
---|---|
static interface |
DbxDatastore.SyncStatusListener
A listener that will be called when there's a change to the sync
status of this datastore.
|
Modifier and Type | Method and Description |
---|---|
void |
addSyncStatusListener(DbxDatastore.SyncStatusListener l)
Adds a listener that will be called when there's a change to the sync
status of this datastore, as returned by
DbxDatastore.getSyncStatus() . |
void |
close()
Closes this datastore, and ceases monitoring for updates.
|
boolean |
equals(java.lang.Object other) |
java.lang.String |
getId()
Returns the ID of this datastore.
|
DbxDatastoreManager |
getManager()
Returns the
DbxDatastoreManager that manages this datastore. |
DbxDatastoreStatus |
getSyncStatus()
Returns the current status of synchronizing this datastore.
|
DbxTable |
getTable(java.lang.String id)
Returns a reference to the table with the given ID in this datastore.
|
java.util.Set<DbxTable> |
getTables()
Returns a set of all tables in the datastore that currently contain any records.
|
int |
hashCode() |
boolean |
isOpen()
Returns whether this
DbxDatastore is currently open (i.e. |
static DbxDatastore |
openDefault(DbxAccount acct)
Opens the default datastore for the given
DbxAccount . |
void |
removeSyncStatusListener(DbxDatastore.SyncStatusListener l)
Removes a listener previously registered with
DbxDatastore.addSyncStatusListener(com.dropbox.sync.android.DbxDatastore.SyncStatusListener) . |
java.util.Map<java.util.Set<DbxRecord>> |
sync()
Apply all outstanding changes to the datastore, and also incorporate remote changes
into this datastore.
|
java.lang.String |
toString() |
public static DbxDatastore openDefault(DbxAccount acct) throws DbxException
DbxAccount
. Equivalent to
DbxDatastoreManager.openDefaultDatastore()
.
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 problem opening the datastore.public void close()
Any changes you committed with a call to DbxDatastore.sync()
are safe on disk,
and will continue to upload in the background until the DbxDatastoreManager
is shut down, after which they will remain queued until the next time you open
this datastore. Any changes made since the last call to DbxDatastore.sync()
will be
discarded.
You must close a datastore when you're done using it to indicate to the Sync API that you are no longer interested in receiving updates for this datastore. After a call to this method, the Datastore can no longer be used and listeners will no longer be called. You must open the datastore again if you want to access it.
public boolean isOpen()
DbxDatastore
is currently open (i.e. it has not
been closed).public DbxDatastoreManager getManager()
DbxDatastoreManager
that manages this datastore.public java.lang.String getId()
public DbxTable getTable(java.lang.String id)
DbxDatastore.getTables()
until a record is inserted.public java.util.Set<DbxTable> getTables()
public java.util.Map<java.util.Set<DbxRecord>> sync() throws DbxException
Returns a map from table IDs to sets of DbxRecord
s. These correspond to the
tables and records that changed due to remote changes applied during this sync.
Records deleted on the server will be included in the list, and you can call
DbxRecord.isDeleted()
to detect them. If nothing was changed remotely,
the result is an empty map.
DbxException.NotFound
- if the datastore was deleted on the server.DbxException
- if there is a problem updating local state.public DbxDatastoreStatus getSyncStatus()
public void addSyncStatusListener(DbxDatastore.SyncStatusListener l)
DbxDatastore.getSyncStatus()
.
Adding the same listener multiple times will have no additional effect. A
single call to DbxDatastore.removeSyncStatusListener(com.dropbox.sync.android.DbxDatastore.SyncStatusListener)
will still remove it. If the
datastore is closed, 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 removeSyncStatusListener(DbxDatastore.SyncStatusListener l)
DbxDatastore.addSyncStatusListener(com.dropbox.sync.android.DbxDatastore.SyncStatusListener)
.
Calling this method with a listener that was never added will have no effect. If the datastore is closed, this method will be ignored, and listeners will no longer be called.
public boolean equals(java.lang.Object other)
equals
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object