ADR-001: Apache Thrift for Internal Services

Decision Analysis and Resolution: SW360 Internal RPC Framework

Created by: SW360 Architecture Team
Original Decision: 2014
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 - REST/JSON
   • Option 2 - SOAP/XML
   • Option 3 - Apache Thrift
   • Option 4 - gRPC/Protocol Buffers
6. Criteria for Making a Decision
7. Final Decision
8. Contributors
9. Discussion & Brainstorming

Background

SW360 was designed as a multi-tier application for open source license compliance management with:

• A web portal (Liferay) as the frontend
• Backend services handling business logic
• A document database (CouchDB) for persistence

FOSSology Integration Challenge: A critical requirement was integration with FOSSology, a license scanning tool. At the time (2014), neither FOSSology nor SW360 had REST APIs. The need arose for a communication protocol that could bridge the Java-based SW360 and the predominantly C/PHP-based FOSSology.

Internal Communication Needs: The system also needed an efficient, reliable communication protocol between the web layer and backend services for internal operations.

Why This Decision Matters Now: This decision affects:

• All internal service-to-service communication
• External tool integrations
• Developer experience and onboarding
• System performance and maintainability

Goal

The goal of this decision analysis is to:

1. Select an internal RPC framework for SW360 that supports efficient service communication
2. Enable integration with external tools like FOSSology
3. Provide strong interface contracts to prevent service drift
4. Support potential polyglot implementations in the future
5. Document the rationale for future team members

Key Principles

Key Inputs, Assumptions and Restrictions

Options Analysis

Option 1 - REST/JSON

Summary

Use RESTful HTTP APIs with JSON serialization for all internal and external communication. This is the most common approach for web services and offers broad tooling support.

Conceptual View

graph LR
    A[Liferay Portal] <-->|HTTP/JSON<br/>REST APIs| B[Backend Services]
    B -->|HTTP/JSON| C[FOSSology]

Impact / Changes Required

• Implement REST controllers for all backend services
• Define JSON schemas for all data transfer objects
• Manual serialization/deserialization code
• FOSSology would need REST API development (not available in 2014)

SWOT Analysis

Option 2 - SOAP/XML

Summary

Use SOAP (Simple Object Access Protocol) with XML serialization. This was the enterprise standard for web services, offering strong typing through WSDL contracts.

Conceptual View

graph LR
    A[Liferay Portal] <-->|SOAP/XML<br/>WSDL| B[Backend Services]

Impact / Changes Required

• Define WSDL contracts for all services
• Generate Java stubs from WSDL
• Heavy XML processing infrastructure
• FOSSology integration would require SOAP support

SWOT Analysis

Option 3 - Apache Thrift

Summary

Use Apache Thrift, a binary RPC framework with Interface Definition Language (IDL). Thrift generates client/server code for multiple languages from a single interface definition.

Conceptual View

graph TB
    A[Liferay Portal] <-->|Thrift Binary<br/>TBinaryProtocol| B[Backend Services]
    A --> C[".thrift files<br/>(contracts)"]
    B --> C
    C -->|Code Generation| D["Java, C++, Python, PHP, ..."]
    D --> E["FOSSology (C/PHP)"]

Impact / Changes Required

• Define Thrift IDL files for all data structures and services
• Add Thrift compiler to build process
• Generate Java handlers for backend services
• FOSSology can use generated C/PHP code directly

SWOT Analysis

Option 4 - gRPC/Protocol Buffers

Summary

Use Google’s gRPC framework with Protocol Buffers for serialization. Similar to Thrift but newer, with HTTP/2 transport and strong Google backing.

Conceptual View

graph LR
    A[Liferay Portal] <-->|gRPC/HTTP2<br/>Protobuf| B[Backend Services]

Impact / Changes Required

• Define .proto files for all services
• Add protoc compiler to build process
• Generate Java/C++ stubs
• Requires HTTP/2 support throughout

SWOT Analysis

Criteria for Making a Decision

T-Shirt Sizing Scale

Weighted Evaluation Matrix

Score Summary

Final Decision

Selected Option: Apache Thrift

Rationale

Apache Thrift was selected as the internal RPC framework for SW360 based on:

1. Highest Weighted Score (670.0) - Significantly outperformed alternatives across all criteria

2. Critical FOSSology Integration - The highest-weighted criterion (10). Thrift’s native C/PHP support was the only option enabling FOSSology integration without requiring FOSSology to implement a new API

3. Superior Type Safety - Thrift IDL provides compile-time guarantees that prevent service interface drift:

   service ComponentService {
       Component getComponentById(1: string id, 2: User user) 
           throws (1: SW360Exception exp);
   }
   

4. Complex Data Structure Support - Native handling of nested structures, optional fields, and collections essential for SW360’s data model

5. Production Readiness - Battle-tested at Facebook scale, unlike gRPC which wasn’t released until 2016

Implementation Notes

Thrift Files Location:

libraries/datahandler/src/main/thrift/
├── sw360.thrift          # Common types, enums
├── components.thrift     # Component, Release
├── projects.thrift       # Project, ClearingRequest
├── licenses.thrift       # License, Obligation
├── users.thrift          # User, UserGroup
└── ...

Service Pattern:

// Handler implements Thrift interface
public class ComponentHandler implements ComponentService.Iface {
    @Override
    public Component getComponentById(String id, User user) 
            throws SW360Exception {
        // Implementation
    }
}

External API: REST/JSON layer to be added for external client access (cannot expose Thrift directly)

Review Triggers

This decision should be revisited if:

• FOSSology deprecates Thrift support
• gRPC becomes the industry standard with full PHP support
• Major Thrift vulnerabilities are discovered
• Team expertise in Thrift becomes unsustainable

Contributors

Discussion & Brainstorming

Architecture Team - 2014

The key differentiator is FOSSology integration. Without Thrift, we would need to wait for FOSSology to implement REST APIs, which is outside our control and timeline.

Development Team - 2014

Concern: Learning curve for Thrift IDL. Mitigation: Create internal documentation and code examples. The code generation actually reduces overall development effort.

Operations - 2014

Binary protocol harder to debug. Recommendation: Implement detailed logging at service boundaries and consider JSON protocol for development environments.

Consequences Summary

Positive

• ✅ Strong typing with compile-time checking of service interfaces
• ✅ Efficient binary protocol for large payloads
• ✅ Clear contracts through IDL files as documentation
• ✅ Backward compatibility through optional fields
• ✅ Consistent data model across all layers
• ✅ FOSSology integration enabled immediately

Negative

• ⚠️ Learning curve for developers new to Thrift
• ⚠️ Build complexity with Thrift compiler dependency
• ⚠️ Binary protocol harder to inspect than JSON
• ⚠️ REST API needed for external client integration

Technical Debt Created

• External REST API layer needed for non-Thrift clients
• Thrift compiler must be maintained in CI/CD pipeline

Revision History