Using the Datastore API on Android

These days, your app needs to store and sync more than just files. With the Datastore API, structured data like contacts, to-do items, and game state can be synced effortlessly. Datastores support multiple platforms, offline access, and automatic conflict resolution.

Here are the basic concepts that underlie the Datastore API:

Account manager and datastore manager
The account manager is your starting point. It lets your app start the authentication process to link with a user's Dropbox account. Once you've linked to an account, you can create a datastore manager, which you can use to open datastores, get a list of datastores, wait for changes to multiple datastores, and so on.
Datastores and tables

Datastores are containers for your app's data. Each datastore contains a set of tables, and each table is a collection of records. As you'd expect, the table allows you to query existing records or insert new ones.

A datastore is cached locally once it's opened, allowing for fast access and offline operation. Datastores are also the unit of transactions; changes to one datastore are committed independently from another datastore. After modifying a datastore, call the sync method to sync those changes back to Dropbox and also apply changes that may have been made by other devices.

Records

Records are how your app stores data. Each record consists of a set of fields, each with a name and a value. Values can be simple objects, like strings, integers, and booleans, or they can be lists of simple objects. A record has an ID and can have any number of fields.

Unlike in SQL, tables in datastores don't have a schema, so each record can have an arbitrary set of fields. While there's no requirement to have the same fields, it makes sense for all the records in a table to have roughly the same fields so you can query over them.

Now that you're familiar with the basics, read on to learn how to get the Datastore API running in your app.

Setting up the SDK

If you want to code along with this guide, start by visiting the SDKs page for instructions on downloading the SDK and setting up your project.

Linking accounts

To start using the Datastore API, you'll need to create a DbxAccountManager object. This object lets you link to a Dropbox user's account, which is the first step to working with data on their behalf.

Each Android Activity or Fragment which interacts with Dropbox can obtain a DbxAccountManager. A good place to do so is in your onCreate() method.

Be sure to replace APP_KEY and APP_SECRET with the real values for your app.

private DbxAccountManager mAccountManager;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    mAccountManager = DbxAccountManager.getInstance(getApplicationContext(), APP_KEY, APP_SECRET);
}

The next step is to have the user start the linking flow (keep in mind, you'll need all the pieces in this section in place before it will work end-to-end). You can start the linking flow in response to a user action asking them to link to Dropbox. This example will add a new click handler to onCreate() for a button called link_button which will start the linking process. You'll also need to add a button with the same name to your activity or fragment's layout as well.

The Datastore API will automatically store the user's account info on the device once they've linked. You should check whether an account is already linked by calling hasLinkedAccount.

static final int REQUEST_LINK_TO_DBX = 0;  // This value is up to you

private Button mLinkButton;
private DbxAccountManager mAccountManager;
private DbxAccount mAccount;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    mAccountManager = DbxAccountManager.getInstance(getApplicationContext(), APP_KEY, APP_SECRET);

    mLinkButton = (Button) findViewById(R.id.link_button);
    mLinkButton.setOnClickListener(new OnClickListener() {
        @Override
        public void onClick(View v) {
            mAccountManager.startLink((Activity)MyActivity.this, REQUEST_LINK_TO_DBX);
        }
    });

    if (mAccountManager.hasLinkedAccount()) {
        mAccount = mAccountManager.getLinkedAccount();
        mLinkButton.setVisibility(View.GONE);
        // ... Now display your own UI using the linked account information.
    } else {
        mLinkButton.setVisibility(View.VISIBLE);
    }
}

Starting the linking process will launch an external Activity so your app will need to override onActivityResult() which will be called when linking is complete. You can specify any request code you want, it's just used to indicate the reason that onActivityResult() is being called (in this case, because the Dropbox account linking activity completed).

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_LINK_TO_DBX) {
        if (resultCode == Activity.RESULT_OK) {
            mAccount = mAccountManager.getLinkedAccount();
            mLinkButton.setVisibility(View.GONE);
            // ... Now display your own UI using the linked account information.
        } else {
            // ... Link failed or was cancelled by the user.
        }
    } else {
        super.onActivityResult(requestCode, resultCode, data);
    }
}

When onActivityResult() is called with the REQUEST_LINK_TO_DBX request code and RESULT_OK, you should see an info-level message in LogCat saying "Dropbox user <userid> linked." At this point, the account has been linked with the account manager.

You now have all the pieces you need to link to a user's account. Run the app and press your Link to Dropbox button. Your app should proceed through the authorization flow and return to your app with the account associated with the account manager.

Creating a datastore and your first table

With a DbxAccount in hand, the next step is to open the default datastore. Each app has its own default datastore per user.

DbxDatastore store = DbxDatastore.openDefault(mAccount);

In order to store records in a datastore, you'll need to put them in a table. Let's define a table named "tasks":

DbxTable tasksTbl = store.getTable("tasks");

In the future, you might choose to add more tables to store related sets of things such as a "settings" table for the app or a "people" table to keep track of people assigned to each task. For now, this app is really simple so you only need one table to hold all your tasks.

You've got a datastore manager, a datastore for your app, and a table for all the tasks you're about to make. Let's start storing some data.

Working with records

A record is a set of name and value pairs called fields, similar in concept to a map. Records in the same table can have different combinations of fields; there's no schema on the table which contains them. You can insert the record and add fields to it in a single line of code.

DbxRecord firstTask = tasksTbl.insert().set("taskname", "Buy milk").set("completed", false);

This task is now in memory, but hasn't been persisted to storage or synced to Dropbox. Thankfully, that's simple:

store.sync();

