Datastore API for Android documentation

Datastores are an easy way to keep an app's per-user data — like settings, bookmarks, or game state — in sync across multiple devices and operating systems. Datastores are simple embedded databases, which are synced to Dropbox.

This reference details the full set of classes needed when working with datastores. You can also read the Datastore API tutorial for a detailed example of how to use them.

Dropbox apps can work with both datastores and files at the same time and this SDK includes functionality to handle both. For more information on the classes needed to work with files, see the Sync API documentation.

General information

Local datastores

This feature allows you to create local datastores without a linked Dropbox account, so you can use Datastores without requiring the user to log in with Dropbox. Local datastores are stored on the local device, and not synced to Dropbox. You can later migrate these datastores to a Dropbox account when the user chooses to link. If a user uses your app on multiple devices in local datastores mode and later links a Dropbox account, their data will be merged together once those devices link.

Local datastores are stored in a compressed delta format which allows their contents to be merged properly without taking up extra space on the device. A compressed delta is a minimal set of changes which have the same effect as the operations your app performed on a datastore. For instance, if you set the same field multiple times, there is no need to keep all values. The one exception is modifications to a list (through DbxList), since list operations will not be compressed.

Shared datastores

Apps may want to share data between users. With the Datastore API, apps can share a datastore across multiple Dropbox accounts. The unit of sharing is a single datastore, and one or more datastores may be shared between accounts. Any datastore with a shareable ID (see "Private or shareable datastores" below) can be shared by assigning roles to principals, creating an access control list. Any Dropbox account with the correct permissions will then be able to open the shared datastore by ID.

There are two available principals to whom you may apply a role:

  • DbxPrincipal.PUBLIC – The role will apply to all Dropbox users.
  • DbxPrincipal.TEAM – The role will apply to everyone on the user's team (only applicable for Dropbox for Business accounts).

There are four available roles:

  • DbxDatastore.Role.NONE – The principal has no access to this datastore.
  • DbxDatastore.Role.VIEWER – The principal is able to view this datastore.
  • DbxDatastore.Role.EDITOR – The principal is able to edit this datastore.
  • DbxDatastore.Role.OWNER – The principal is the owner of this datastore. This role cannot be assigned directly. The user who created a datastore is always that datastore's owner.

Note that if your app is using local datastores, you can create a shareable datastore and update the permissions locally. However, the datastore can't actually be shared with others until after the user links their account to Dropbox and the data is migrated.

An example of sharing a datastore is included in the Datastore API tutorial.

Private or shareable datastores

Datastores can be created in 2 different ways, and the choice affects how they can be used. Each type of datastore can be identified by its ID.

  • Datastores with private IDs are created using DbxDatastoreManager.openOrCreateDatastore(id). Private IDs are meaningful to the developer of the app, such as "default" (for the default datastore) or "settings". The scope of private IDs is the current user-app pair. Two different devices can create datastores with the same private ID while offline, and their data will be merged when they come online.

    Private datastore IDs can be 1-64 characters containing only lowercase letters, digits, dot, hyphen or underscore, and they must not begin or end with dot.

  • Datastores with shareable IDs are created using DbxDatastoreManager.createDatastore() which allows them to be shared between users. Their IDs are auto-generated and are not only unique for the user-app pair, they're also unique across Dropbox. Shareable IDs are more appropriate when treating each datastore as an individual document where users may create an unknown number of them.

    Shareable datastore IDs (generated by the SDK) are a dot followed by 1-63 characters containing uppercase letters, lowercase letters, hyphen or underscore.

Storage size limits

Datastores have limits on their maximum size to ensure good performance across platforms. You should keep these in mind as guidelines when modeling your datastores.

Your app can store up to 5MB of data across all its datastores without counting against the user's storage quota. Any data beyond the first 5MB is factored into the user's Dropbox storage quota, and writing can be limited in these cases when a user is over quota. Sizes are calculated as:

  • The size of a datastore is calculated by summing the size of all records, plus 1000 bytes for the datastore itself.
  • The size of a record is calculated by summing the size of all values in all fields, plus 100 bytes for the record itself.
  • The size of a field is a fixed 100 bytes for the field itself plus:
    • for string or bytes values, the length in bytes of the value.
    • for List values, 20 bytes for each list element plus the size of each element.
    • for all other types, no additional contribution.
  • The size of changes made in a sync() call is calculated by summing the size of each change, plus 100 bytes for the delta itself. The size of each change is calculated by summing the size of the values contained in the change (for field updates and list put and insert operations) plus 100 bytes for the change itself.

Maximum record size100 KiB
Maximum number of records per datastore100,000
Maximum datastore size10 MiB
Maximum size of a single sync() call2 MiB

Thread safety

All classes and methods in the API are thread-safe. Changes made to a datastore are atomic and are immediately visible to other threads accessing the same datastore. Calling sync() persists datastore changes made by any thread to disk, queuing those changes for upload in the background, and also applying remote changes that have been downloaded.

DbxAccountManager

This is the entry point for the Sync API. Use this class to initialize the Sync API and link it to a user's Dropbox account. The same account linking infrastructure applies whether you want to use files and folders, or datastores, or both.

Use getInstance to get an instance of DbxAccountManager. Then call getLinkedAccount() to see if there's already a linked Dropbox account. If that returns null use startLink(Activity, int) to begin the process of linking a user's Dropbox account.

Static methods

  • DbxAccountManager getInstance(android.content.Context applicationContext, String appKey, String appSecret)

    Initializes the Dropbox Sync API if necessary, and returns an object for interacting with the Sync API. This method can be called multiple times but you must always pass the same app key and app secret.

    Parameters

    applicationContext

    the context of the current application. Must be an application context (getApplicationContext()), not just an Activity or other context.

    appKey

    your Dropbox API app key.

    appSecret

    your Dropbox API app secret.

    Throws

    DbxAccountManager.ConfigurationMismatchException

    if the app key or secret given doesn't match an earlier call.

Instance methods

  • void startLink(android.app.Activity activity, int callbackRequestCode)

    Starts the authentication process to link a new account, initiated from an Activity. This will prompt the user to log in and authorize this app to use their Dropbox account. Once linking is complete, the given activity will receive a result via Activity.onActivityResult() with the request code you specify.

    If your app is already linked, you can call this method again to prompt the user to link a different account, allowing your app to use multiple accounts at once (e.g. a personal and a business account).

    Note that if you're using an older Android SDK (prior to API 11), you may see an error about the type of the first argument to this method and the other overloads. You can avoid this error using an explicit cast of the first argument to force this method to be chosen. For instance: startLink((Activity)this, code)

    Parameters

    activity

    the Activity that will be launched when linking is complete.

    callbackRequestCode

    the request code that will be passed to the given Activity's Activity.onActivityResult() when linking is complete. This can be any value, which the API will simply pass through.

  • void startLink(android.app.Fragment fragment, int callbackRequestCode)

    Starts the authentication process to link a new account, initiated from a Fragment. This will prompt the user to log in and authorize this app to use their Dropbox account. Once linking is complete, the given activity will receive a result via Activity.onActivityResult() with the request code you specify.

    Note that if you're using an older Android SDK (prior to API 11), you may see an error about the type of the first argument to this method and the other overloads. You can avoid this error using an explicit cast of the first argument to force this method to be chosen. For instance: startLink((Fragment)this, code)

    Parameters

    fragment

    the Fragment that will be launched when linking is complete.

    callbackRequestCode

    the request code that will be passed to the given Fragment's Fragment.onActivityResult() when linking is complete. This can be any value, which the API will simply pass through.

  • void startLinkFromSupportFragment(android.support.v4.app.Fragment fragment, int callbackRequestCode)

    Starts the authentication process to link a new account, initiated from a Fragment using the V4 support library. This will prompt the user to log in and authorize this app to use their Dropbox account. Once linking is complete, the given activity will receive a result via Fragment.onActivityResult() with the request code you specify.

    This method uses a unique name to avoid compilation issues in apps which do not use the support library.

    Parameters

    fragment

    the Fragment that will be launched when linking is complete.

    callbackRequestCode

    the request code that will be passed to the given Fragment's Fragment.onActivityResult() when linking is complete. This can be any value, which the API will simply pass through.

  • void unlink()

    Unlinks this app from Dropbox. If multiple accounts have been linked, this method will unlink all of them. To unlink a single account use DbxAccount.unlink().

  • boolean hasLinkedAccount()

    Returns whether this application is linked to at least one Dropbox account.

  • DbxAccount getLinkedAccount()

    Returns the DbxAccount for the most recently linked Dropbox account, if any. If no account has been linked, this method will return null.

    If your app needs to link multiple accounts at the same time, you should use getLinkedAccounts() instead.

  • List<DbxAccount> getLinkedAccounts()

    Returns the DbxAccount for all currently linked Dropbox accounts. If no accounts have been linked, this method will return an empty list.

    The accounts are ordered from the least recently to the most recently linked.

  • void addListener(AccountListener l)

    Adds an DbxAccountManager.AccountListener which will be called whenever a new account is linked or an existing account is unlinked. The listener will be called regardless of whether the account was unlinked using DbxAccount.unlink() or by the user on the Dropbox website.

    Registering the same listener more than once will have no additional effect. A single call to removeListener() will still remove it.

  • void removeListener(AccountListener l)

    Removes a listener previously added by a call to addListener().

Constants

  • String SDK_VERSION_NAME

    The human-readable version number for this SDK.

Exceptions

DbxAccountManager.AccountListener

Interface for receiving notifications of a new account being linked or an existing account being unlinked.

Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.

Instance methods

  • void onLinkedAccountChange(DbxAccountManager mgr, DbxAccount acct)

    Called whenever a new account is linked, or an existing account is unlinked. An unlink notification indicates that the DbxFileSystem will be shut down so the app should disable Dropbox functionality.

    Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.

    Parameters

    mgr

    the account manager on which this listener was registered.

    acct

    the account that has been linked or unlinked. Examine this object to determine which one has occurred.

DbxAccount

Represents a specific user's Dropbox account.

Instance methods

  • String getUserId()

    Returns the user ID for this account.

  • boolean isLinked()

    Returns whether this account is currently linked.

  • DbxAccountInfo getAccountInfo()

    Returns the DbxAccountInfo for this account, if available, or null otherwise. Account info is fetched in the background. To be notified when account info is available or updated, use addListener().

  • void unlink()

    Unlinks this app from the user's Dropbox account. This will also shut down the corresponding DbxFileSystem and delete any locally cached data for the user.

    This method has no effect if this account isn't linked.

  • void addListener(Listener l)

    Adds a DbxAccount.Listener which will be called each time the account changes: i.e. it is unlinked, or the account info is updated.

    Registering the same listener more than once will have no additional effect. A single call to removeListener() will still remove it.

  • void removeListener(Listener l)

    Removes a listener previously added by a call to addListener().

DbxAccount.Listener

Callback interface for listeners to be notified when a specific account changes. Changes include unlinking the account, or updated account info.

Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.

Instance methods

  • void onAccountChange(DbxAccount acct)

    Called when the observed account is unlinked, or account info changes. After an account is unlinked, listeners will receive no further calls.

    Parameters

    acct

    the account on which the listener was registered.

DbxAccountInfo

Information about a user's Dropbox account.

Instance fields

  • String displayName

    The recommended string to display to identify an account. This is "userName" if orgName is null, otherwise it's "userName (orgName)".

  • String userName

    The user's name.

  • String orgName

    The user's organization's name, if available, or null otherwise.

DbxException   extends IOException, implements DbxThrowable

Base class for checked exceptions in the SDK. Inner subtypes distinguish types of Exceptions so your app can respond appropriately, but the base class can be used as a catch-all.

Instance methods

  • void rethrow()

    Re-throws this exception.

    Throws

    DbxException

    the same object on which this is called.

