Configuring CouchDB connectivity by 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 by 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. You can continue to use the ektorp client library with the couchdb-1.0 feature. However, consider using instead the cloudant-1.0 feature or create a CDI producer 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.

Before you begin

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

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

About this task

To enable an application to use CouchDB, you must 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.

Procedure

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.

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>

Enable your application to access CouchDB, either by direct access from the application or by 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 you 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 you use JNDI to look up resources. This feature is not required if you 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"/>
```
    Configuring a JNDI name enables an application or the Liberty runtime to look up the CouchDB instance.
  3. Enable your 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 you are using JNDI lookup, add a resource environment reference to the web.xml file of your 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>
```
  You can use the couchdb-1.0 feature to configure a connection to an online Cloudant® service. Specify the URL, userid, and password of your 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 your application is configured to use CouchDB, you are ready to test the use of CouchDB from your application.