ADR-006: Cloudant SDK for CouchDB Access

Decision Analysis and Resolution: CouchDB Client Library Migration

Created by: SW360 Architecture Team
Original Decision: 2024
Reformatted: April 2026
Status: Accepted
Estimated read time: 10 minutes

Table of Contents

1. Background
2. Goal
3. Key Principles
4. Key Inputs, Assumptions and Restrictions
5. Options Analysis
   • Option 1 - IBM Cloudant SDK
   • Option 2 - Apache CouchDB-Java
   • Option 3 - Ektorp Fork (Community)
   • Option 4 - Custom HTTP Client
6. Criteria for Making a Decision
7. Final Decision
8. Migration Path
9. Contributors

Background

SW360 uses Apache CouchDB as its primary database (see ADR-002). The original CouchDB client library was Ektorp, a Java library that provided:

• Object mapping for CouchDB documents
• View query support
• Attachment handling

However, Ektorp became deprecated and unmaintained:

• Last release: 2016 (8+ years without updates)
• Java compatibility: No support for Java 17+, 21+
• Security: Known vulnerabilities not addressed
• Features: Missing support for CouchDB 3.x features (Mango queries, Nouveau)

Why This Decision Matters: The CouchDB client is used throughout SW360’s data layer. An unmaintained library with security vulnerabilities poses significant risk.

Goal

The goal of this decision analysis is to:

1. Replace the deprecated Ektorp library
2. Enable Java 17+ and Java 21 compatibility
3. Ensure active maintenance and security patches
4. Support CouchDB 3.x features
5. Minimize migration disruption

Key Principles

Key Inputs, Assumptions and Restrictions

Options Analysis

Option 1 - IBM Cloudant SDK

Summary

Use IBM’s Cloudant Java SDK (cloudant-java-sdk), which despite its name, is fully compatible with Apache CouchDB. IBM unified their cloud SDKs and actively maintains this library.

Conceptual View

graph TB
    subgraph SDK["IBM Cloudant SDK"]
        direction TB
        W["Works with:<br/>├── IBM Cloudant (cloud)<br/>└── Apache CouchDB (self-hosted) ✓"]
        F["Features:<br/>Document CRUD | View queries<br/>Mango queries | Attachments<br/>Bulk operations | Async support"]
    end

Impact / Changes Required

• Refactor repository classes to use Cloudant SDK APIs
• Update connection configuration
• Migrate view query code to new API
• Update attachment handling code

SWOT Analysis

Option 2 - Apache CouchDB-Java

Summary

Use Apache’s official CouchDB Java client library, which provides basic HTTP client operations for CouchDB.

Conceptual View

graph TB
    subgraph CJ["Apache CouchDB-Java"]
        direction TB
        C1["Basic HTTP client for CouchDB"]
        C2["Limited object mapping"]
        C3["Manual JSON serialization"]
    end

Impact / Changes Required

• Build custom object mapping layer
• Implement view query abstraction
• Custom attachment handling
• More code to maintain

SWOT Analysis

Option 3 - Ektorp Fork (Community)

Summary

Use a community-maintained fork of Ektorp that attempts to keep the library updated with Java compatibility patches.

Conceptual View

graph TB
    subgraph EF["Ektorp Fork (Community)"]
        direction TB
        E1["Fork of original Ektorp"]
        E2["Community-maintained"]
        E3["Same API as original"]
    end

Impact / Changes Required

• Update Maven dependency coordinates
• Test compatibility
• Minimal code changes

SWOT Analysis

Option 4 - Custom HTTP Client

Summary

Build a custom CouchDB client using a modern HTTP client library like OkHttp or Java’s HttpClient, with Jackson for JSON serialization.

Conceptual View

graph TB
    subgraph CH["Custom HTTP Client"]
        direction TB
        H1["OkHttp / Java HttpClient"]
        H2["+ Jackson for JSON"]
        H3["+ Custom CouchDB abstractions"]
    end

Impact / Changes Required

• Design and implement complete client library
• Build all CouchDB operations from scratch
• Implement view query builders
• Handle attachments manually
• Ongoing maintenance

SWOT Analysis

Criteria for Making a Decision

T-Shirt Sizing Scale

Weighted Evaluation Matrix

Score Summary

Final Decision

Selected Option: IBM Cloudant SDK

Rationale

IBM Cloudant SDK was selected as the CouchDB client library based on:

1. Highest Weighted Score (706.25) - Clear winner on critical criteria

2. Active Maintenance (XL) - IBM corporate commitment:

   • Regular releases
   • Security vulnerability response
   • Feature additions

3. Java 21 Support (XL) - Full modern Java compatibility

4. CouchDB Compatibility (XL) - Despite the name, works perfectly with vanilla CouchDB:

   // Works with Apache CouchDB, not just IBM Cloudant
   Cloudant client = new Cloudant("sw360", authenticator);
   client.setServiceUrl("http://couchdb:5984");
   

5. Corporate Backing (XL) - IBM’s unified cloud SDK strategy ensures long-term viability

Migration Path

Phase 1: Add Cloudant SDK Alongside Ektorp

• Add dependency without removing Ektorp
• Create adapter layer for gradual migration

Phase 2: Migrate Core Repositories

• Convert document CRUD operations
• Migrate view queries
• Update attachment handling

Phase 3: Complete Migration

• Remove remaining Ektorp usages
• Remove Ektorp dependency
• Update documentation

Migration Examples

Ektorp (Old):

CouchDbConnector db = new StdCouchDbConnector("sw360db", couchDbInstance);
Component component = db.get(Component.class, id);

Cloudant SDK (New):

GetDocumentOptions options = new GetDocumentOptions.Builder()
    .db("sw360db")
    .docId(id)
    .build();
Document doc = client.getDocument(options).execute().getResult();
Component component = mapper.convertValue(doc, Component.class);

Maven Dependency

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>cloudant</artifactId>
    <version>0.8.x</version>
</dependency>

Contributors

Consequences Summary

Positive

• ✅ Active maintenance—regular updates and security patches
• ✅ Corporate backing—IBM’s commitment to the SDK
• ✅ Modern API—clean, builder-based design
• ✅ Async support—non-blocking operations for performance
• ✅ Documentation—comprehensive IBM documentation
• ✅ Java 21—full modern Java support

Negative

• ⚠️ Migration effort—refactoring from Ektorp APIs required
• ⚠️ IBM branding—name suggests Cloudant-only
• ⚠️ Dependency size—larger dependency tree
• ⚠️ Learning curve—new API patterns for developers

Technical Debt Addressed

• Eliminated unmaintained library (Ektorp)
• Resolved unpatched security vulnerabilities
• Enabled Java 21 compatibility
• Gained access to CouchDB 3.x features

Revision History