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.
Before you begin
Liberty supports configuration of the
Cloudant Java client but does not supply the required libraries. You must use version 2.2.0 or later
versions of the Cloudant Java client. You 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>
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.
Procedure
-
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.