Create Liberty applications that use CouchDB

Applications that use CouchDB can run on the Liberty profile. For access to a CouchDB instance, applications use the ektorp Java API and a connection instance configured for the NoSQL database.

The Liberty profile provides configuration support for CouchDB. CouchDB is a scalable, high-performance, open source NoSQL database.

Use Version 1.4.1 or later of the ektorp Java driver. Use the Maven plug-in to obtain the ektorp driver and its dependencies.

<dependency>
    <groupId>org.ektorp</groupId>
    <artifactId>org.ektorp</artifactId>
    <version>1.4.1</version>
</dependency>

To enable an application to use CouchDB, configure a shared library for the CouchDB Java driver and a library reference to the shared library in the server.xml file of the Liberty profile. An application can access CouchDB either directly from the application, or through the couchdb-1.0 feature and CouchDB instance configurations in the server.xml file.

1. Install the CouchDB Java driver in a location that your application and the Liberty runtime can access.

   For example, place the ektorp driver file and its dependencies in the Liberty_profile_root/usr/servers/server_name/lib directory.

2. Configure a shared library for the ektorp driver files in the server.xml file of the Liberty profile server.

   <library id="couchdb-lib">
       <fileset          
       dir='${server.config.dir}/lib'          
       includes='org.ektorp-1.4.1.jar        
       commons-codec-1.6.jar        
       commons-io-2.0.1.jar        
       commons-logging-1.1.1.jar        
       httpclient-4.2.5.jar        
       httpclient-cache-4.2.5.jar        
       httpcore-4.2.4.jar        
       jackson-annotations-2.2.2.jar        
       jackson-core-2.2.2.jar        
       jackson-databind-2.2.2.jar        
       slf4j-api-1.6.4.jar        
       slf4j-simple-1.6.4.jar'/>   
   </library>

3. Enable the application to access CouchDB, either by direct access from the application or using the couchdb-1.0 feature.

   • Enable direct access to CouchDB from the application.

     1. Configure a library reference for the shared library in an application element in the server.xml file.

        <application ...>
           <classloader commonLibraryRef="couchdb-lib"/>
        </application>

        The application can now access the CouchDB APIs directly. If we want the application to use the runtime injection engine, continue with the next steps.

   • Configure the couchdb-1.0 feature, and the couchdb elements in server.xml.

     1. Add the couchdb-1.0 feature to the server.xml file.

        <featureManager>
           <feature>couchdb-1.0</feature>
           <feature>jndi-1.0</feature>
        </featureManager>

        The JNDI feature is only required when we use JNDI to look up resources. This feature is not required if we use resource injection.

     2. Configure a couchdb element that has a reference to the shared library created in a previous step.

        <couchdb id="couchdb" jndiName="couchdb/connector"
              libraryRef="couchdb-lib" url="http://example.com:5984" username="username"
              password="password"/>

        Configure a JNDI name enables an application or the Liberty runtime to look up the CouchDB instance.

     3. Enable the application to access CouchDB.

        The following example shows both JNDI lookup and resource injection:

        public class TestServlet extends HttpServlet {
              @Resource(name = "couchdb/connector")
              protected CouchDbInstance db;
              ...
           protected void doGet(HttpServletRequest request,      HttpServletResponse response) throws ServletException, IOException {
           // Alternatively use InitialContext lookup
              CouchDbInstance lookup = (CouchDbInstance) new 
        InitialContext().lookup("java:comp/env/couchdb/connector");
        ...

     4. If we are using JNDI lookup, add a resource environment reference to the web.xml file of the application:

        <resource-env-ref>
           <resource-env-ref-name>couchdb/connector</resource-env-ref-name>
           <resource-env-ref-type>org.ektorp.CouchDbInstance</resource-env-ref-type>
        </resource-env-ref>

What to do next

Now that we have configured the application to enable the use of CouchDB, we are ready to test the use of CouchDB from the application.

Parent topic: Administer data access applications