Sync may be a straightforward method, but it wraps some powerful functionality. Sync both saves all of your local changes and applies any remote changes as well, automatically merging and dealing with conflicts along the way. Sync even works offline; you won't apply any remote changes, but your local changes will be saved to persistent storage and synced to Dropbox when the device comes back online.

Once syncing completes, visit the datastore browser and you should see your newly created task.

Accessing data from a record is straightforward:

String taskname = firstTask.getString("taskname");

Editing tasks is just as easy. This is how you can mark the first result as completed:

firstTask.set("completed", true);
store.sync();

After the edit, calling sync will commit the edits locally and then sync them to Dropbox.

Finally, if you want to remove the record completely, just call deleteRecord().

firstTask.deleteRecord();
store.sync();

Querying records

You can query the records in a table to get a subset of records that match a set of field names and values you specify. The query method takes a set of conditions that the fields of a record must match to be returned in the result set. For each included condition, all records must have a field with that name and that field's value must be exactly equal to the specified value. For strings, this is a case-sensitive comparison (e.g. "abc" won't match "ABC").

DbxFields queryParams = new DbxFields().set("completed", false);
DbxTable.QueryResult results = tasksTbl.query(queryParams);
DbxRecord firstResult = results.iterator().next();

results provides an iterable set of DbxRecord objects.

The records that meet the specified query are not returned in any guaranteed order. The entire result set is returned so you may apply sort in memory after the request completes.

If no condition set is provided, the query will return every record in the table.

DbxTable.QueryResult results = tasksTbl.query();

Using listeners

A datastore will receive changes from other instances of your app when you call sync(). For some apps, the frequency of updates will be low; others may be rapid-fire. In either case, your app should respond as soon as those changes happen by updating the state of your app. You can do this by registering sync status listeners.

For Android, you'll use DbxDatastore.addSyncStatusListener() to register the listener. To adhere to Android's app lifecycle, it's a good idea to remove the listener when the app goes to the background. In this example, MainActivity implements the SyncStatusListener interface and uses onResume() and onPause() to add and remove itself as a listener.

public class MainActivity extends Activity implements DbxDatastore.SyncStatusListener {

    // ...

    @Override
    public void onResume() {
        super.onResume();
        mStore = DbxDatastore.openDefault(mAccount);
        mStore.addSyncStatusListener(this);
    }

    @Override
    public void onPause() {
        super.onPause();
        mStore.removeSyncStatusListener(this);
        mStore.close();
    }

    @Override
    public void onDatastoreStatusChange(DbxDatastore store) {
        if (store.getSyncStatus().hasIncoming) {
            try {
                Map<String, Set<DbxRecord>> changes = mStore.sync();
                // Handle the updated data
            } catch (DbxException e) {
                // Handle exception
            }
        }
    }

    // ...

}

The SyncStatusListener.onDatastoreStatusChange method is called whenever the state of the datastore changes, which includes downloading or uploading changes. It is also called when there are changes ready to be applied to the local state.

Checking getSyncStatus().hasIncoming in the listener lets you figure out when there are new changes that your app should respond to. If there are changes, calling sync() will apply those changes to the datastore. sync() will also return a mapping of tables to sets of records that changed as a result of the sync. Your app can update based on the set of changed records, or you can simply query the new states of the tables and update your app's views with the results.

Records and fields

The record is the smallest grouping of data in a datastore. It combines a set of fields to make a useful set of information within a table.

Record IDs

Each record has a string ID. An ID can be provided when a record is created, or one will be automatically generated and assigned if none is provided. Once a record is created, the ID cannot be changed.

Other records can refer to a given record by storing its ID. This is similar to the concept of a foreign key in SQL databases.

Field types

Records can contain a variety of field types. Earlier in this tutorial, you saw strings and booleans, but you can also specify a number of other types. Here is a complete list of all supported types:

  • String (String)
  • Boolean (boolean)
  • Integer (long) – 64 bits, signed
  • Floating point (double) – IEEE double
  • Date (Date) – POSIX-like timestamp stored with millisecond precision.
  • Bytes (byte[]) – Arbitrary data, which is treated as binary, such as thumbnail images or compressed data. Individual records can be up to 100KB, which limits the size of the blob. If you want to store larger files, you should use the Sync API and reference the paths to those files in your records.
  • List (DbxList) – A special value that can contain other values, though not other lists.

Customizing conflict resolution

Datastores automatically merge changes on a per-field basis. If, for example, a user were to edit the taskname of a task on one device and the completed status of that same task on another device, the Datastore API would merge these changes without a conflict.

Sometimes, however, there will be simultaneous changes to the same field of the same record, and this requires conflict resolution. For example, if a user were to edit the completed status of a task on two different devices while offline, it's unclear how those changes should be merged when the devices come back online. Because of this ambiguity, app developers can choose what conflict resolution rule they want to follow.

To set the conflict resolution rule, call the setResolutionRule() method on a table, and pass in the name of a field and the resolution rule you want to apply to that field.

taskTable.setResolutionRule("completed", DbxTable.ResolutionRule.LOCAL);

There are five available resolution rules that affect what happens when a remote change conflicts with a local change:

  • ResolutionRule.REMOTE – The remote value will be chosen. This is the default behavior for all fields.
  • ResolutionRule.LOCAL – The local value of the field will be chosen.
  • ResolutionRule.MAX – The greater of the two changes will be chosen.
  • ResolutionRule.MIN – The lesser of the two changes will be chosen.
  • ResolutionRule.SUM – Additions and subtractions to the value will be preserved and combined.

Note that resolution rules don't persist, so you should set any custom resolution rules after opening a datastore but before the first time you sync.