JAX-RS + Cloudant in Bluemix as a service and Worklight App as a client

In the service side, I developed a very simple JAX-RS service which retrieve JSON documents of a Cloudant Database using ektrop over Bluemix.

Below is the JAX-RS service code:

package com.test.todos.service;

import java.util.ArrayList;
import java.util.List;

import javax.naming.InitialContext;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import org.ektorp.CouchDbConnector;
import org.ektorp.CouchDbInstance;

public class TodoService {
    protected static CouchDbInstance _db;      
    static {
        try {
            _db = (CouchDbInstance) new InitialContext().lookup("couchdb/todos-cloudant");
        } catch (Exception e) {
            //Handle error nicely here ...
    public List<Todo> getAllTodos() {
        List<Todo> todos = new ArrayList<>();

        try {            
            CouchDbConnector dbc = _db.createConnector("todos_db", false);

            List<String> ids = dbc.getAllDocIds();

            for (String id : ids) {
                Todo todo = dbc.get(Todo.class, id);

        } catch (Exception e) {
            todos = new ArrayList<>();
            //Handle error nicely here ...

        return todos;
    static class Todo {
        String _id;
        String _rev;
        String title;
        String description;
        public Todo() {
        public Todo(String id, String title, String description) {
            this._id = id;
            this.title = title;
            this.description = description;
        public String get_id() {
            return _id;

        public void set_id(String _id) {
            this._id = _id;

        public String get_rev() {
            return _rev;
        public void set_rev(String _rev) {
            this._rev = _rev;

        public String getTitle() {
            return title;
        public void setTitle(String title) {
            this.title = title;
        public String getDescription() {
            return description;
        public void setDescription(String description) {
            this.description = description;

As you notice here, the Cloudant DB connector resource name follows "couchdb/[service_name]" naming which is ("couchdb/todos-cloudant" in our case). Note that all of the Cloudant DB connector resources have the prefix "couchdb/". _db connector variable is used to access the Cloudant Database which is created in Bluemix as shown below.
Bluemix config

As you see we have a Liberty for Java app called ("todos") and a Cloudant Database service which is bound to it. Do not forget to make sure your Cloudant service name matches the last part of the Cloudant DB connector name after “/”.

In order to allow the service to be accessed using Ajax without facing cross domain boundaries issues from the Worklight mobile client, I created a simple Filter servlet that wraps the JSON response in a JSONP format as shown here:

Finally, in order to deploy our WAR file, just do the following:
1. Make sure to install Cloud Foundry CLI from https://github.com/cloudfoundry/cli.

2. After this, type the following cf login command as follows:

cmd> cf login

3. You will be introduced to the API endpoint prompt then enter "https://api.ng.bluemix.net" and your email and password as shown follows:

API endpoint> https://api.ng.bluemix.net

Email> [email protected]
Password> yourPassword

4. After this, you can go ahead and install our WAR as follows:

cmd> cf push <unique_app_name> -m 512M -p <path_to_your_war_file> 

which is in our case:

cmd> cf push todos -m 512M -p todos.war

5. Finally, you can access the working application using simply:


In the Worklight project, a call to the TODO service is done using jQuery $.ajax as follows to get the list of TODOs as follows:

	url: "http://hs-todos.mybluemix.net/todo",
	jsonp: "callback",
	dataType: "jsonp", 
	success: function(todos) {
	    //Display TODOs here ...
	error: function(jqXHR, textStatus, errorThrown) {
	    console.log("An error occurs");            	

The final result of the WL project in iPhone is displayed as shown below:
iPhone screenshot

Finally, it worth mentioning that you can directly call Cloudant from your JavaScript client, Cloudant offers a powerful REST API over the database as indicated in the links below:

The mentioned example above introduces JAX-RS with Cloudant to show you how you can use them together with Bluemix and to give you the ability to decouple the REST client JavaScript code from the underlying Cloudant Database structure which will give you the ability to change Cloudant DB JSON structure in the future without affecting your REST API clients code.

I placed the working sample (JAX RS project and Worklight project) in GitHub for reference: