Photo of Oldest Known Map

Photo of the Oldest Known Map

Photo courtesy of cea + with permission under license CC BY 2.0

In this post I’d like to continue exploring fundamental elements of Couchbase Mobile on Android.  Much of the information will apply to iOS as well.  Look for more on iOS specifically and cross-platform tools coming up.

You can read a mid-level overview of why I’m a convert to NoSQL and using Couchbase Lite instead of SQLite and other storage options for mobile here.

This post will get you up and running on Android in a couple of minutes.  And this one explores basic database operations.  You’ll see in that post I use Maps extensively.

Dealing with JSON directly

You can do a lot with maps.  Often you’ll pull data into other structures like lists, too.  That may be all you ever need.  Here’s an example of the kind of typecast needed.

In the example app, I stored a set of comments as an string array.  You still have to pull the array based on a key, but from there you can handle it as a list.

A touch more sophistication

For more sophisticated applications, you may want to convert your documents fully into objects.

There are several libraries around for converting JSON to/from Java Objects.  The standard APIs on Android for handling JSON have some real limitations, but it is built in, so that’s an advantage.  Google has a library, Gson.  Gson can handle cases where you don’t have access to source.  I found it interesting to read the Gson Design Document to get deeper insight into other considerations when handling JSON.

In this post I’m going to talk about another popular JSON library, Jackson.  Jackson is quite mature, supports three different approaches to handling JSON, and has a strong reputation for efficiency.


Read the details about the three modes for Jackson here if you like.  Most app developer will probably want to use the databinding approach.  This sounds perhaps a little intimidating, but it’s really not.  Databinding here just refers to matching the JSON to properties of an object in some automated way.

For example, databinding means taking this

and using it to create an instance of this

Jackson is quite good at figuring out how to do this without help.  Since the fields above are all declared public, there’s nothing else to do.  Assuming the JSON data is in a Map called “map”, this snippet will fill out the a Contact instance.

If the JSON above represents the data in a Couchbase document, the code would be something like this.

This works if the fields aren’t public if there are corresponding getters and setters.

A little help: Annotations

Finally, you can get into truly fine-grained control of your object construction using Annotations.  Jackson Annotations are powerful.  A complete description is beyond the scope of this blog.  You can read a good guide describing them here.

POJO (Plain Old Java Objects)1

To aid in using Annotations, I found it useful to start with a base class.  Here’s the code.

The first annotation @JsonInclude(Include.NON_NULL) instructs Jackson to ignore null fields (i.e. stuff missing from the data).

The next three annotations, along with the code, allow Jackson to handle any unspecified fields.  Jackson will happily stuff anything you haven’t told it about into the additionalProperties map.  This means you can change your data around without worrying about your code blowing up.  Needless to say, this could allow real mistakes to slip unnoticed, so use with caution!

Finally, in case you want to avoid doing it yourself, here’s a link to a tool that can help automate annotating classes:

Final Note

Couchbase Lite currently uses Jackson internally.  Many people would recommend not relying on this.  I point this out in case you run into library conflicts or other issues.


Check out more resources on our developer portal and follow us on Twitter @CouchbaseDev. You can post questions on our forums. And we actively participate on Stack Overflow.

You can follow me personally at @HodGreeley


Posted by Hod Greeley, Developer Advocate, Couchbase

Hod Greeley is a Developer Advocate for Couchbase, living in Silicon Valley. He has over two decades of experience as a software engineer and engineering manager. He has worked in a variety of software fields, including computational physics and chemistry, computer and network security, finance, and mobile. Prior to joining Couchbase in 2016, Hod led developer relations for mobile at Samsung. Hod holds a Ph.D. in chemical physics from Columbia University.

Leave a reply