Exceptions

  • DbxException.AlreadyOpen   extends DbxException.InvalidOperation

    Attempt to open a file or datastore which is already open.

  • DbxException.Cancelled   extends DbxException

    An operation was cancelled by another thread.

  • DbxException.DiskSpace   extends DbxException

    Insufficient local storage space.

  • DbxException.Disallowed   extends DbxException.InvalidOperation

    The app attempted an operation that isn't allowed by its access level, or that the user does not have permission to perform.

  • DbxException.Exists   extends DbxException.InvalidOperation

    Operation failed because the target already exists.

  • DbxException.FileIO   extends DbxException

    I/O error accessing a file outside of the SDK's cache.

  • DbxException.Interrupted   extends DbxException.Cancelled

    The thread was interrupted.

  • DbxException.InvalidOperation   extends DbxException

    An attempt to perform an invalid API operation such as attempting to delete or move the root directory.

  • DbxException.Network   extends DbxException

    Network failure.

  • DbxException.NetworkConnection   extends DbxException.Network

    No network connection available.

  • DbxException.NetworkTimeout   extends DbxException.Network

    Timeout in network communication.

  • DbxException.NotFound   extends DbxException.InvalidOperation

    File, folder, or datastore doesn't exist.

  • DbxException.NoThumb   extends DbxException.InvalidOperation

    No thumbnail is available.

  • DbxException.Parent   extends DbxException.InvalidOperation

    Parent of a specified file or folder doesn't exist, or is a file rather than a folder.

  • DbxException.Quota   extends DbxException

    The user's Dropbox quota is full.

  • DbxException.Request   extends DbxException.Server

    Server indicated that a request is invalid.

  • DbxException.Response   extends DbxException.Server

    Invalid response from server.

  • DbxException.RetryLater   extends DbxException.Server

    Rate limited by the server.

  • DbxException.Server   extends DbxException

    Error reported by the Dropbox server.

  • DbxException.Ssl   extends DbxException.Network

    Failure to establish secure communication via SSL/TLS.

  • DbxException.Unauthorized   extends DbxException

    Application or user isn't authorized. This may indicate that the application has been unlinked by the user via the website.

DbxRuntimeException   extends RuntimeException, implements DbxThrowable

Base class for unchecked exceptions in the SDK. Inner subtypes distinguish types of Exceptions so your app can respond appropriately, but the base class can be used as a catch-all.

Instance methods

  • void rethrow()

    Re-throws this exception.

    Throws

    DbxRuntimeException

    the same object on which this is called.

Exceptions

  • DbxRuntimeException.AccessDenied   extends DbxRuntimeException

    Unchecked exception type used when the server denies access.

  • DbxRuntimeException.BadIndex   extends DbxRuntimeException.IllegalArgument

    Unchecked exception type used to indicate use of a bad index into a list or array.

  • DbxRuntimeException.BadState   extends DbxRuntimeException

    Unchecked exception type used to indicate an object is in a bad state for an attempted operation.

  • DbxRuntimeException.BadType   extends DbxRuntimeException

    Unchecked exception type used to indicate use of an object of the wrong type.

  • DbxRuntimeException.Cache   extends DbxRuntimeException

    Unchecked exception type used to indicate an error in the SDK's local cache storage.

  • DbxRuntimeException.Closed   extends DbxRuntimeException.BadState

    Unchecked exception type used to indicate an object was used after it was closed.

  • DbxRuntimeException.Deleted   extends DbxRuntimeException.BadState

    Unchecked exception type used to indicate an object was used after it was deleted.

  • DbxRuntimeException.IllegalArgument   extends DbxRuntimeException

    Unchecked exception type used to indicate an illegal argument passed to the SDK.

  • DbxRuntimeException.Internal   extends DbxRuntimeException

    Unchecked exception type used to indicate an internal error or assertion in the SDK.

  • DbxRuntimeException.Memory   extends DbxRuntimeException

    Unchecked exception type used to indicate memory exhaution in the SDK.

  • DbxRuntimeException.NotCached   extends DbxRuntimeException

    Unchecked exception type used to indicate a file is not in the cache when it should be.

  • DbxRuntimeException.Shutdown   extends DbxRuntimeException.BadState

    Unchecked exception type used to indicate an object was used after it was shut down.

  • DbxRuntimeException.SizeLimit   extends DbxRuntimeException

    Unchecked exception type used to indicate exceeding a fixed limit, such as the maximum size of a datastore.

  • DbxRuntimeException.System   extends DbxRuntimeException

    Unchecked exception type used to indicate an error with OS functionality (such as threads or disk I/O) inside the SDK.

DbxThrowable

A common interface for all exceptions thrown for failures in the SDK.

A DbxThrowable will always be an instance of either DbxException for checked exceptions, or DbxRuntimeException for unchecked exceptions. This interface allows those two types to be stored, manipulated, and re-thrown using a type more specific than Throwable (which could violate exception specifications).

Some methods here are duplicated from Throwable for convenience. Cast to (Throwable) to use methods not provided here.

Instance methods

  • void rethrow()

    Re-throws this instance, which will always be either a DbxException or an unchecked DbxRuntimeException.

    Throws

    DbxException

    if this instance represents a checked exception.

    DbxRuntimeException

    if this instance represents an unchecked exception.

  • String getMessage()

    Gets the failure message, as with the Throwable method.

  • Throwable getCause()

    Gets the cause of this exception, as with the Throwable method.

DbxDatastoreManager

The Datastore Manager allows you to access a user's Dropbox datastores. Get an instance using forAccount() or localManager().

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.

