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

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. If your app uses multiple processes, you must make use of the Datastore API in only a single process, to avoid conflicting access to the cache on disk.

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.

The overall size of a datastore is calculated by summing the sizes of all values of all fields, plus 1000 bytes for the datastore itself. 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.

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. 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), or aren't using the Android support library, 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.

    Throws

    DbxAccountManager.MultipleAccountsException

    if there's already an account linked.

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

    Starts the authentication process to link a new account. 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.

    Note that if you're using an older Android SDK (prior to API 11), or aren't using the Android support library, 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.

    Throws

    DbxAccountManager.MultipleAccountsException

    if there's already an account linked.

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

    Starts the authentication process to link a new account. 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.

    Note that if you're using an older Android SDK (prior to API 11), or aren't using the Android support library, 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.

    Throws

    DbxAccountManager.MultipleAccountsException

    if there's already an account linked.

  • void unlink()

    Unlinks this app from the user's Dropbox account.

  • boolean hasLinkedAccount()

    Returns whether this application is linked to a Dropbox account.

  • DbxAccount getLinkedAccount()

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

  • 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.MultipleAccountsException   extends IllegalStateException

    Thrown when the app attempts to link with a Dropbox account while already linked.

  • DbxAccountManager.ConfigurationMismatchException   extends IllegalArgumentException

    Thrown when getInstance() was called with two different configurations in the same application.

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

Base class for exceptions. Inner subtypes distinguish types of Exceptions so your app can respond appropriately.

Exceptions
  • DbxException.AlreadyOpen   extends DbxException

    Specified file is already open.

  • DbxException.ApiUsage   extends DbxException

    Specific usage or arguments.

  • DbxException.Disallowed   extends DbxException

    The app attempted an operation that isn't allowed by its access level.

  • DbxException.Exists   extends DbxException

    Specified file or folder already exists.

  • DbxException.DiskSpace   extends DbxException.RecoverableSystem

    Insufficient storage space.

  • DbxException.InvalidParameter   extends DbxException

    Bad parameter value, such as attempting to delete or move the root directory.

  • DbxException.Network   extends DbxException

    Network failure.

  • DbxException.NetworkConnection   extends DbxException

    Failure to establish a network connection.

  • DbxException.NetworkTimeout   extends DbxException

    Network timeout.

  • DbxException.NotFound   extends DbxException

    Specified file or folder doesn't exist.

  • DbxException.NoThumb   extends DbxException

    No thumbnail is available.

  • DbxException.Parent   extends DbxException

    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.RecoverableSystem   extends DbxException

    System failure that should be recoverable in some way.

  • DbxException.Server   extends DbxException

    Error reported by the server.

  • DbxException.Ssl   extends DbxException

    Failure to establish SSL communication.

  • 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.

DbxDatastoreManager

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

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
  • 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 DbxException.ApiUsage or IllegalStateException. 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.

  • 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.

  • 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 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. The default datastore can never be deleted.

    Throws

    DbxException

    if there is a failure deleting 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.

This class provides the datastore ID, and will provide more metadata in future.

Instance fields
  • String id

    The ID of the datastore.

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.

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).

  • 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.

  • 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.

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.

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.

  • boolean isUploading

    Set when there are local changes that need to be uploaded to the server.

  • 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 comitted by a call to DbxDatastore.sync().

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-32 characters long and may contain alphanumeric characters plus these punctuation characters: . - _ + / = IDs with a leading colon (:) are also valid, but reserved for internal use.

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.

Exceptions
  • DbxTable.IllegalTableId   extends IllegalArgumentException

    Thrown when an illegal table ID is given. IDs are case-sensitive, can be 1-32 characters long and contain alphanumeric characters plus these punctuation characters: . - _ + / =

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: DbxFields.FieldNotFound, DbxFields.IllegalFieldName, or DbxFields.WrongValueType.

Static methods
  • boolean isValidId(String id)

    Returns true if id is a valid ID for a DbxRecord. IDs are case-sensitive, can be 1-32 characters long and may contain alphanumeric characters plus these punctuation characters: . - _ + / = IDs with a leading colon (:) are also valid, but reserved for internal use.

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.

  • 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 an incompatible type (or DbxFields.WrongValueType will be thrown), but if it isn't set, an empty DbxList will be created.

  • 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.

Exceptions
  • DbxRecord.IllegalRecordId   extends IllegalArgumentException

    Thrown when an illegal record ID is given. IDs are case-sensitive, can be 1-32 characters long and contain alphanumeric characters plus these punctuation characters: . - _ + / =

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.

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: DbxFields.FieldNotFound, DbxFields.IllegalFieldName, or DbxFields.WrongValueType.

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-32 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.

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 an incompatible type, but if it isn't set, an empty DbxList will be created.

  • 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.

Exceptions
  • DbxFields.FieldNotFound   extends IllegalArgumentException

    Thrown when attempting to get the value of a field that isn't present.

  • DbxFields.IllegalFieldName   extends IllegalArgumentException

    Thrown when an illegal field name is given. Field names are case-sensitive, can be 1-32 characters long and contain alphanumeric characters plus these punctuation characters: . - _ + / =

  • DbxFields.WrongValueType   extends ClassCastException

    Thrown when attempting to get a field that isn't of the specified type.

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.