Configuring CouchDB connectivity by 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 by using the Cloudant Java client.

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

1. Install the Cloudant Java client library and its dependencies where your 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 your application by using resource lookups or resource injections.

   Specifically, you 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 you use JNDI to look up resources. However, this feature is not required when you 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 your 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 that are created in previous steps.
   You 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: Configuring a JNDI name enables an application to look up the ClientBuilder instance.
5. You can also configure a cloudantDatabase element that references the cloudant element you configured in step 4.
   This configuration allows your 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, your 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 your application to access the Database Cloudant resource.

   Inject or lookup the Database that was configured by 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 your application to use cloudant classes by configuring your application with a reference to the Cloudant library configured in step 3.

   <application ...>
       <classloader commonLibraryRef="cloudantLib"/>
   </application>