Begin with Couchbase Lite on Android

This blog post provides the basic steps to create a simple android app based on Couchbase Lite database. This app will demonstrate how to configure couchbase for your android app, create a database , create a document and modify it.

Note : This sample app demonstrated through blog post has been created using ADT 23.0.0 and Eclipse Kepler 4.3

1. Set up a simple android app using File->New->Project->Android Application Project . Fill the necessary information and choose minimum sdk version to be 2.3 as recommended for using couchbase database.

2. Open manifest and add the following permission as

<uses-permission android:name="android.permission.INTERNET" />  

Save the AndroidManifest.xml file.


3. Next step is to add the prerequisites for the couchbase lite's smooth implementation for android.

• Download the latest version of Couchbase Lite from http://www.couchbase.com/download#cb-mobile.
• Decompress the zip file.
• Copy all the files into the libs folder in the your project.
• Download http://cl.ly/Pr1r/td_collator_so.jar.
• Rename the downloaded td_collator_so.jar file to td_collator_so.zip.
• Decompress the td_collator_so.zip file.
• The zip file decompresses into a lib directory that contains several folders:
• Copy all of the files into the libs folder in the project

4. Now before getting into the coding lets first understand the basic classes that we are going to deal with in this sample.

    Manager : Class which provide a shared instance that acts as controller or collection of multiple couchbase lite databases.

    Database : Class representing the couchbase database for android.
   
    Document : Class representing  the documents which stores the actual data. The data in the form of Map is set as properties to the document.
    Map objects provide JSON-compatible representations of data that are suitable for creating documents that you can store in the database.
   
    One most important thing is to provide a valid name to the method that creates the database.
    A database name can consist of only lowercase alphabetic characters (a-z), digits (0-9) and a few special characters (_$()+-/), so it’s important to validate the name.
   
    When the document is saved to the database, Couchbase Lite generates a document identifier property named _id and a revision identifier property named _rev, and adds them to the document. The generated _id for the newly created document is available via the getId() method of the Document class.
   
   
   
5. Now we will explain the major steps for creating a database , creating a document and then deleting a document.

 Creating Manager
        

try
{
  Manager mCouchbaseManager =  

   new Manager(getApplicationContext().getFilesDir(), Manager.DEFAULT_OPTIONS);
}
catch (IOException e)
{
  e.printStackTrace();
}

       

Checking validity for name and Creating Database  

if (Manager.isValidDatabaseName(iDatabaseName))
{
  try
  {
    Database mCouchbaseDatabase = mCouchbaseManager.getDatabase(iDatabaseName);
  }
  catch (CouchbaseLiteException e)
  {
    e.printStackTrace();
  }
}

Creating a document and adding data to it.
   
         // Creating map that will hold the actual data to be set into the document          

 Map<String, Object> docContent = new HashMap<String, Object>();
 docContent.put("content","Sample data content for the document");
 docContent.put("time", "2014-01-01");

   
        // Create a document and add the following content to it.         

Document document = mCouchbaseDatabase.createDocument();
document.putProperties(docContent);

           
        // Save id for the document          

String docId = document.getId();

   
       
 Deleting a document
          

 boolean deleteDocSuccess = mCouchbaseDatabase.getDocument(docId).delete();

Please find the complete source code here SourceCode