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