If you’re developing a content rich application that synchronizes data from server to smartphone and needs to work offline, this is the article for you.
Every once in a while, you end up working on a project that throws you out of your comfort zone and requires some heavy duty learning.
For me, it was a seemingly simple project that required things like data replication and high availability, things I vaguely remember from my college days. After some exploring, I came across Couchbase Mobile, a framework that offers support for mobile app development and covers all of the requirements.
Couchbase Mobile has two major parts:
- Couchbase Lite – an embedded, schemaless, JSON database
- Sync Gateway – a mechanism to sync data to and from the server
NOSQL
Couchbase Lite is a NOSQL database, which means that there’s no schema or a predefined data structure. It’s a document store and the documents are JSON objects. It also means that you don’t need to worry about structural changes in the data, since there’s little structure to begin with. This allows for great flexibility and little maintenance.
VIEWS
If you need to build reports, aggregate and join documents, or have different representations of the data, you can use views. Views are defined in JavaScript. They are built dynamically and don’t affect the underlying data, so you can have as many as you like.
DISTRIBUTION
Couchbase’s distribution system is incredibly complex and very powerful. It has several main characteristics, and you can fine tune your app to use any or all of them:
- Master → Slave replication
- Master ↔ Master replication
- Filtered Replication
- Incremental and bi-directional replication
- Conflict management
NETWORK AVAILABILITY
Additionally, you don’t need to take care of the changes in the network availability. The underlying network listener in the library monitors the changes, and pauses and resumes whatever replication you have running, leaving you ample space to notify the user of the current network status.
Replication itself can be one-shot or continuous. If you want to say when and what needs to be synced to or from the host, you will use one-shot replication. On the other hand, if the requirements say that data should be synced anytime a change occurs, then continuous replication is the way to go. Both replications will download the same data, but keeping continuous replication running requires minimal data traffic, in my case less than 100 kB/h.
How do I implement it?
After we’ve covered the basics, let’s see just how simple setting up an app with Couchbase Lite is. The official getting started pages are quite detailed and easy to follow. In the following example, I use the Cloudant service as the backend for my demo application, but you can setup your own host with CouchDb on it.
Here is a code example of the bare minimum needed to implement bidirectional replication from your Android application;
1. Add the repository location to the application’s root build.gradle file
buildscript {
repositories {
mavenCentral()
maven {
url "http://files.couchbase.com/maven2/"
}
mavenLocal()
}
dependencies {
classpath ’com.android.tools.build:gradle:0.9.+’
}
}
allprojects {
repositories {
mavenCentral()
maven {
url "http://files.couchbase.com/maven2/"
}
}
}
2. Add the dependency to the module’s build.gradle file
compile ’com.couchbase.lite:couchbase-lite-android:1.0.0’
3. Add the following code to your application’s main activity or fragment
//initialise the database
protected void initDB() throws IOException, CouchbaseLiteException {
// create the database manager with default options
Manager manager = new Manager(new AndroidContext(MainActivity.this), Manager.DEFAULT_OPTIONS);
// get or create the database with the provided name
database = manager.getDatabase("demodb");
// add a change listener
database.addChangeListener(databaseListener);
}
//start bi-directional syncing
protected void startSync() {
URL syncUrl;
try {
syncUrl = new URL("https://username:password" +
"@username.cloudant.com/demodb");
} catch (MalformedURLException e) {
throw new RuntimeException(e);
}
// server - client
Replication pullReplication = database.createPullReplication(syncUrl);
pullReplication.setContinuous(true);
// client - server
Replication pushReplication = database.createPushReplication(syncUrl);
pushReplication.setContinuous(true);
// replication listeners
pullReplication.addChangeListener(pullReplicationListener);
pushReplication.addChangeListener(pushReplicationListener);
// start both replications
pullReplication.start();
pushReplication.start();
}
//call those methods in the onCreate
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
try {
initDB();
startSync();
} catch (Exception e) {
e.printStackTrace();
}
}
The only thing left to do is to define some data in the database and show it to the users.
When to use Couchbase Mobile?
As always, you should find the best tool for the problem at hand. If your data is well structured and stable with no room for modification, then standard relational databases are the way to go.
If your data is flexible and should be available anytime and anywhere, this is by far the simplest solution.