Static methods
Instance methods

  • DbxDatastoreManager migrateToAccount(DbxAccount acct)

    Returns a new DbxDatastoreManager created by migrating this local DbxDatastoreManager to the given account.

    This will move all datastores and data from the local DbxDatastoreManager to the new DbxDatastoreManager. The new manager will immediately begin uploading to the server, and merging with any existing changes on the server.

    The data is moved not copied, so the local datastore manager will be empty after migration. Migration should be done to a freshly linked account which contains no unuploaded datastore changes. If that isn't the case, any datastore changes in the target account will be overwritten by the migrated data.

    This must be called on a local DbxDatastoreManager, and all of its datastores must be closed. If the account provided ever had a DbxDatastoreManager it must be shut down. After this call, the current local DbxDatastoreManager will be shut down and emptied.

    Throws

    DbxRuntimeException.BadState

    if the pre-requisites above are not met.

  • void shutDown()

    Shuts down this 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. Unsynced changes to unclosed datstores will 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 DbxRuntimeException.Shutdown or DbxRuntimeException.Closed. You should get a new DbxDatastoreManager via forAccount().

    This method will have no effect if the DbxDatastoreManager is already shut down.

  • boolean isShutDown()

    Checks whether this instance has been shut down, either explicitly with a call to shutDown(), or implicitly when its account was unlinked.

  • boolean isLocal()

    Whether this is the local manager.

  • Set<DbxDatastoreInfo> listDatastores()

    Lists the DbxDatastoreInfo for each of the user's datastores, including the default datastore (with ID DEFAULT_DATASTORE_ID) if it has been created.

    Throws

    DbxException

    if there is a failure listing datastores.

  • Map<String, DbxDatastoreInfo> listDatastoreInfo()

    Returns a map of ID to the DbxDatastoreInfo for each of the user's datastores, including the default datastore (with ID DEFAULT_DATASTORE_ID) if it has been created.

    This method returns the most recent information from the server, but is overridden with the local version any time a local datastore has been changed and DbxDatastore.sync() has been called (i.e. the changes have not yet been uploaded to the server).

    Throws

    DbxException

    if there is a failure listing datastores.

  • DbxDatastore openDatastore(String id)

    Open an existing datastore by its 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.

    Throws

    DbxException.NotFound

    if there is no datastore of the given ID.

    DbxException

    if there is a failure opening the datastore.

  • DbxDatastore openOrCreateDatastore(String id)

    Opens the datastore with the given ID, creating it if it does not already exist.

    Datastores can be created offline with this method, and their contents will be merged with any datastore of the same name when the app is online again.

    The same datastore can't be opened more than once. You should generally keep a datastore open only when your the relevant part of app is on the screen, to maximize battery life. You must call DbxDatastore.close() when you are finished with a Datastore.

    See DbxDatastore.isValidId() for a description of valid strings for a datastore ID.

    Throws

    DbxException

    if there is a failure opening the datastore.

  • DbxDatastore openDefaultDatastore()

    Opens the default datastore, which will be created if it doesn't exist. The default datastore is identified by a fixed ID defined by 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.

    Throws

    DbxException

    if there is a failure opening the datastore.

  • DbxDatastore createDatastore()

    Create and opens a new datastore, assigning it a new unique 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.

    Throws

    DbxException

    if there is a failure creating the datastore.

  • void deleteDatastore(String id)

    Deletes a datastore by ID.

    You must close open datastores before deleting them.

    Throws

    DbxException

    if there is a failure deleting the datastore.

  • void uncacheDatastore(String id)

    Removes a datastore from the local cache.

    You must close open datastores before uncaching them.

    Any changes not yet uploaded to the server are discarded on uncache. If the datastore has such changes its DbxDatastoreStatus.hasOutgoing is true. The next time a datastore is opened its entire snapshot is downloaded from the server.

    Throws

    DbxException

    if there is a failure uncaching the datastore.

  • void addListListener(ListListener l)

    Registers a listener that will be called when there's a change to the list of known datastores, as returned by 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 removeListListener() 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.

  • void removeListListener(ListListener l)

    Removes a listener previously registered with addListListener().

    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.

Constants

  • String DEFAULT_DATASTORE_ID

    The fixed ID of the default datastore, which will appear in the results of listDatastores().

DbxDatastoreManager.ListListener

A listener that will be called when there's a change to the list of known datastores. The listener can call DbxDatastoreManager.listDatastores() to get the latest list.

Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.

Instance methods

  • void onDatastoreListChange(DbxDatastoreManager mgr)

    Called when there's a change to the list of known datastores. The listener can call DbxDatastoreManager.listDatastores() to get the latest list.

    Parameters

    mgr

    the DbxDatastoreManager on which the listener was registered.

DbxDatastoreInfo

Info about a Dropbox datastore.

Instance fields

  • String id

    The ID of the datastore.

  • String title

    The title of the datastore, or null if none is set.

  • Date mtime

    The last modified time of the datastore, or null if none is set.

    The last modified time is automatically updated on each call to DbxDatastore.sync() which commits local changes, or incorporates remote changes. The timestamp is based on the local clock of the device where the change is made.

  • Role role

    The current user's role with respect to this datastore.

Instance methods

  • boolean isShareable()

    Returns whether this DbxDatastore can be shared with other users. (This is currently equivalent to whether the ID starts with ".".)

  • boolean isWritable()

    Returns whether this DbxDatastore is writable by the current user. (This is currently equivalent to whether the role is EDITOR or OWNER.)

DbxDatastore

A datastore is a container for app data. A DbxDatastore lets you interact with tables and records. To get an instance, call openDefault(), DbxDatastoreManager.createDatastore(), or DbxDatastoreManager.openDatastore().

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 sync(). After 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 sync(), which will also resolve any conflict with your local changes.

When a datastore is open it will monitor for remote changes, reported in 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 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).

Static methods

  • DbxDatastore openDefault(DbxAccount acct)

    Opens the default datastore for the given 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 close() when you are finished with a Datastore.

    Throws

    DbxException

    if there is a problem opening the datastore.

  • DbxDatastore openDefaultLocal(DbxAccountManager acctMgr)

    Opens the default local datastore for the given DbxAccountManager.

    The same datastore can't be opened more than once. You must call close() when you are finished with a Datastore.

    Throws

    DbxException

    if there is a problem opening the datastore.

  • boolean isValidId(String id)

    Returns whether id is a valid ID for a DbxDatastore. Datastore IDs come in 2 forms:

    Private datastores (such as the default datastore) use IDs which can be 1-64 characters long, must not begin or end with a '.', and may contain lower-case letters, digits, and these punctuation characters: . - _ (Note that older SDKs limited these to 32 characters, so take care if your datastore needs to be accessed by legacy clients.)

    Shareable datastore IDs (created with DbxDatastoreManager.createDatastore()) always begin with a '.' and can contain 1-63 additional characters which can be upper-case, lower-case, digits, and these punctuation characters: . -

  • boolean isValidShareableId(String id)

    Returns whether id is a valid shareable ID for a DbxDatastore. This a valid datastore ID (see isValidId) that starts with a '.'.

Instance methods

  • void close()

    Closes this datastore, and ceases monitoring for updates. This must be called to release this datastore when you're finished with it.

    Any changes you committed with a call to 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 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.

  • boolean isOpen()

    Returns whether this DbxDatastore is currently open (i.e. it has not been closed).

  • boolean isShareable()

    Returns whether this DbxDatastore can be shared with other users. (This is currently equivalent to whether the ID starts with ".".)

  • Role getEffectiveRole()

    Return the current user's effective role for this datastore.

  • Map<DbxPrincipal, Role> listRoles()

    Return a map representing the ACL (Access Control List) for this datastore. This is a map from DbxPrincipal to DbxDatastore.Role containing the principals and roles that have been set by setRole() (and not deleted by deleteRole()).

    Throws

    DbxRuntimeException.IllegalArgument

    if the datastore is not shareable.

  • Role getRole(DbxPrincipal principal)

    Return a principal's role for this datastore, as listed in the ACL.

    Throws

    DbxRuntimeException.IllegalArgument

    if the datastore is not shareable.

  • void setRole(DbxPrincipal principal, Role role)

    Set a principal's role for this datastore in the ACL, overwriting any previous role. Setting the role to NONE is the same as calling deleteRole().

    Throws

    DbxRuntimeException.IllegalArgument

    if the datastore is not shareable.

  • void deleteRole(DbxPrincipal principal)

    Delete a principal's role for this datastore in the ACL. This is the same as setting the role to NONE.

    Throws

    DbxRuntimeException.IllegalArgument

    if the datastore is not shareable.

  • boolean isWritable()

    Returns whether this DbxDatastore is writable by the current user. (This is currently equivalent to whether the role is EDITOR or OWNER.)

  • DbxDatastoreManager getManager()

    Returns the DbxDatastoreManager that manages this datastore.

  • String getId()

    Returns the ID of this datastore.

  • DbxTable getTable(String id)

    Returns a reference to the table with the given ID in this datastore. If this is a new table ID, the table won't be visible to a call to getTables() until a record is inserted.

  • Set<DbxTable> getTables()

    Returns a set of all tables in the datastore that currently contain any records.

  • String getTitle()

    Returns the title of this datastore, or null if none is set.

  • long getSize()

    Returns the size of this datastore in bytes. The overall size of a datastore is calculated by summing the size of all records, plus the base size of an empty datastore itself.

  • long getRecordCount()

    Returns the total number of records in this datastore.

  • long getUnsyncedChangesSize()

    Returns the size in bytes of changes that will be queued for upload by the next call to sync().

  • Date getMtime()

    Returns the last modified time of this datastore, or null if no data has been synced yet.

    The last modified time is automatically updated on each call to sync() which commits local changes, or incorporates remote changes. The timestamp is based on the local clock of the device where the change is made.

  • void setTitle(String title)

    Sets the title of this datastore. Setting it to null will delete the title field.

  • Map<String, Set<DbxRecord>> sync()

    Apply all outstanding changes to the datastore, and also incorporate remote changes into this datastore. This method does not wait for network I/O, but does wait for disk I/O. When this method returns, all local changes have been safely saved to disk, and will be uploaded in the background.

    Returns a map from table IDs to sets of DbxRecords. 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.

    Throws

    DbxException.NotFound

    if the datastore was deleted on the server.

    DbxException

    if there is a problem updating local state.

  • DbxDatastoreStatus getSyncStatus()

    Returns the current status of synchronizing this datastore.

  • void addSyncStatusListener(SyncStatusListener l)

    Adds a listener that will be called when there's a change to the sync status of this datastore, as returned by getSyncStatus().

    Adding the same listener multiple times will have no additional effect. A single call to removeSyncStatusListener() 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.

  • void removeSyncStatusListener(SyncStatusListener l)

    Removes a listener previously registered with addSyncStatusListener().

    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.

Constants

  • long DATASTORE_SIZE_LIMIT

    The maximum size in bytes of a datastore.

  • long UNSYNCED_CHANGES_SIZE_LIMIT

    The maximum size in bytes of changes that can be queued up between calls to sync().

  • long RECORD_COUNT_LIMIT

    The maximum number of records in a datastore.

  • long BASE_DATASTORE_SIZE

    The size in bytes of a datastore before accounting for the size of its records.

    The overall size of a datastore is this value plus the size of all records.

  • long BASE_UNSYNCED_CHANGES_SIZE

    The size in bytes of unsynced changes before accounting for the size of each change.

    The overall size of unsynced changes is this value plus the size of each change.

  • long BASE_CHANGE_SIZE

    The size in bytes of a change before accounting for the size of its values.

    The overall size of a change is this value plus the size of the values in the change.

Enums

  • DbxDatastore.Role

    The roles that a user can have with respect to a datastore.

    Values

    NONE

    No access.

    VIEWER

    Read-only access.

    EDITOR

    Read-write access.

    OWNER

    Full access. A datastore can have only one owner, and their access cannot be taken away.

DbxDatastore.SyncStatusListener

A listener that will be called when there's a change to the sync status of this datastore.

Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.

Instance methods

  • void onDatastoreStatusChange(DbxDatastore ds)

    Called when there's a change to the sync status of this datastore

    Parameters

    ds

    the datastore on which this listener was registered.

DbxDatastoreStatus

Sync status for a DbxDatastore, including any errors that are preventing syncing.

Instance fields

  • boolean isConnected

    Set when the API is in active communication with the server, so that remote changes are likely to be visible quickly, and local changes can be uploaded soon. The API will attempt to connect when datastores are open, but may fail if offline.

  • boolean isDownloading

    Set when there are remote changes that need to be downloaded from the server. Always set when a DbxDatastore is opened until the first successful check for updates. Always set for a local datastore.

  • boolean isUploading

    Set when there are local changes that need to be uploaded to the server. Always set for a local datastore that has any changes at all.

  • boolean hasIncoming

    Set when there are remote changes that will be incorporated by the next call to DbxDatastore.sync().

  • boolean hasOutgoing

    Set when there are local changes that haven't yet been committed by a call to DbxDatastore.sync().

  • boolean needsReset

    Set when the datastore needs to be reset with a call to DbxDatastore.close() followed by DbxDatastoreManager.uncacheDatastore().

  • DbxThrowable downloadError

    The current error preventing remote datastore state from being downloaded, or null if there is currently no failure.

  • DbxThrowable uploadError

    The current error preventing local datastore state from being uploaded, or null if there is currently no failure.

Instance methods

  • DbxThrowable anyError()

    An error (downloadError or uploadError) affecting this datastore, or null if there is no error. This is a convenience method for determining whether any operation is currently failing.

DbxPrincipal

Constants

  • DbxPrincipal TEAM

    The principal used to represent access for DfB team members of the datastore's owner. If the owner is not a member of a DfB team, changing access for this principal has no effect (but it will still be recorded in the ACL).

  • DbxPrincipal PUBLIC

    The principal used to represent access for everyone.

DbxTable

A collection of records that lets you query for existing records or insert new ones. To get an instance call DbxDatastore.getTable().

A table object is a convenience for querying and accessing records with a given table ID. The table in the datastore only exists based on the presence of records with its table ID, and a table doesn't enforce any schema on the fields of individual records.

Static methods

  • boolean isValidId(String id)

    Returns whether id is a valid ID for a DbxTable. IDs are case-sensitive, can be 1-64 characters long and may contain alphanumeric characters plus these punctuation characters: . - _ + / = IDs with a leading colon (:) are also valid, but reserved for internal use. (Note that older SDKs limited these to 32 characters, so take care if your datastore needs to be accessed by legacy clients.)

