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.
About this task
To enable an application to use the Cloudant Java client API, you must configure the following
items in the
server.xml file:
- A shared library for the driver and the libraries that it depends upon
- A reference to the shared library
An application can then directly access the client API without any additional configuration of
the server. For more information, 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, you 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.
- 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.
- 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.
- 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.
- 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.
- 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"/>
- 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;
- 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>
What to do next
After you configure the Cloudant connectivity for your application, test CouchDB from your
application.