Design Pattern 11: Adapter Pattern - Complete Guide with Real-World Stock Data Integration Examples

📁 Download the complete Design Pattern series code from our design_pattern repository.

🎯 What is the Adapter Pattern?

The Adapter Pattern is a structural design pattern that allows incompatible interfaces to work together. It acts as a bridge between two incompatible interfaces by wrapping an existing class with a new interface, enabling objects with incompatible interfaces to collaborate.

Key Benefits:

✅ Interface Compatibility - Make incompatible interfaces work together
✅ Legacy Integration - Integrate old systems with new code
✅ Third-party Integration - Work with external APIs and libraries
✅ Code Reusability - Reuse existing code without modification
✅ Flexibility - Support multiple interface variations

🚀 Real-World Problem: Stock Data Integration System

Let’s design a stock data integration system with the following requirements:

System Requirements:

Integrate existing XML-based stock system with new JSON-based analysis system
Support multiple data formats (XML, JSON, CSV) for future expansion
Maintain backward compatibility with existing XML system
Enable real-time data processing with new analysis tools
Provide unified interface for all data sources

Business Rules:

Existing system provides stock data in XML format
New analysis system expects JSON format
Data transformation should be transparent to clients
System should handle data validation and error recovery
Performance should not be significantly impacted by transformation

🏗️ Object-Oriented Analysis (OOA)

Let’s analyze the problem and identify the core components:

Identified Forces:

Interface Incompatibility
- Existing XML system and new JSON system have different interfaces
- Direct integration would require significant code changes
- No common interface between the two systems
Legacy System Constraints
- Cannot modify existing XML system due to business constraints
- Need to maintain backward compatibility
- Risk of breaking existing functionality
Integration Complexity
- Data format conversion required (XML to JSON)
- Different data structures and field mappings
- Error handling for format conversion

💡 Adapter Pattern Solution

After analyzing the forces, we can apply the Adapter Pattern to create a compatible interface:

Adapter Pattern Components:

Target Interface - The interface that the client expects
Adaptee - The existing class with incompatible interface
Adapter - The class that makes incompatible interfaces work together
Client - Uses the target interface

Benefits:

Seamless integration - Clients work with familiar interface
No legacy modification - Existing code remains unchanged
Flexible design - Support multiple adapters for different sources
Easy testing - Mock adapters for testing

🛠️ Implementation: Stock Data Integration System

Stock Data Integration Adapter Pattern Implementation

1. Target Interface (JSON Analyzer)

interface JsonAnalyzer {
    fun analyzeJsonData(json: String): AnalysisResult
    fun validateJsonData(json: String): ValidationResult
    fun getSupportedFormats(): List<String>
}

data class AnalysisResult(
    val success: Boolean,
    val data: Map<String, Any>,
    val timestamp: Long,
    val processingTime: Long,
    val errors: List<String> = emptyList()
)

data class ValidationResult(
    val isValid: Boolean,
    val errors: List<String> = emptyList(),
    val warnings: List<String> = emptyList()
)

2. Adaptee (XML Stock Data System)

class XmlStockData {
    private val stockData = mapOf(
        "stocks" to listOf(
            mapOf(
                "symbol" to "TSLA",
                "price" to "675.50",
                "volume" to "12500000",
                "change" to "+12.30",
                "changePercent" to "+1.86%"
            ),
            mapOf(
                "symbol" to "AMZN",
                "price" to "3201.65",
                "volume" to "8900000",
                "change" to "-15.20",
                "changePercent" to "-0.47%"
            ),
            mapOf(
                "symbol" to "GOOGL",
                "price" to "2850.25",
                "volume" to "15600000",
                "change" to "+8.75",
                "changePercent" to "+0.31%"
            )
        )
    )
    
    fun getXmlData(): String {
        return buildString {
            appendLine("<?xml version=\"1.0\" encoding=\"UTF-8\"?>")
            appendLine("<stocks>")
            stockData["stocks"]?.forEach { stock ->
                appendLine("  <stock>")
                appendLine("    <symbol>${stock["symbol"]}</symbol>")
                appendLine("    <price>${stock["price"]}</price>")
                appendLine("    <volume>${stock["volume"]}</volume>")
                appendLine("    <change>${stock["change"]}</change>")
                appendLine("    <changePercent>${stock["changePercent"]}</changePercent>")
                appendLine("  </stock>")
            }
            appendLine("</stocks>")
        }
    }
    
