Configure CouchDB connectivity using the ektorp client library in Liberty

Applications that run on Liberty can use CouchDB. For access to a CouchDB instance, applications can configure a connector for the NoSQL database using the ektorp client library. Stabilized feature: Use of the ektorp client library with the couchdb-1.0 feature is stabilized. This feature is stabilized because the ektorp Java driver is no longer in service. We can continue to use the ektorp client library with the couchdb-1.0 feature. However, we can create a CDI producer for CouchDB by following the technique that is described in Access any version of MongoDB with Open Liberty using CDI. Use any CouchDB version that meets your requirements.

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

We must 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. 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 the 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. 

      <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.

        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 the server.xml file.

      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>

      We can use the couchdb-1.0 feature to configure a connection to an online Cloudant service. Specify the URL, userid, and password of the existing Cloudant account in the couchdb configuration element. For example: 

        <couchdb id='couchdb' jndiName='couchdb/connector' libraryRef='couchdb-lib' url='https://mylink.cloudant.com/' username='myusername' password='mypassword'/>

      See the documentation about limits to protection through password encryption to learn about how to secure passwords in configuration files.


What to do next

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