Instance methods

  • DbxDatastore getDatastore()

    Returns the DbxDatastore that contains this table.

  • String getId()

    Returns the ID of this table.

  • void setResolutionRule(String fieldName, ResolutionRule rule)

    Set rule as the resolution pattern for conflicts involving the field of the given name in all records in this table. Any previously-set resolution rule for the same field of the same table will be replaced. The new resolution rule will be applied when merging local changes with remote changes during a call to DbxDatastore.sync() or during a background upload.

    Resolution rules aren't persistent. When you open a DbxDatastore, you should always set up any non-default resolution rules before you make any changes to a given table. Any background conflict resolutions will use the rules in force at the time the change was made, but new changes will use the default rule unless you specify otherwise.

  • DbxRecord get(String id)

    Returns the record with the given ID, or null if the record doesn't exist.

    Throws

    DbxException

    if there is a failure reading the saved state of this table.

  • DbxRecord getOrInsert(String id)

    Returns the record with the given ID, or inserts a new record with the given ID and no fields.

    Throws

    DbxException

    if there is a failure reading or modifying the saved state of this table.

  • DbxRecord getOrInsert(String id, DbxFields fields)

    Returns the record with the given ID, or inserts a new record with the given ID and a copy of the given fields.

    Throws

    DbxException

    if there is a failure reading the saved state of this table.

  • DbxRecord insert()

    Inserts a new record with no fields, generating a new unique ID for the resulting record.

  • DbxRecord insert(DbxFields fields)

    Inserts a new record with a copy of the given the given field values, generating a new unique ID.

  • QueryResult query()

    Returns all records in this table.

    Throws

    DbxException

    if there is a failure reading the saved state of this table.

  • QueryResult query(DbxFields fields)

    Queries for records that contain all of the given fields, with the same values as the given object. Queries will compare long and double values by converting to double, but will not compare values of any other distinct types.

    Throws

    DbxException

    if there is a failure reading the saved state of this table.

Enums

  • DbxTable.ResolutionRule

    Constants to specify the possible conflict resolution rules for a field in setResolutionRule().

    Values

    REMOTE

    Resolves conflicts by selecting the remote change from the Dropbox server. This is the default conflict resolution rule.

    LOCAL

    Resolves conflicts by selecting the local change on this client.

    MAX

    Resolves conflicts by selecting the largest value, based on type-specific ordering, described in DbxFields.ValueType.

    MIN

    Resolves conflicts by selecting the smallest value, based on type-specific ordering, described in DbxFields.ValueType.

    SUM

    Resolves conflicts by calculating a value such that all additions to or subtractions from a numerical value are preserved and combined. This allows a numerical value to act as a counter or accumulator without losing any updates.

    For non-numerical values this resolution rule behaves as REMOTE.

DbxTable.QueryResult   implements Iterable

Represents the records returned by a query on a DbxTable.