    fun getStockCount(): Int = stockData["stocks"]?.size ?: 0
    
    fun getLastUpdateTime(): Long = System.currentTimeMillis()
}

3. Adapter Implementation

class StockDataAdapter(
    private val xmlStockData: XmlStockData
) : JsonAnalyzer {
    
    override fun analyzeJsonData(json: String): AnalysisResult {
        val startTime = System.currentTimeMillis()
        
        return try {
            // Parse JSON data
            val jsonData = parseJson(json)
            
            // Perform analysis
            val analysisData = performAnalysis(jsonData)
            
            val processingTime = System.currentTimeMillis() - startTime
            
            AnalysisResult(
                success = true,
                data = analysisData,
                timestamp = System.currentTimeMillis(),
                processingTime = processingTime
            )
            
        } catch (e: Exception) {
            AnalysisResult(
                success = false,
                data = emptyMap(),
                timestamp = System.currentTimeMillis(),
                processingTime = System.currentTimeMillis() - startTime,
                errors = listOf("Analysis failed: ${e.message}")
            )
        }
    }
    
    override fun validateJsonData(json: String): ValidationResult {
        return try {
            parseJson(json)
            ValidationResult(isValid = true)
        } catch (e: Exception) {
            ValidationResult(
                isValid = false,
                errors = listOf("Invalid JSON: ${e.message}")
            )
        }
    }
    
    override fun getSupportedFormats(): List<String> = listOf("JSON", "XML")
    
    // Adapter-specific method to convert XML to JSON
    fun convertAndAnalyze(): AnalysisResult {
        val startTime = System.currentTimeMillis()
        
        return try {
            // Get XML data from existing system
            val xmlData = xmlStockData.getXmlData()
            
            // Convert XML to JSON
            val jsonData = convertXmlToJson(xmlData)
            
            // Analyze the converted data
            val analysisData = performAnalysis(jsonData)
            
            val processingTime = System.currentTimeMillis() - startTime
            
            AnalysisResult(
                success = true,
                data = analysisData,
                timestamp = System.currentTimeMillis(),
                processingTime = processingTime
            )
            
        } catch (e: Exception) {
            AnalysisResult(
                success = false,
                data = emptyMap(),
                timestamp = System.currentTimeMillis(),
                processingTime = System.currentTimeMillis() - startTime,
                errors = listOf("Conversion failed: ${e.message}")
            )
        }
    }
    
    private fun convertXmlToJson(xml: String): Map<String, Any> {
        // Simulate XML to JSON conversion
        return mapOf(
            "stocks" to listOf(
                mapOf(
                    "symbol" to "TSLA",
                    "price" to 675.50,
                    "volume" to 12500000,
                    "change" to 12.30,
                    "changePercent" to 1.86
                ),
                mapOf(
                    "symbol" to "AMZN",
                    "price" to 3201.65,
                    "volume" to 8900000,
                    "change" to -15.20,
                    "changePercent" to -0.47
                ),
                mapOf(
                    "symbol" to "GOOGL",
                    "price" to 2850.25,
                    "volume" to 15600000,
                    "change" to 8.75,
                    "changePercent" to 0.31
                )
            ),
            "metadata" to mapOf(
                "source" to "XML System",
                "conversionTime" to System.currentTimeMillis(),
                "totalStocks" to xmlStockData.getStockCount()
            )
        )
    }
    
    private fun parseJson(json: String): Map<String, Any> {
        // Simulate JSON parsing
        return mapOf("parsed" to true, "data" to json)
    }
    
    private fun performAnalysis(data: Map<String, Any>): Map<String, Any> {
        val stocks = data["stocks"] as? List<Map<String, Any>> ?: emptyList()
        
        val totalValue = stocks.sumOf { 
            (it["price"] as? Number)?.toDouble() ?: 0.0 
        }
        val averagePrice = if (stocks.isNotEmpty()) totalValue / stocks.size else 0.0
        val totalVolume = stocks.sumOf { 
            (it["volume"] as? Number)?.toLong() ?: 0L 
        }
        
        return mapOf(
            "summary" to mapOf(
                "totalStocks" to stocks.size,
                "totalValue" to totalValue,
                "averagePrice" to averagePrice,
                "totalVolume" to totalVolume
            ),
            "topPerformers" to stocks
                .filter { (it["changePercent"] as? Number)?.toDouble() ?: 0.0 > 0 }
                .sortedByDescending { (it["changePercent"] as? Number)?.toDouble() ?: 0.0 }
                .take(3),
            "worstPerformers" to stocks
                .filter { (it["changePercent"] as? Number)?.toDouble() ?: 0.0 < 0 }
                .sortedBy { (it["changePercent"] as? Number)?.toDouble() ?: 0.0 }
                .take(3),
            "analysis" to mapOf(
                "timestamp" to System.currentTimeMillis(),
                "dataSource" to "XML Adapter"
            )
        )
    }
}

