Couchbase Lite (CBL) on Android

Table of Contents

What you’ll build
What you’ll need
How to complete this guide
Setup
Code
Run
Summary

This guide walks you through a series of basic database operations with Couchbase Lite on Android.

What you’ll build

You’ll build an Android application consisting of a single Activity. Within the Activity, you’ll perform Create, Read, Update, and Delete (CRUD) operations in a new database. The database will be stored locally on the device.

What you’ll need

15 minutes
Android Studio (version 2 or later)

How to complete this guide

This guide assumes you know how to create an application with Android Studio, using at least one Android Activity.

You will need to know how to launch an application, either in an Android Virtual Device, or on an actual device. See the Android Studio documentation for details.

You will need to include the Couchbase Lite external libraries. In this guide, we will use Gradle to import the libraries automatically. There is no need to download the package yourself.

Setup

Create a new project in Android Studio. Be sure to use API level 10 or higher.

Add a dependency for Couchbase Lite to the app Gradle build file. To do this, open build.gradle (Module: app) in Studio. In the dependencies section, add

compile 'com.couchbase.lite:couchbase-lite-android:1.2.1'

You may also need to add the following snippet to the android section.

// workaround for "duplicate files during packaging of APK" issue
// see https://groups.google.com/d/msg/adt-dev/bl5Rc4Szpzg/wC8cylTWuIEJ
packagingOptions {
    exclude 'META-INF/ASL2.0'
    exclude 'META-INF/LICENSE'
    exclude 'META-INF/NOTICE'
}

Code

After following the steps above, we’re ready to code CRUD operations in Couchbase Lite.

We don’t list the import statements that go along with this code, since Studio will create them automatically. For reference, the upper level package containing the CBL classes is com.couchbase.lite.

Opening a database

Opening a database takes just a couple of lines of code. You first need a database manager object. Note the context required here is not the standard Android context. Instead, we will need to create an instance of CBL’s AndroidContext, initialized from an Android Context. Here’s the code.

Manager manager = null;
Database database = null;

try {
    manager = new Manager(new AndroidContext(this), Manager.DEFAULT_OPTIONS);
    database = manager.getDatabase("crud");
} catch (Exception ex) {
    Log.e(TAG, "Error getting database");
}

Creating a document

Documents are fed in and out of the database in the form of Java Maps. This code snippet creates a new document object and commits the first revision.

Document document = database.createDocument();
String documentId = document.getId();

Map<String, Object> profile = new HashMap<>();
profile.put("firstName", "Hod");
profile.put("lastName", "Greeley");

try {
    document.putProperties(profile);
} catch (CouchbaseLiteException ex) {
    Log.e(TAG, "CBL operation failed");
}

It’s important to know here that the call to document.putProperties() both populates the document object and writes it to the local CBL storage.

Reading a document

document = database.getDocument(documentId);

profile = new HashMap<>();
profile.putAll(document.getProperties());

The getProperties() method returns an immutable map. In this example, we copy the contents into a HashMap so we can make changes.

In other cases, you might want to create a POJO. CBL uses the Jackson project for handling JSON, so those libraries are already available in your app.

Updating a document

Updating a document is nearly identical to creating one. In the code snippet, we add a type to the profile map. Calling putProperties then updates the database. Again, this causes the document to updated in the local storage. No other steps are needed.

profile.put("type", "profile");

try {
    document.putProperties(profile);
} catch (CouchbaseLiteException ex) {
    Log.e(TAG, "CBL operation failed");
}

Couchbase has an idea of document "revisions", which you can read about in the main documentation. If you examine the document after this update, you can see the revision number has increased by one.

Deleting a document

Deleting a document is a single, straightforward call.

try {
    document.delete();
} catch (CouchbaseLiteException ex) {
    Log.e(TAG, "Error deleting document");
}

It’s also possible to do things like query the delete status of the document.

Run

At this point, the code is ready to run. We haven’t added any code to display contents of documents. You may wish to add logging statements and examine output on the console, or even step through the application with the debugger to see the results.

Summary

Congratulations! You’ve just developed an Android app that uses Couchbase Lite.

couchbase-guides/java-android