Applications that run on Liberty can use CouchDB. For access to a CouchDB instance,
applications can configure a connector for the NoSQL database with the ektorp client
library.
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 of the Liberty server.
<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.
- 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.
- 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.
- 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.
- 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");
...
- 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 for
The limits to protection through password encryption to learn
about how to secure passwords in configuration files.
What to do next
Now that you have configured your application
to enable the use of CouchDB, you are ready to test the use of CouchDB
from your application.