4. Enhanced Adapter with Multiple Sources

class MultiSourceStockAdapter : JsonAnalyzer {
    private val xmlAdapter = StockDataAdapter(XmlStockData())
    private val csvAdapter = CsvStockDataAdapter()
    private val jsonAdapter = DirectJsonAdapter()
    
    override fun analyzeJsonData(json: String): AnalysisResult {
        return jsonAdapter.analyzeJsonData(json)
    }
    
    override fun validateJsonData(json: String): ValidationResult {
        return jsonAdapter.validateJsonData(json)
    }
    
    override fun getSupportedFormats(): List<String> = listOf("JSON", "XML", "CSV")
    
    fun analyzeFromXml(): AnalysisResult = xmlAdapter.convertAndAnalyze()
    
    fun analyzeFromCsv(csvData: String): AnalysisResult = csvAdapter.convertAndAnalyze(csvData)
    
    fun analyzeFromJson(jsonData: String): AnalysisResult = jsonAdapter.analyzeJsonData(jsonData)
}

class CsvStockDataAdapter {
    fun convertAndAnalyze(csvData: String): AnalysisResult {
        // Simulate CSV to JSON conversion and analysis
        return AnalysisResult(
            success = true,
            data = mapOf("source" to "CSV", "converted" to true),
            timestamp = System.currentTimeMillis(),
            processingTime = 50
        )
    }
}

class DirectJsonAdapter : JsonAnalyzer {
    override fun analyzeJsonData(json: String): AnalysisResult {
        return AnalysisResult(
            success = true,
            data = mapOf("source" to "JSON", "direct" to true),
            timestamp = System.currentTimeMillis(),
            processingTime = 10
        )
    }
    
    override fun validateJsonData(json: String): ValidationResult {
        return ValidationResult(isValid = true)
    }
    
    override fun getSupportedFormats(): List<String> = listOf("JSON")
}

5. Client Code

fun main() {
    println("=== Stock Data Integration Demo ===\n")
    
    // Create adapter
    val adapter = StockDataAdapter(XmlStockData())
    val multiAdapter = MultiSourceStockAdapter()
    
    // Test XML to JSON conversion and analysis
    println("📊 Analyzing stock data from XML system...")
    val xmlResult = adapter.convertAndAnalyze()
    
    if (xmlResult.success) {
        println("✅ XML analysis successful!")
        println("📈 Processing time: ${xmlResult.processingTime}ms")
        println("📊 Analysis results:")
        
        val summary = xmlResult.data["summary"] as? Map<String, Any>
        println("   • Total Stocks: ${summary?.get("totalStocks")}")
        println("   • Total Value: $${summary?.get("totalValue")}")
        println("   • Average Price: $${summary?.get("averagePrice")}")
        println("   • Total Volume: ${summary?.get("totalVolume")}")
        
        val topPerformers = xmlResult.data["topPerformers"] as? List<Map<String, Any>>
        println("   • Top Performers: ${topPerformers?.map { "${it["symbol"]} (+${it["changePercent"]}%)" }}")
        
    } else {
        println("❌ XML analysis failed: ${xmlResult.errors}")
    }
    
    println()
    
    // Test direct JSON analysis
    println("📊 Analyzing direct JSON data...")
    val jsonData = """
    {
        "stocks": [
            {"symbol": "AAPL", "price": 150.25, "change": 2.50},
            {"symbol": "MSFT", "price": 280.75, "change": -1.25}
        ]
    }
    """.trimIndent()
    
    val jsonResult = adapter.analyzeJsonData(jsonData)
    if (jsonResult.success) {
        println("✅ JSON analysis successful!")
        println("📈 Processing time: ${jsonResult.processingTime}ms")
    } else {
        println("❌ JSON analysis failed: ${jsonResult.errors}")
    }
    
    println()
    
    // Test multi-source adapter
    println("🔄 Testing multi-source adapter...")
    println("📋 Supported formats: ${multiAdapter.getSupportedFormats()}")
    
    val xmlMultiResult = multiAdapter.analyzeFromXml()
    val csvMultiResult = multiAdapter.analyzeFromCsv("AAPL,150.25,2.50")
    val jsonMultiResult = multiAdapter.analyzeFromJson(jsonData)
    
    println("✅ Multi-source analysis complete!")
    println("   • XML: ${if (xmlMultiResult.success) "✅" else "❌"}")
    println("   • CSV: ${if (csvMultiResult.success) "✅" else "❌"}")
    println("   • JSON: ${if (jsonMultiResult.success) "✅" else "❌"}")
    
    println()
    
    // Performance comparison
    println("📊 Performance Comparison:")
    println("   • XML Analysis: ${xmlResult.processingTime}ms")
    println("   • JSON Analysis: ${jsonResult.processingTime}ms")
    println("   • Direct JSON: ${jsonMultiResult.processingTime}ms")
}

