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.
Stabilized feature: Use of the ektorp client
library with the
couchdb-1.0
feature is stabilized. This feature is stabilized
because the ektorp Java driver is no longer in service. You can continue to use the ektorp client
library with the
couchdb-1.0
feature. However, consider using instead the
cloudant-1.0 feature or create a CDI producer by following
the technique that is described in
Access any version of MongoDB with Open Liberty using CDI. Use any CouchDB
version that meets your requirements.
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 about
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.