Exploring Couchbase Mobile on Android: C.R.U.D.

photo by ken banks used with permission under cc by 2.0

in previous posts, i wrote a mid-level overview of couchbase mobile and walked through getting set up in an android project.

in this post, i want to begin exploring how to use couchbase lite (cbl) in an android app.

we'll start with showing how to create, read, update, and delete some data. (this is where the crud acronym comes from that you'll often see in the database world.)

we'll progress into more sophisticated uses in later posts, but really, you can do a lot of useful things just with these steps.

almost everything occurs as an operation on a document object. using cbl turns out to be easier than most any other approach, even for extremely simple purposes.

opening or creating a database

to perform any database operation, first, we need an instance of the couchbase lite manager class. you'll see in the code below, you don't really use this class for much in simple cases.

using a manager instance, opening a database is just one line. let's take a look.

manager manager = null;
database database = null;

try {
    manager = new manager(new androidcontext(getapplicationcontext()), manager.default_options);
    database = manager.getdatabase("crud");
} catch (exception ex) {
    log.e(tag, "error getting database");
}

notice the first argument to the manager class constructor. this creates an androidcontext , which is something unique to couchbase. be sure to pass in an application context to initialize this object, as shown. anything else risks leaking memory.

the database name is something i made up for this example. you can use pretty much anything you want.

create

creating a new database entry (referred to as a document) is just one line.

document document = database.createdocument();

often you'll want to know the unique id of the document. here's the code to retrieve it.

string documentid = document.getid();

the createdocument method creates a document with a system-defined unique id. for simple applications, you may want to specify your own id. in this case, use getdocument(string id) instead. if the document doesn't already exist, it will be created.

read

knowing the id, reading a document is straightforward.

document = database.getdocument(documentid);

you can do more sophisticated work with documents and retrieval. we'll get into that another time when we delve into queries.

with a document in hand, you can pull data out of it directly using getproperty(string key) or getproperties() .

update

couchbase lite documents are stored as json. that makes it easy to manipulate them. once again, you don't really need to do anything to get going. you can manipulate documents directly using maps. here's what the code looks like to update some profile information, in this approach.

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");
}

one of the most compelling reasons to use cbl is the flexibility it gives you. this code shows how you can add a new item to your document.

profile = new hashmap<>();
profile.putall(document.getproperties());
profile.put("type", "profile");  // add a "type" to the document

try {
    document.putproperties(profile);
} catch (couchbaseliteexception ex) {
    log.e(tag, "cbl operation failed");
}

delete

call the delete method on a document to remove it from the database. the delete happens immediately

try {
    document.delete();
} catch (couchbaseliteexception ex) {
    log.e(tag, "cbl failed deleting document");
}

wrapping up

what really strikes me in this post is how much more object oriented using cbl feels, compared to something like sqlite. i hope that comes through. explaining that you call the delete method on a document to delete it feels almost silly. but, of course, that's not how it works in a lot of databases.

postscript