Expected Output:

=== Stock Data Integration Demo ===

📊 Analyzing stock data from XML system...
✅ XML analysis successful!
📈 Processing time: 45ms
📊 Analysis results:
   • Total Stocks: 3
   • Total Value: 6727.4
   • Average Price: 2242.47
   • Total Volume: 37000000
   • Top Performers: [TSLA (+1.86%), GOOGL (+0.31%)]

📊 Analyzing direct JSON data...
✅ JSON analysis successful!
📈 Processing time: 12ms

🔄 Testing multi-source adapter...
📋 Supported formats: [JSON, XML, CSV]
✅ Multi-source analysis complete!
   • XML: ✅
   • CSV: ✅
   • JSON: ✅

📊 Performance Comparison:
   • XML Analysis: 45ms
   • JSON Analysis: 12ms
   • Direct JSON: 10ms

📊 Adapter Pattern vs Alternative Approaches

Approach	Pros	Cons
Adapter Pattern	✅ Interface compatibility ✅ No legacy modification ✅ Reusable design	❌ Additional layer ❌ Potential performance overhead ❌ Increased complexity
Direct Modification	✅ No overhead ✅ Direct integration ✅ Simple implementation	❌ Breaks existing code ❌ High risk ❌ Maintenance burden
Wrapper Classes	✅ Encapsulation ✅ Clean interface	❌ Different purpose (encapsulation vs compatibility)
Interface Segregation	✅ Clean interfaces ✅ Better design	❌ Requires system redesign ❌ Not always feasible

🎯 When to Use the Adapter Pattern

✅ Perfect For:

Legacy system integration (old systems with new code)
Third-party API integration (external services with different interfaces)
Interface compatibility (making incompatible interfaces work together)
Library integration (using libraries with different interfaces)
Data format conversion (XML to JSON, CSV to XML, etc.)

❌ Avoid When:

Simple interface changes (direct modification is simpler)
Performance-critical applications (adapter overhead)
Frequent interface changes (adapter becomes maintenance burden)
New system design (design compatible interfaces from start)

🔧 Advanced Adapter Pattern Implementations

1. Adapter with Caching

