Apache CouchDB and Java

Rajarshi Bhose is a Senior Research Associate and Manager at the Cloud Computing Center of Excellence at SETLabs, Infosys Technologies. Kashyap Santoki works in the Cloud Computing Center of Excellence at SETLabs where he specializes in .NET, Java, and performance engineering. They can be contacted at [email protected] and [email protected].

Cloud databases are an emerging type of non-relational databases which do not follow relational algebra. Generally speaking, they are key-value oriented systems used for storing internet scale data and provide easy programmatic access. Databases suc as Amazon SimpleDB, Facebook's Cassandra, and Apache CouchDB among others fall in the category of non-relational databases that have been widely used in large consumer-based applications.

Apache CouchDB is a document-oriented, non-relational, schema-less database used for storing Internet-scale data. Apache CouchDB provides a rich set of REST-based JSON API's to access the database to perform administrative as well as CRUD operations. Apache CouchDB follows all ACID properties and also allows distributed updates and replications. Apache CouchDB is implemented on the Erlang OTP Platform.

In Apache CouchDB, the key is the "document ID" and the value is the associated document and where each document can have multiple fields. CouchDB also allows retrieving documents based on field values; this is done with the help of "views".

In this article, we demonstrate how to use CouchDB for CRUD and administrative operations using Java. We have used Java 1.6 version and CouchDB driver from Google code. The development environment is Eclipse 3.4.2 on Microsoft Windows XP-SP3 and Apache CouchDB on Fedora 9 System.

Before Your Start

This article provides a step-by-step guide for using Apache CouchDB using Java. Here we will use Java code to:

• Create a database in CouchDB,
• Store employee data (Employee number, Name, Designation, etc).
• Perform some CRUD operations on the data that is stored.
• Show the use of "Views" and how it can retrieve data based on field values.

The software we use includes:

• Apache CouchDB 0.9.0 installation
• Couchdb4j-0.1.2 jar file
• Json-lib-2.2.3-jdk15 jar file
• ezmorph-1.0 jar file
• Httpclient-4.0-beta2 jar file
• Httpcore-4.0.1 jar file
• Java 1.6
• Eclipse 3.4.2

Documents are the basic unit of data in CouchDB. They can contain any number of fields as well as attachments. Documents also contain metadata information which is maintained by the CouchDB. Fields in a CouchDB document are uniquely named and contain values of different types like text, number, boolean, lists, etc.

A CouchDB document is a simple JSON object. The following is an example of a CouchDB document:

{
 "_id":"1234",
 "_rev":"1-550825736",
 "EmployeeNo":"1",
 "Name":"Ram",
 "Unit":"Research Labs",
 "Address":"Bangalore",
}

In the above example document, EmployeeNO, Name, Unit, Address are the fields that contains values 1, Ram, Research Labs, Bangalore, respectively.

Any fields with a name starting with a _ prefix are reserved for use by CouchDB itself. Common examples for such fields are _id (document id) and _rev (document revision), as shown above.

A CouchDB database is a flat collection of all these documents. Each document is identified by a unique ID (_id).

Creating New Projects and Establishing Sessions with CouchDB

To start, you need to create a new project in Eclipse, and a new class in that project. You can then add all the previously mentioned jar files to the project. At this point, you can start writing Java code in the class you have created.

The first step in using or accessing CouchDB is to create a Session. If you don't create a Session, you won't be able to perform any operations on the CouchDB. In short, Session is mandatory. You need to provide two input parameters to create a Session -- Host name and Port. The following code shows how to create session object or how to establish Session:

Session dbSession = new Session("localhost", 5984);

Here Host name is "localhost" and Port is "5984".