Logo Icon Logo
A Crowd-sourced Cookbook on Writing Great Android® Apps
GitHub logo Twitter logo OReilly Book Cover Art
Save Data in the cloud with CouchDB and EktorpBack to Android Cookbook Home | Up to Chapter: Data Persistence

Author: Ian Darwin ('idarwin')
In Published Edition? No
FormatLanguage: WikiFormat

Save Data in the cloud with CouchDB and Ektorp


You want to persist data locally and have it backed to a persistence store in the cloud.


CouchBase is an enhanced (and still open source) version of Apache CouchDB, one of the leading non-SQL (or "noSQL") databases. There are mobile versions of CouchBase for Android and for iOS at present, with others under consideration. Ektorp is an open source mapping extension for Couch which provides JPA-like functionality.


Before you start, bear in mind that the download footprint of this combination, with the DB server and all the pieces needed, is over four megabytes, tiny by today's desktop standards but larger than many Android or iOS applications. Dozens of small files must be archived each time you save any file in Eclipse; if you save multiple files you will notice the delay. And it takes a while to load into the emulator, too; the following times were observed on a 2GHz 2GB Core 2 Duo MacBook:

[2011-09-29 18:12:53 - CouchEktorpDemo] Uploading CouchEktorpDemo.apk onto device 'emulator-5554'
[2011-09-29 18:13:01 - CouchEktorpDemo] Installing CouchEktorpDemo.apk...
[2011-09-29 18:13:34 - CouchEktorpDemo] Success!
[2011-09-29 18:13:34 - CouchEktorpDemo] Starting activity com.darwinsys.couchektorp.MainActivity on device emulator-5554

At any rate, follow these steps:

  1. If starting with an existing project, be sure to commit the current state of the project in your version control system, as CouchBase will make some changes to your AndroidManifest and other files.
  2. Download and unzip the Couchbase distribution.
  3. CouchBase Mobile for Android provides an Ant build script to modify an existing Eclipse Android project; it adds various Jar files to your project classpath, and also the native code for the database mini-server. Copy the two files couchbase.xml and CouchBase.zip (note case) into the root of your Eclipse Android project.
  4. Run the Ant build, either in the command line ant (cd $WORKSPACE/$project; ant -f couchbase.xml) or using the built-in Ant runner in Eclipse (open Ant view, drag couchbase.xml to it, select it, click the green Run button above it).
  5. The above step modified your project, so Refresh it for Eclipse (right-click the project and select Refresh, or hit F5 if that works for you). Note that some NDK libraries are installed in the libs/ folder; they "must" be located in a folder of that name for Android to download them.
  6. You can now remove the two files manually added earlier, as their contents have been assimilated into your project.
  7. Create an instance of ICouchbaseDelegate (see mDelegate in the code example below).
  8. Download the Ektorp sample project, and add its Jar files to the libs directory and to your ClassPath.
  9. Setup an httpclient for Ektorp to talk to the server with.
  10. rather incomplete...
import org.ektorp.*;
import org.ektorp.android.http.AndroidHttpClient;
import org.ektorp.impl.StdCouchDbInstance;
import org.ektorp.support.DesignDocument;

import android.app.Activity;
import android.content.ServiceConnection;
import android.content.SharedPreferences;
import android.os.Bundle;
import android.preference.PreferenceManager;
import android.text.method.DigitsKeyListener;
import android.util.Log;
import android.widget.EditText;

import com.couchbase.android.CouchbaseMobile;
import com.couchbase.android.ICouchbaseDelegate;

public class MainActivity extends Activity {
	// Instance of ICouchbaseDelegate and its two required method stubs
	private final ICouchbaseDelegate mDelegate = new ICouchbaseDelegate() {
	    public void couchbaseStarted(String host, int port) {
	    	Log.d("database", "CouchDB server started on port " + port);

	    public void exit(String error) {}
	// Instance of Couch ServiceConnection
	private ServiceConnection couchServiceConnection;

    /** Called when the activity is first created. */
    public void onCreate(Bundle savedInstanceState) {
        EditText valueId=(EditText)findViewById(R.id.valueId);
        DigitsKeyListener onlyNumbers = DigitsKeyListener.getInstance(true,true);//allows digits with positive/negative signs and decimal points

	private void startCouchDB() {
		CouchbaseMobile couch = new CouchbaseMobile(getBaseContext(), mDelegate);
		couchServiceConnection = couch.startCouchbase();

Lots more code to come here...

See Also

The CouchBase Grocery Sync example.