class CachedStockDataAdapter(
    private val xmlStockData: XmlStockData,
    private val cache: MutableMap<String, AnalysisResult> = mutableMapOf(),
    private val cacheTimeout: Long = 60000 // 1 minute
) : JsonAnalyzer {
    
    override fun analyzeJsonData(json: String): AnalysisResult {
        val cacheKey = "json_${json.hashCode()}"
        val cached = cache[cacheKey]
        
        if (cached != null && !isExpired(cached.timestamp)) {
            println("📋 Returning cached result for JSON analysis")
            return cached
        }
        
        val result = performJsonAnalysis(json)
        cache[cacheKey] = result
        return result
    }
    
    fun convertAndAnalyze(): AnalysisResult {
        val cacheKey = "xml_conversion"
        val cached = cache[cacheKey]
        
        if (cached != null && !isExpired(cached.timestamp)) {
            println("📋 Returning cached result for XML conversion")
            return cached
        }
        
        val result = performXmlConversion()
        cache[cacheKey] = result
        return result
    }
    
    private fun isExpired(timestamp: Long): Boolean {
        return System.currentTimeMillis() - timestamp > cacheTimeout
    }
    
    private fun performJsonAnalysis(json: String): AnalysisResult {
        // Implementation for JSON analysis
        return AnalysisResult(
            success = true,
            data = mapOf("source" to "JSON", "cached" to false),
            timestamp = System.currentTimeMillis(),
            processingTime = 15
        )
    }
    
    private fun performXmlConversion(): AnalysisResult {
        // Implementation for XML conversion
        return AnalysisResult(
            success = true,
            data = mapOf("source" to "XML", "cached" to false),
            timestamp = System.currentTimeMillis(),
            processingTime = 50
        )
    }
    
    fun clearCache() {
        cache.clear()
        println("🗑️ Cache cleared")
    }
    
    fun getCacheSize(): Int = cache.size
}

2. Adapter with Error Recovery

class ResilientStockDataAdapter(
    private val xmlStockData: XmlStockData,
    private val maxRetries: Int = 3
) : JsonAnalyzer {
    
    override fun analyzeJsonData(json: String): AnalysisResult {
        return retryOperation("JSON Analysis") {
            performJsonAnalysis(json)
        }
    }
    
    fun convertAndAnalyze(): AnalysisResult {
        return retryOperation("XML Conversion") {
            performXmlConversion()
        }
    }
    
    private fun <T> retryOperation(operationName: String, operation: () -> T): T {
        var lastException: Exception? = null
        
        for (attempt in 1..maxRetries) {
            try {
                return operation()
            } catch (e: Exception) {
                lastException = e
                println("⚠️ $operationName attempt $attempt failed: ${e.message}")
                
                if (attempt < maxRetries) {
                    val delay = attempt * 1000L // Exponential backoff
                    println("⏳ Retrying in ${delay}ms...")
                    Thread.sleep(delay)
                }
            }
        }
        
        throw RuntimeException("$operationName failed after $maxRetries attempts", lastException)
    }
    
    private fun performJsonAnalysis(json: String): AnalysisResult {
        // Simulate potential failure
        if (Math.random() < 0.3) {
            throw RuntimeException("Simulated JSON analysis failure")
        }
        
        return AnalysisResult(
            success = true,
            data = mapOf("source" to "JSON", "retry" to false),
            timestamp = System.currentTimeMillis(),
            processingTime = 20
        )
    }
    
    private fun performXmlConversion(): AnalysisResult {
        // Simulate potential failure
        if (Math.random() < 0.2) {
            throw RuntimeException("Simulated XML conversion failure")
        }
        
        return AnalysisResult(
            success = true,
            data = mapOf("source" to "XML", "retry" to false),
            timestamp = System.currentTimeMillis(),
            processingTime = 60
        )
    }
}

3. Adapter with Monitoring

class MonitoredStockDataAdapter(
    private val adapter: JsonAnalyzer,
    private val monitor: AdapterMonitor
) : JsonAnalyzer {
    
    override fun analyzeJsonData(json: String): AnalysisResult {
        val startTime = System.currentTimeMillis()
        
        return try {
            monitor.recordOperation("json_analysis", startTime)
            val result = adapter.analyzeJsonData(json)
            monitor.recordSuccess("json_analysis", System.currentTimeMillis() - startTime)
            result
        } catch (e: Exception) {
            monitor.recordError("json_analysis", e.message ?: "Unknown error")
            throw e
        }
    }
    
    override fun validateJsonData(json: String): ValidationResult {
        return adapter.validateJsonData(json)
    }
    
    override fun getSupportedFormats(): List<String> = adapter.getSupportedFormats()
}

class AdapterMonitor {
    private val operations = mutableListOf<OperationRecord>()
    private val errors = mutableListOf<ErrorRecord>()
    
    fun recordOperation(type: String, startTime: Long) {
        operations.add(OperationRecord(type, startTime, null, null))
        println("📊 Started operation: $type")
    }
    
    fun recordSuccess(type: String, duration: Long) {
        operations.lastOrNull { it.type == type && it.duration == null }?.let {
            it.duration = duration
            it.success = true
        }
        println("✅ Operation completed: $type (${duration}ms)")
    }
    
