Datastores

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.

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 size

100 KiB

Maximum number of records per datastore

100,000

Maximum datastore size

10 MiB

Maximum size of a single sync() call

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

Static methods

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

Instance methods

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.

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.

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.

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.

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.

DbxDatastoreManager

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

Returns the appropriate DbxDatastoreManager for the given account, creating
it if necessary. Multiple calls with the same account will return the same object, unless
you call shutDown() or the DbxAccount has been unlinked.

Instance methods

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

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.

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

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

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.

Throws

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

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

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

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.

Parameters

DbxDatastoreInfo

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.

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

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

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

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.

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.

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.

Instance methods

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

DbxPrincipal

Constants

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

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

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.

Throws

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

Enums

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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.

Constants

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.

Values

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.