Couchbase-Lite-Android

by Marty Schoch ([email protected]) + Traun Leyden ([email protected])

Couchbase-Lite-Android is a ightweight embedded NoSQL database engine for Android with the built-in ability to sync to Couchbase Server on the backend. It is the Android port of Couchbase Lite iOS.

Update: The project structure recently changed, here is a mailing list post describing the change, as well as Project Structure wiki page that describes the new project structure.

Architecture

Couchbase Lite databases are able to sync with eachother via Sync Gateway backed by Couchbase Server

Documentation Overview

• This README
• Official Documentation for beta2 release
• Javadocs
• Wiki

Getting Started with Couchbase Lite

• Download and run the Grocery-Sync demo application

• Create your own Hello World Couchbase Lite via the Getting Started guide.

Developing / Contributing to Couchbase Lite

If you are just building an application with Couchbase Lite, you can skip the rest of this document. (see Getting Started with Couchbase Lite)

However, if you need to debug Couchbase Lite Android or otherwise hack on it, these instructions will help you do that.

Prerequisites

• Download Android Studio

  • If you are using the beta2 release or stable branch of Couchbase Lite, use the latest version in the stable channel (currently Android Studio 0.3.X)

  • If you are using the master branch of Couchbase Lite, use the latest version in the canary channel (currently Android Studio 0.4.3)

• Under Tools / Android / Android SDK Manager and install "Extras/Google Repository" and "Extras/Android Support Repository" (future versions of Android Studio may make this step unnecessary)

Clone the repository

Use Git to clone the Couchbase Lite repository to your local disk:

$ git clone git://github.com/couchbase/couchbase-lite-android.git
cd couchbase-lite-android
$ git submodule init && git submodule update

Configure Android Studio SDK location

• cp local.properties.example local.properties
• Customize local.properties according to your SDK installation directory

Importing Project into Android Studio

You should be able to import the project directly into Android Studio:

• Start Android Studio
• Choose File / Import and choose the couchbase-lite-android/CouchbaseLiteProject directory screenshot
• Choose Import from External Model and make sure Gradle is selected screenshot
• Check the auto-import and the Use gradle wrapper (recommended) checkboxes screenshot
• Hit Finish and wait for all tasks to finish (may take a while)

After it's finished with the import, it should look like this

Working around Import bugs

At this point, unfortunately, if you open the CBLServer class, it will look like this. Android Studio will say it cannot resolve some objects. This seems to be due to a bug in the import process.

To fix this:

• Go to File / Project Structure
• Choose Modules
• Choose the CBLite module
• Change the jackson-core-asl-1.9.2 and jackson-mapper-asl-1.9.2 dependencies from "test" to "compile" screenshot
• Hit Apply

Note: you may need to do this in other places for other libraries if you run into situations where Android Studio cannot resolve code.

Note: the above workarounds are only needed for Android Studio, and even without these the command line gradle builds should still work.

Running tests

See the Running the Test Suite wiki page.

Building and deploying maven artifacts.

If you want to host and deploy your own maven artifacts, see the upload_android_artifacts.sh script.

Example Apps

• GrocerySync
• LiteServAndroid
• CouchChatAndroid -- just a stub at this point.

Utilities

• CBLiteConsole

Requirements

• Android 2.3 Gingerbread (API level 9) and above.

License

• Apache License 2.0