    fun recordError(type: String, error: String) {
        errors.add(ErrorRecord(type, error, System.currentTimeMillis()))
        operations.lastOrNull { it.type == type && it.duration == null }?.let {
            it.duration = System.currentTimeMillis() - it.startTime
            it.success = false
        }
        println("❌ Operation failed: $type - $error")
    }
    
    fun getReport(): String {
        val successfulOps = operations.filter { it.success == true }
        val failedOps = operations.filter { it.success == false }
        val avgDuration = successfulOps.mapNotNull { it.duration }.average()
        
        return buildString {
            appendLine("=== Adapter Monitor Report ===")
            appendLine("Total Operations: ${operations.size}")
            appendLine("Successful: ${successfulOps.size}")
            appendLine("Failed: ${failedOps.size}")
            appendLine("Average Duration: ${String.format("%.2f", avgDuration)}ms")
            appendLine("Recent Errors:")
            errors.takeLast(3).forEach { error ->
                appendLine("  - ${error.type}: ${error.message}")
            }
            appendLine("=============================")
        }
    }
}

data class OperationRecord(
    val type: String,
    val startTime: Long,
    var duration: Long?,
    var success: Boolean?
)

data class ErrorRecord(
    val type: String,
    val message: String,
    val timestamp: Long
)

🚀 Real-World Applications

1. API Integration

Payment gateways - Adapt different payment provider interfaces
Social media APIs - Unify different platform interfaces
Cloud services - Abstract cloud provider differences
Database drivers - Standardize database access interfaces

2. Legacy System Integration

Mainframe integration - Connect old systems with modern applications
File format conversion - Convert between different data formats
Protocol adaptation - Bridge different communication protocols
Hardware interfaces - Adapt different device interfaces

3. Library and Framework Integration

Third-party libraries - Adapt incompatible library interfaces
Version compatibility - Bridge different API versions
Language interoperability - Connect different programming languages
Platform abstraction - Abstract platform-specific differences

4. Data Processing

ETL pipelines - Transform data between different formats
Message queues - Adapt different messaging protocols
Stream processing - Convert between different stream formats
Configuration management - Adapt different config formats

📈 Performance Considerations

Adapter Overhead

Method delegation - Additional method calls through adapter
Data transformation - Cost of converting between formats
Memory usage - Adapter object memory footprint
Caching strategies - Cache expensive transformations

Optimization Techniques

Lazy loading - Defer expensive operations until needed
Connection pooling - Reuse expensive connections
Batch processing - Process multiple items together
Async operations - Handle transformations asynchronously

Bridge Pattern - For abstraction-implementation separation
Facade Pattern - For simplifying complex interfaces
Decorator Pattern - For adding functionality
Proxy Pattern - For access control

📚 Best Practices

1. Adapter Design

Single responsibility - Each adapter should handle one specific conversion
Error handling - Proper error handling for conversion failures
Performance optimization - Minimize conversion overhead
Documentation - Clear documentation of conversion logic

2. Interface Design

Target interface - Design clean, stable target interfaces
Extensibility - Support future interface changes
Compatibility - Ensure backward compatibility when possible
Validation - Validate data during conversion

3. Implementation Guidelines

Thread safety - Handle concurrent access properly
Resource management - Properly manage resources and connections
Testing strategies - Test with various data formats and edge cases
Monitoring - Monitor adapter performance and errors

🎯 Conclusion

The Adapter Pattern provides a powerful way to integrate incompatible interfaces and systems. By creating a bridge between different interfaces, it enables:

Seamless integration of legacy and new systems
Flexible architecture that supports multiple data sources
Maintainable code without modifying existing systems
Reusable components for different integration scenarios

This pattern is essential for building flexible, maintainable systems that need to work with various external interfaces and legacy systems. Whether you’re integrating APIs, connecting legacy systems, or handling multiple data formats, the Adapter Pattern provides the foundation for robust system integration.

Next Steps:

Explore the Bridge Pattern for abstraction-implementation separation
Learn about the Facade Pattern for interface simplification
Discover the Decorator Pattern for adding functionality

Ready to implement the Adapter Pattern in your projects? Download the complete code examples from our design_pattern repository and start building more flexible, integrable systems today!