Configure CouchDB connectivity using the Cloudant Java client library in Liberty

Applications that run on Liberty can access NoSQL databases, such as CouchDB. For access to a CouchDB instance in Liberty, the preferred way is to configure the connector using the Cloudant Java client. cloudant-1.0 feature is stabilized. The strategic alternative to this guide is to create a CDI producer for cloudant-1.0 by following the technique that is described in Access any version of MongoDB with Open Liberty using CDI. Liberty supports configuration of the Cloudant Java client but does not supply the required libraries. We must use version 2.2.0 or later versions of the Cloudant Java client. We can download the required libraries from many sources, such as GitHub or the Eclipse Maven plug-in to obtain the Cloudant Java client and its dependencies as follows: 

    <dependency>
   <groupId>com.cloudant</groupId>
   <artifactId>cloudant-client</artifactId>
   <version>2.2.0</version>
</dependency>

To enable an application to use the Cloudant Java client API, configure the following items in the server.xml file:

An application can then directly access the client API without any additional configuration of the server.

See Cloudant Documentation. The ClientBuilder can create CloudantClient instances that can then be used to search, create database views, and do other tasks. A Database allows the application to do create, update, and modify operations.

In order for applications to inject a ClientBuilder or Database instance, we must enable the cloudant-1.0 feature and configure the Cloudant resources in the server configuration. The Liberty runtime manages the life cycle of CloudantClient instances that it uses for creating Database instances.

  1. Install the Cloudant Java client library and its dependencies where the application and the Liberty runtime can access.

    For example, place the Cloudant driver files and its dependencies in the ${server.config.dir}/lib directory.

  2. Update the server configuration to make a ClientBuilder or Database instance available to the application using resource lookups or resource injections.

    Specifically, we can use JNDI to update the server configuration by adding the cloudant-1.0 feature to the feature manager in the server.xml file: 

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

    Remember: The JNDI feature is required only when we use JNDI to look up resources. However, this feature is not required when we use a resource injection.

  3. Configure a shared library for the Cloudant driver files in the server.xml file of the Liberty server: 

      <library id="cloudantLib">
  <fileset dir="${shared.resource.dir}cloudant" includes="cloudant-client-2.2.0.jar commons-codec-1.6.jar commons-io-2.4.jar gson-2.2.4.jar"/>
</library>

    Extra libraries might be needed depending on the APIs that the application uses. For more information, see the Cloudant Java client documentation.

  4. Configure a cloudant element that has references to the shared library and default container authentication alias created in previous steps. We can specify either the URL of the local or remote database, or an account for a Cloudant Database as a Service (DBaaS). Remember not to specify both of them.

    • The following example specifies the URL of the database: 

        <cloudant id="myCloudant" libraryRef="cloudantLib" url="http://example.com:5984" username="your_cloudant_username" password="your_cloudant_password"/>

    • The following example specifies the account: 

        <cloudant id="myCloudant" libraryRef="cloudantLib" account="account_name" username="your_cloudant_username" password="your_cloudant_password" />

    Tip: Configure a JNDI name enables an application to look up the ClientBuilder instance.

  5. We can also configure a cloudantDatabase element that references the cloudant element you configured in step 4. This configuration allows the application to directly inject or lookup a com.cloudant.client.api.Database object. This setup is beneficial because the application does not need to know the name of the database, since the database name is stored in the server configuration. Additionally, our Liberty server manages the lifecycle of the cloudant connection managers that it creates. 

      <cloudantDatabase jndiName="cloudant/mydb" databaseName="mydb" create="true" cloudantRef="myCloudant"/>

  6. Enable the application to access the Database Cloudant resource.

    Inject or lookup the Database that was configured using the cloudantDatabase configuration element in step 5. Notice that when you inject a Database directly, the application does not need to know the name of the database or to manage the lifecycle of the connection manager. 

      @Resource(lookup="cloudant/mydb")
com.cloudant.client.api.Database db;

  7. Enable the application to use cloudant classes by configuring the application with a reference to the Cloudant library configured in step 3.


What to do next

After configuring the Cloudant connectivity for the application, test CouchDB from the application.