Instance methods

  • boolean hasResults()

    Returns whether this result includes any records.

  • int count()

    Returns the number of records in this query result.

  • Iterator<DbxRecord> iterator()

    Returns an iterator which can be used to enumerate the resulting records.

  • List<DbxRecord> asList()

    Returns a list containing all the resulting records, loaded into memory. The resulting list can be freely modified (e.g. sorted), and doing so will affect the view of the data through this query object (e.g. through iterator(). Modifying the list won't cause records to be inserted or deleted in the datastore.

DbxRecord   extends DbxFields

A record represents an entry in a particular table in a datastore. A record has a unique ID, and contains a set of fields, each of which has a name and a value. Get an instance by calling DbxTable methods such as DbxTable.query() or DbxTable.get().

A DbxRecord represents a direct view of the datastore. Changes to the DbxRecord are immediately visible via access to the same DbxDatastore, and a call to DbxDatastore.sync() that incorporates remote changes will change the state of any outstanding DbxRecord objects.

A DbxRecord is an instance of DbxFields, supporting all the same methods, and can be used for methods such as DbxTable.query(DbxFields) and setAll(). Fields are identified by name, and have a value of one of the types defined by DbxFields.ValueType. Fields can never have a null value. Fields can be retrieved by name and type. Illegal field access will be signaled by an exception: DbxRuntimeException.IllegalArgument, or DbxRuntimeException.BadType.

Static methods

  • boolean isValidId(String id)

    Returns true if id is a valid ID for a DbxRecord. IDs are case-sensitive, can be 1-64 characters long and may contain alphanumeric characters plus these punctuation characters: . - _ + / = IDs with a leading colon (:) are also valid, but reserved for internal use. (Note that older SDKs limited these to 32 characters, so take care if your datastore needs to be accessed by legacy clients.)

Instance methods

  • DbxTable getTable()

    Returns the table that contains this record.

  • String getId()

    Returns the ID of this record.

  • boolean isDeleted()

    Returns whether this record has been deleted. A deleted record has no fields, and can't be modified.

  • void deleteRecord()

    Deletes this record. This method has no effect on a record that is already deleted.

  • long getSize()

    Returns the size of this record in bytes. The size of a record is calculated by summing the size of all values in all fields, plus the base size of an empty record itself.

  • boolean hasField(String name)

    Returns whether a field with the given name is set.

  • ValueType getFieldType(String name)

    Returns the type of value in the field with the given name, or null if the field isn't set.

  • boolean getBoolean(String name)

    Returns the value of a boolean field of the given name, which must exist and be of the correct type.

  • long getLong(String name)

    Returns the value of a long field of the given name, which must exist and be of the correct type. This method won't convert a double or boolean field to a long.

  • double getDouble(String name)

    Returns the value of a double field of the given name, which must exist and be of a numerical type. If the field value is a long, this method will silently convert it to a double. No conversion is performed on other field types.

  • String getString(String name)

    Returns the value of a String field of the given name, which must exist and be of the correct type.

  • byte[] getBytes(String name)

    Returns the value of a byte field of the given name, which must exist and be of the correct type.

  • Date getDate(String name)

    Returns the value of a Date field of the given name, which must exist and be of the correct type.

  • DbxList getList(String name)

    Returns a DbxList object for reading and writing the contents of a List field of the given name. The given field must exist and contain a list.

    Changes made via the DbxList are immediately reflected in the field value.

  • DbxList getOrCreateList(String name)

    Returns a DbxList object for reading and writing the contents of a List field of the given name. The field must not be of a non-list type, but if it isn't set, an empty DbxList will be created.

    Changes made via the DbxList are immediately reflected in the field value.

  • DbxRecord set(String name, boolean value)

    Sets a field with the given name to the given boolean value, replacing any prior value.

    Returns a reference to this object, to allow for call chaining.

  • DbxRecord set(String name, long value)

    Sets a field with the given name to the given long value, replacing any prior value.

    Returns a reference to this object, to allow for call chaining.

  • DbxRecord set(String name, double value)

    Sets a field with the given name to the given double value, replacing any prior value.

    Returns a reference to this object, to allow for call chaining.

  • DbxRecord set(String name, String value)

    Sets a field with the given name to the given String value, replacing any prior value. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxRecord set(String name, byte[] value)

    Sets a field with the given name to the given byte value, replacing any prior value. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxRecord set(String name, Date value)

    Sets a field with the given name to the given Date value, replacing any prior value. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxRecord set(String name, DbxList value)

    Sets a field with the given name to List value with a copy of the contents of the given DbxList, replacing any prior value. The value must not be null.

    Setting a list in this way won't allow automatic conflict resolution on items within the list. If you need that, you should modify lists using a DbxList obtained from getList() or getOrCreateList().

    Returns a reference to this object, to allow for call chaining.

  • DbxRecord setAll(DbxFields fields)

    Copies all of the fields from the given object to this object, replacing any prior values. The argument must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxRecord deleteField(String name)

    Removes the field with the given name. This method has no effect if the given field isn't set.

    Returns a reference to this object, to allow for call chaining.

  • Set<String> fieldNames()

    Returns a set containing the names of all of the fields that are set.

Constants

  • long RECORD_SIZE_LIMIT

    The maximum size in bytes of a record.

  • long BASE_RECORD_SIZE

    The size in bytes of a record before accounting for the size of its fields.

    The overall size of a record is this value plus the sum of the sizes of its fields.

DbxList

Allows you to access a list value, which might be stored in a field in a DbxRecord or DbxFields, or might be a temporary list created by a constructor and not saved in any field. If the list is located in a record (obtained by a call to DbxRecord.getList() or DbxRecord.getOrCreateList()) or DbxFields, the DbxList represents a direct view of the value of the field in place. DbxList methods can be used to change the field, and any changes to the field will be immediately visible (locally).

Changes to a list field through DbxList methods will be automatically merged with other changes made to the same field by combining the effective set of put (set), insert (add), delete (remove), and move operations which result.

Lists are heterogeneous, able to hold elements of different types. List elements can hold the same types as field values, with the exception of other lists. List elements can't be null. DbxList elements are addressed by a 0-based index, like a Java List. The index at the end of the list can be used only when adding new elements to the list.

Constructors

  • DbxList()

    Creates new empty DbxList which can hold a list not yet inserted into any records. Such an object can be used to repeatedly set the same list in many fields or records.

  • DbxList(DbxList list)

    Creates new DbxList holding a list not yet inserted into any records. The list is initialized with a copy of the contents of the given list. Such an object can be used to repeatedly set the same list in many fields or records.

Instance methods

  • boolean isEmpty()

    Returns whether this list is empty.

  • int size()

    Returns the number of elements in this list.

  • void clear()

    Deletes all elements from this list.

    This operation will override any parallel changes rather than merging with them.

  • AtomType getType(int index)

    Returns the type of the element at the given index.

  • boolean getBoolean(int index)

    Returns the value of a boolean element at the given index, which must exist and be of the correct type.

  • long getLong(int index)

    Returns the value of a long element at the given index, which must exist and be of the correct type. This method won't convert a double or boolean field to a long.

  • double getDouble(int index)

    Returns the value of a double element at the given index, which must exist and be of a numerical type. If the field value is a long, this method will silently convert it to a double. No conversion is performed on other field types.

  • String getString(int index)

    Returns the value of a String element at the given index, which must exist and be of the correct type.

  • byte[] getBytes(int index)

    Returns the value of a byte element at the given index, which must exist and be of the correct type.

  • Date getDate(int index)

    Returns the value of a Date element at the given index, which must exist and be of the correct type.

  • DbxList add(boolean elem)

    Adds the given boolean value, appending it to the end of the list.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(long elem)

    Adds the given long value, appending it to the end of the list.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(double elem)

    Adds the given double value, appending it to the end of the list.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(String elem)

    Adds the given String value, appending it to the end of the list. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(byte[] elem)

    Adds the given byte value, appending it to the end of the list. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(Date elem)

    Adds the given Date value, appending it to the end of the list. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(int index, boolean elem)

    Adds the given boolean value, inserting it at the given index in the list.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(int index, long elem)

    Adds the given long value, inserting it at the given index in the list.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(int index, double elem)

    Adds the given double value, inserting it at the given index in the list.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(int index, String elem)

    Adds the given String value, inserting it at the given index in the list. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(int index, byte[] elem)

    Adds the given byte value, inserting it at the given index in the list. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxList add(int index, Date elem)

    Adds the given Date value, inserting it at the given index in the list. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxList set(int index, boolean elem)

    Replaces the element at the given index with a new boolean value.

    Returns a reference to this object, to allow for call chaining.

  • DbxList set(int index, long elem)

    Replaces the element at the given index with a new long value.

    Returns a reference to this object, to allow for call chaining.

  • DbxList set(int index, double elem)

    Replaces the element at the given index with a new double value.

    Returns a reference to this object, to allow for call chaining.

  • DbxList set(int index, String elem)

    Replaces the element at the given index with a new String value. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxList set(int index, byte[] elem)

    Replaces the element at the given index with a new String value. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxList set(int index, Date elem)

    Replaces the element at the given index with a new Date value. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxList remove(int index)

    Removes the element at the given index, which must exist.

    Returns a reference to this object, to allow for call chaining.

  • DbxList move(int oldindex, int newIndex)

    Moves the element at oldIndex (which must exist) to a position such that its index in the modified list will be newIndex.

    Returns a reference to this object, to allow for call chaining.

Constants

  • long BASE_ITEM_SIZE

    The size in bytes of a list item before accounting for the size of its value.

    The overall size of a list item is this value plus the size of the element.

DbxFields

Allows you to access a set of fields, which might be stored in a record in a datastore, or might be a temporary set not yet saved in a record. If the fields are located in a record, DbxFields methods can be used to change the record, and any changes to the record will be seen immediately. A temporary DbxFields created by one of the constructors in this class is saved only in memory, but can be used to set fields in a record.

Fields are identified by name, and have a value of one of the types defined by DbxFields.ValueType. Fields can never have a null value. Fields can be retrieved by name and type. Illegal field access will be signaled by an exception: DbxRuntimeException.IllegalArgument, or DbxRuntimeException.BadType.

Static methods

  • boolean isValidFieldName(String name)

    Returns true if id is a valid name for a field in a DbxRecord. Field names are case-sensitive, can be 1-64 characters long and may contain alphanumeric characters plus these punctuation characters: . - _ + / = Field names with a leading colon (:) are also valid, but reserved for internal use. (Note that older SDKs limited these to 32 characters, so take care if your datastore needs to be accessed by legacy clients.)

Constructors

  • DbxFields()

    Creates a new temporary set of fields held in memory, without being included in a record. Such an object can be used to repeatedly set the same values in many records, or to perform queries.

  • DbxFields(DbxFields fields)

    Creates a new temporary set of fields held in memory, without being included in a record. The given set of fields are copied into the new object. Such an object can be used to repeatedly set the same values in many records, or to perform queries.

Instance methods

  • boolean hasField(String name)

    Returns whether a field with the given name is set.

  • ValueType getFieldType(String name)

    Returns the type of value in the field with the given name, or null if the field isn't set.

  • boolean getBoolean(String name)

    Returns the value of a boolean field with the given name, which must exist and be of the correct type.

  • long getLong(String name)

    Returns the value of a long field of the given name, which must exist and be of the correct type. This method won't convert a double or boolean field to a double.

  • double getDouble(String name)

    Returns the value of a double field of the given name, which must exist and be of a numerical type. If the field value is a long, this method will silently convert it to a double. No conversion is performed on other field types.

  • String getString(String name)

    Returns the value of a String field of the given name, which must exist and be of the correct type.

  • byte[] getBytes(String name)

    Returns the value of a byte field of the given name, which must exist and be of the correct type.

  • Date getDate(String name)

    Returns the value of a Date field of the given name, which must exist and be of the correct type.

  • DbxList getList(String name)

    Returns a DbxList object for reading and writing the contents of a List field of the given name. The given field must exist and contain a list.

    Changes made via the DbxList are immediately reflected in the field value.

  • DbxList getOrCreateList(String name)

    Returns a DbxList object for reading and writing the contents of a List field of the given name. The field must not be of a non-list type, but if it isn't set, an empty DbxList will be created.

    Changes made via the DbxList are immediately reflected in the field value.

  • DbxFields set(String name, boolean value)

    Sets a field with the given name to the given boolean value, replacing any prior value.

    Returns a reference to this object, to allow for call chaining.

  • DbxFields set(String name, long value)

    Sets a field with the given name to the given long value, replacing any prior value.

    Returns a reference to this object, to allow for call chaining.

  • DbxFields set(String name, double value)

    Sets a field with the given name to the given double value, replacing any prior value.

    Returns a reference to this object, to allow for call chaining.

  • DbxFields set(String name, String value)

    Sets a field with the given name to the given String value, replacing any prior value. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxFields set(String name, byte[] value)

    Sets a field with the given name to the given byte value replacing any prior value. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxFields set(String name, Date value)

    Sets a field with the given name to the given Date value, replacing any prior value. The value must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxFields set(String name, DbxList value)

    Sets a field with the given name to List value with a copy of the contents of the given DbxList, replacing any prior value. The value must not be null.

    Setting a list in this way won't allow automatic conflict resolution on items within the list. If you need that, you should modify lists using a DbxList obtained from getList() or getOrCreateList().

    Returns a reference to this object, to allow for call chaining.

  • DbxFields setAll(DbxFields fields)

    Copies all of the fields from the given object to this object, replacing any prior values. The argument must not be null.

    Returns a reference to this object, to allow for call chaining.

  • DbxFields deleteField(String name)

    Removes the field with the given name. This method has no effect if the given field isn't set.

    Returns a reference to this object, to allow for call chaining.

  • Set<String> fieldNames()

    Returns a set containing the names of all of the fields that are set.

Constants

  • long BASE_FIELD_SIZE

    The size in bytes of a field before accounting for the sizes of its values.

    The overall size of a field is this value plus:

    String and byte[] The length in bytes of the value.
    DbxList The sum of the size of each list item, where each item's size is computed as the size of the item value plus DbxList.BASE_ITEM_SIZE.
    Other types No additional contribution to the size of the field.

Enums

  • DbxFields.AtomType

    The atomic value types: those which can be included in lists. These include all of the types in DbxFields.ValueType, with the exception of lists, which can't be nested within other lists.

    Fields must be read using the appropriate typed method on DbxFields or DbxList. Automatic conversion is provided if you request a double value from a long field (not the reverse), but no other type conversion is performed.

    Atoms use the ordering defined in DbxFields.ValueType.

    Values

    BOOLEAN

    A datastore value corresponding to a Java boolean.

    LONG

    A datastore value corresponding to a Java long. A long value will be automatically converted to a double if requested (but not the reverse).

    DOUBLE

    A datastore value corresponding to a Java double.

    STRING

    A datastore value corresponding to a Java String. Strings in a datastore are stored in a UTF-8 encoding.

    BYTES

    A datastore value holding arbitrary bytes, accessed as a byte[].

    DATE

    A datastore value corresponding to a Java Date.

  • DbxFields.ValueType

    The possible types of datastore field values, as stored on the server. Most value types are also members of DbxFields.AtomType which is the more limited set of values which can be included in lists.

    Fields must be read using the appropriate typed method on DbxFields or DbxList. Automatic conversion is provided if you request a double value from a long field (not the reverse), but no other type conversion is performed.

    Values have a sort order based on their type. LONG, DOUBLE, BOOLEAN, and DATE values are ordered by their numerical value. STRING, BYTES, and LIST values are lexicographically ordered. LONG and DOUBLE values are compared to each other by casting to double. Other values of distinct types are ordered by type, in the order that they are listed here. For example, all BOOL values are ordered before all numeric (LONG and DOUBLE) values.

    Values

    BOOLEAN

    A datastore value corresponding to a Java boolean.

    LONG

    A datastore value corresponding to a Java long. A long value will be automatically converted to a double if requested (but not the reverse).

    DOUBLE

    A datastore value corresponding to a Java double.

    STRING

    A datastore value corresponding to a Java String. Strings in a datastore are stored in a UTF-8 encoding.

    BYTES

    A datastore value holding arbitrary bytes, accessed as a byte[].

    DATE

    A datastore value corresponding to a Java Date.

    LIST

    A datastore value that can hold a list of atomic values (those taken from the types in DbxFields.AtomType). Lists need not be homogeneous: they can hold elements of multiple types.