1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// Interface definition - a pure contract
public interface PaymentProcessor {
    
    // ═══════════════════════════════════════════════════
    // METHOD SIGNATURES: What must exist (no implementation)
    // ═══════════════════════════════════════════════════
    
    /**
     * Process a payment transaction.
     * @param amount The amount to charge
     * @param currency The currency code (e.g., "USD", "EUR")
     * @param paymentDetails Provider-specific payment information
     * @return Result of the payment processing
     * @throws PaymentException if processing fails
     */
    PaymentResult processPayment(
        BigDecimal amount,
        String currency,
        PaymentDetails paymentDetails
    ) throws PaymentException;
    
    /**
     * Refund a previously processed payment.
     * @param transactionId The original transaction to refund
     * @param amount Amount to refund (may be partial)
     * @return Result of the refund operation
     */
    RefundResult refundPayment(String transactionId, BigDecimal amount);
    
    /**
     * Check if the processor supports a given currency.
     * @param currency Currency code to check
     * @return true if the currency is supported
     */
    boolean supportsCurrency(String currency);
    
    /**
     * Get the processor's unique identifier.
     * @return Processor ID (e.g., "stripe", "paypal", "square")
     */
    String getProcessorId();
    
    // ═══════════════════════════════════════════════════
    // CONSTANTS: Compile-time values (allowed in interfaces)
    // ═══════════════════════════════════════════════════
    
    // These are implicitly public static final
    int MAX_RETRY_ATTEMPTS = 3;
    Duration TIMEOUT = Duration.ofSeconds(30);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

// ═══════════════════════════════════════════════════
// WITHOUT INTERFACES: Tight coupling
// ═══════════════════════════════════════════════════
 
// This class is LOCKED to Stripe
public class CheckoutService_Coupled {
    
    // Direct dependency on concrete implementation
    private final StripePaymentProcessor stripeProcessor;
    
    public CheckoutService_Coupled() {
        // Creating the dependency internally - very rigid
        this.stripeProcessor = new StripePaymentProcessor(
            System.getenv("STRIPE_API_KEY")
        );
    }
    
    public OrderResult checkout(Order order) {
        // Directly using Stripe-specific methods
        StripePaymentResult result = stripeProcessor.chargeStripe(
            order.getTotal(),
            order.getStripeToken() // Stripe-specific concept!
        );
        
        // To switch to PayPal, we must modify this code
        // To test without real payments, we need the real Stripe
        return convertToOrderResult(result);
    }
}
 
 
// ═══════════════════════════════════════════════════
// WITH INTERFACES: Loose coupling
// ═══════════════════════════════════════════════════
 
// This class works with ANY payment processor
public class CheckoutService_Decoupled {
    
    // Depends on interface, not implementation
    private final PaymentProcessor paymentProcessor;
    
    // Dependency injected - we don't choose the implementation
    public CheckoutService_Decoupled(PaymentProcessor paymentProcessor) {
        this.paymentProcessor = paymentProcessor;
    }
    
    public OrderResult checkout(Order order) {
        // Using interface methods - implementation-agnostic
        PaymentResult result = paymentProcessor.processPayment(
            order.getTotal(),
            order.getCurrency(),
            order.getPaymentDetails() // Generic concept
        );
        
        // Works with Stripe, PayPal, Square, or MockPayments
        // Zero code changes required to switch
        return convertToOrderResult(result);
    }
}
 
 
// ═══════════════════════════════════════════════════
// USAGE: Plug in any implementation
// ═══════════════════════════════════════════════════
 
// Production: Use Stripe
PaymentProcessor stripeProcessor = new StripePaymentProcessor(apiKey);
CheckoutService checkout = new CheckoutService_Decoupled(stripeProcessor);
 
// Production: Switch to PayPal (no code changes in CheckoutService!)
PaymentProcessor paypalProcessor = new PayPalPaymentProcessor(credentials);
CheckoutService checkout = new CheckoutService_Decoupled(paypalProcessor);
 
// Testing: Use mock (no real money, no API calls)
PaymentProcessor mockProcessor = new MockPaymentProcessor();
CheckoutService checkout = new CheckoutService_Decoupled(mockProcessor);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

// ═══════════════════════════════════════════════════
// FOCUSED INTERFACES: Each defines one capability
// ═══════════════════════════════════════════════════
 
// Capability: Can generate a unique identifier
public interface Identifiable {
    String getId();
}
 
// Capability: Can be serialized to JSON
public interface JsonSerializable {
    String toJson();
    void fromJson(String json);
}
 
// Capability: Can track when last modified
public interface Auditable {
    Instant getCreatedAt();
    Instant getUpdatedAt();
    String getLastModifiedBy();
}
 
// Capability: Can be validated
public interface Validatable {
    ValidationResult validate();
    boolean isValid();
}
 
// Capability: Can be versioned for optimistic locking
public interface Versionable {
    int getVersion();
    void incrementVersion();
}
 
 
// ═══════════════════════════════════════════════════
// COMPOSITION: Combine capabilities as needed
// ═══════════════════════════════════════════════════
 
// A domain entity with all capabilities
public class Order implements 
    Identifiable, 
    JsonSerializable, 
    Auditable, 
    Validatable, 
    Versionable {
    
    private String id;
    private List<OrderItem> items;
    private OrderStatus status;
    private Instant createdAt;
    private Instant updatedAt;
    private String lastModifiedBy;
    private int version;
    
    // Identifiable implementation
    @Override
    public String getId() {
        return this.id;
    }
    
    // JsonSerializable implementation
    @Override
    public String toJson() {
        return new ObjectMapper().writeValueAsString(this);
    }
    
    @Override
    public void fromJson(String json) {
        Order parsed = new ObjectMapper().readValue(json, Order.class);
        this.items = parsed.items;
        this.status = parsed.status;
        // ... copy other fields
    }
    
    // Auditable implementation
    @Override
    public Instant getCreatedAt() { return createdAt; }
    
    @Override
    public Instant getUpdatedAt() { return updatedAt; }
    
    @Override
    public String getLastModifiedBy() { return lastModifiedBy; }
    
    // Validatable implementation
    @Override
    public ValidationResult validate() {
        List<String> errors = new ArrayList<>();
        
        if (items == null || items.isEmpty()) {
            errors.add("Order must have at least one item");
        }
        
        if (items != null) {
            for (OrderItem item : items) {
                if (item.getQuantity() <= 0) {
                    errors.add("Item quantity must be positive");
                }
            }
        }
        
        return new ValidationResult(errors.isEmpty(), errors);
    }
    
    @Override
    public boolean isValid() {
        return validate().isValid();
    }
    
    // Versionable implementation
    @Override
    public int getVersion() { return version; }
    
    @Override
    public void incrementVersion() { this.version++; }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

// Each service depends ONLY on the capability it needs
 
// Persistence layer cares about identity and versions
public class Repository<T extends Identifiable & Versionable> {
    
    public void save(T entity) {
        String id = entity.getId();         // Identifiable
        int version = entity.getVersion();  // Versionable
        
        // Check for concurrent modification
        if (existingVersion > version) {
            throw new OptimisticLockException();
        }
        
        entity.incrementVersion();          // Versionable
        persistToDatabase(entity);
    }
}
 
 
// Audit system cares only about audit info
public class AuditLogger {
    
    public void logChange(Auditable auditable, String action) {
        log.info(
            "Action: {} at {} by {}",
            action,
            auditable.getUpdatedAt(),     // Auditable
            auditable.getLastModifiedBy() // Auditable
        );
    }
}
 
 
// Serialization service cares only about JSON capability
public class JsonExporter {
    
    public void export(Collection<? extends JsonSerializable> items) {
        for (JsonSerializable item : items) {
            String json = item.toJson();  // JsonSerializable
            writeToFile(json);
        }
    }
}
 
 
// Validation service requires Validatable
public class ValidationService {
    
    public void ensureValid(Validatable validatable) {
        ValidationResult result = validatable.validate();
        if (!result.isValid()) {
            throw new ValidationException(result.getErrors());
        }
    }
}
 
 
// USAGE: Order works with ALL of these services
Order order = new Order();
 
repository.save(order);           // Uses Identifiable + Versionable
auditLogger.logChange(order);     // Uses Auditable
jsonExporter.export(List.of(order)); // Uses JsonSerializable
validationService.ensureValid(order); // Uses Validatable

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188

// ═══════════════════════════════════════════════════
// THE INTERFACE: Contract for email sending
// ═══════════════════════════════════════════════════
 
public interface EmailService {
    void sendEmail(String to, String subject, String body);
    void sendBulkEmails(List<EmailMessage> messages);
    boolean isValidEmail(String email);
    int getDailyQuotaRemaining();
}
 
 
// ═══════════════════════════════════════════════════
// PRODUCTION IMPLEMENTATION: Real email sending
// ═══════════════════════════════════════════════════
 
public class SendGridEmailService implements EmailService {
    
    private final SendGridClient client;
    
    @Override
    public void sendEmail(String to, String subject, String body) {
        // Real API call to SendGrid
        client.send(new Email(to, subject, body));
    }
    
    @Override
    public int getDailyQuotaRemaining() {
        return client.getAccount().getQuota().getRemaining();
    }
    
    // ... other implementations
}
 
 
// ═══════════════════════════════════════════════════
// THE SERVICE UNDER TEST: Uses EmailService interface
// ═══════════════════════════════════════════════════
 
public class UserRegistrationService {
    
    private final UserRepository userRepository;
    private final EmailService emailService;  // Interface dependency
    
    public UserRegistrationService(
        UserRepository userRepository,
        EmailService emailService
    ) {
        this.userRepository = userRepository;
        this.emailService = emailService;
    }
    
    public RegistrationResult register(RegistrationRequest request) {
        // Validate email
        if (!emailService.isValidEmail(request.getEmail())) {
            return RegistrationResult.failure("Invalid email");
        }
        
        // Check quota
        if (emailService.getDailyQuotaRemaining() < 1) {
            return RegistrationResult.failure("Email quota exceeded");
        }
        
        // Create user
        User user = userRepository.save(new User(request));
        
        // Send welcome email
        emailService.sendEmail(
            user.getEmail(),
            "Welcome!",
            "Thank you for registering..."
        );
        
        return RegistrationResult.success(user.getId());
    }
}
 
 
// ═══════════════════════════════════════════════════
// TEST DOUBLE: Mock implementation for testing
// ═══════════════════════════════════════════════════
 
public class MockEmailService implements EmailService {
    
    // Track what was sent for assertions
    private final List<SentEmail> sentEmails = new ArrayList<>();
    private boolean shouldValidateEmails = true;
    private int quotaRemaining = 100;
    
    @Override
    public void sendEmail(String to, String subject, String body) {
        // Don't really send - just record
        sentEmails.add(new SentEmail(to, subject, body));
    }
    
    @Override
    public boolean isValidEmail(String email) {
        return shouldValidateEmails && email.contains("@");
    }
    
    @Override
    public int getDailyQuotaRemaining() {
        return quotaRemaining;
    }
    
    // Test helpers
    public void setQuotaRemaining(int quota) {
        this.quotaRemaining = quota;
    }
    
    public void setShouldValidateEmails(boolean validate) {
        this.shouldValidateEmails = validate;
    }
    
    public List<SentEmail> getSentEmails() {
        return sentEmails;
    }
    
    public boolean wasSentTo(String email) {
        return sentEmails.stream()
            .anyMatch(e -> e.getTo().equals(email));
    }
}
 
 
// ═══════════════════════════════════════════════════
// THE TESTS: Fast, isolated, deterministic
// ═══════════════════════════════════════════════════
 
@ExtendWith(MockitoExtension.class)
public class UserRegistrationServiceTest {
    
    private MockEmailService mockEmailService;
    private UserRegistrationService service;
    
    @BeforeEach
    void setup() {
        mockEmailService = new MockEmailService();
        service = new UserRegistrationService(
            new InMemoryUserRepository(),
            mockEmailService  // Inject mock!
        );
    }
    
    @Test
    void registersUserAndSendsWelcomeEmail() {
        // Arrange
        var request = new RegistrationRequest("user@example.com", "pass");
        
        // Act
        var result = service.register(request);
        
        // Assert
        assertTrue(result.isSuccess());
        assertTrue(mockEmailService.wasSentTo("user@example.com"));
        
        SentEmail welcome = mockEmailService.getSentEmails().get(0);
        assertEquals("Welcome!", welcome.getSubject());
    }
    
    @Test
    void failsWhenEmailQuotaExceeded() {
        // Arrange
        mockEmailService.setQuotaRemaining(0);  // Simulate exhausted quota
        var request = new RegistrationRequest("user@example.com", "pass");
        
        // Act
        var result = service.register(request);
        
        // Assert
        assertFalse(result.isSuccess());
        assertEquals("Email quota exceeded", result.getError());
        assertTrue(mockEmailService.getSentEmails().isEmpty());
    }
    
    @Test
    void failsWithInvalidEmail() {
        // Arrange
        var request = new RegistrationRequest("not-an-email", "pass");
        
        // Act
        var result = service.register(request);
        
        // Assert
        assertFalse(result.isSuccess());
        assertEquals("Invalid email", result.getError());
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

// ════════════════════════════════════════════════════
// BAD: Overly broad interface (violates ISP)
// ════════════════════════════════════════════════════
 
public interface DataStore {
    // SQL operations - not all stores support SQL
    ResultSet executeSql(String query);
    void beginTransaction();
    void commit();
    void rollback();
    
    // Key-value operations - different concern
    String get(String key);
    void put(String key, String value);
    void delete(String key);
    
    // Document operations - another concern
    Document findDocument(Query query);
    void insertDocument(Document doc);
    
    // Full-text search - yet another concern
    SearchResults search(String text);
    void indexDocument(Document doc);
    
    // Caching - completely different concern!
    void setTtl(String key, Duration ttl);
    void evict(String key);
}
 
// Problem: A Redis implementation doesn't support SQL.
// A PostgreSQL implementation doesn't do full-text search natively.
// Implementations must throw UnsupportedOperationException.
// Clients don't know which methods are actually available.
 
 
// ════════════════════════════════════════════════════
// GOOD: Focused interfaces (follows ISP)
// ════════════════════════════════════════════════════
 
// Core key-value capability
public interface KeyValueStore {
    String get(String key);
    void put(String key, String value);
    void delete(String key);
    boolean exists(String key);
}
 
// Transaction capability (optional)
public interface Transactional {
    void beginTransaction();
    void commit();
    void rollback();
}
 
// SQL capability (optional)
public interface SqlCapable {
    ResultSet executeSql(String sql);
    PreparedStatement prepare(String sql);
}
 
// Document capability
public interface DocumentStore {
    Document find(Query query);
    void insert(Document doc);
    void update(String id, Document doc);
}
 
// Search capability
public interface Searchable {
    SearchResults search(String query);
    void index(String id, String content);
}
 
// Cache capability
public interface CacheableStore extends KeyValueStore {
    void setTtl(String key, Duration ttl);
    void evict(String key);
    Optional<Duration> getTtl(String key);
}
 
 
// ════════════════════════════════════════════════════
// IMPLEMENTATIONS: Declare exactly what they support
// ════════════════════════════════════════════════════
 
// Redis: Key-value + caching, no SQL
public class RedisStore implements CacheableStore {
    // Only implements what Redis actually supports
}
 
// PostgreSQL: SQL + transactions
public class PostgresStore implements SqlCapable, Transactional {
    // Implements what PostgreSQL supports
}
 
// Elasticsearch: Documents + search
public class ElasticsearchStore implements DocumentStore, Searchable {
    // Implements what Elasticsearch supports
}
 
// MongoDB: Documents + key-value style access
public class MongoStore implements DocumentStore, KeyValueStore {
    // Implements MongoDB's capabilities
}
 
 
// ════════════════════════════════════════════════════
// USAGE: Depend on exactly what you need
// ════════════════════════════════════════════════════
 
// This service needs only key-value - works with Redis, Mongo, etc.
public class SessionStore {
    private final KeyValueStore store;
    
    public void saveSession(String sessionId, String data) {
        store.put(sessionId, data);
    }
}
 
// This service needs SQL - works with Postgres, MySQL, etc.
public class ReportGenerator {
    private final SqlCapable database;
    
    public Report generate(String query) {
        ResultSet rs = database.executeSql(query);
        // ... process results
    }
}
 
// This service needs transactions
public class OrderProcessor {
    private final Transactional transactionalStore;
    
    public void processOrder(Order order) {
        transactionalStore.beginTransaction();
        try {
            // ... make changes
            transactionalStore.commit();
        } catch (Exception e) {
            transactionalStore.rollback();
            throw e;
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

// ═══════════════════════════════════════════════════
// LAYER BOUNDARIES: Clean separation via interfaces
// ═══════════════════════════════════════════════════
 
// Domain Layer - pure business logic, no infrastructure
package com.app.domain;
 
public interface OrderRepository {
    Order findById(OrderId id);
    void save(Order order);
    List<Order> findByCustomer(CustomerId customerId);
}
 
public class OrderService {
    private final OrderRepository repository;  // Interface dependency
    
    public void submitOrder(Order order) {
        order.validate();
        order.submit();
        repository.save(order);  // Domain knows nothing about JPA/SQL
    }
}
 
 
// Infrastructure Layer - implements domain interfaces
package com.app.infrastructure.persistence;
 
public class JpaOrderRepository implements OrderRepository {
    
    private final EntityManager em;
    
    @Override
    public Order findById(OrderId id) {
        return em.find(OrderEntity.class, id.getValue())
            .toDomain();  // Convert JPA entity to domain object
    }
    
    @Override
    public void save(Order order) {
        OrderEntity entity = OrderEntity.fromDomain(order);
        em.persist(entity);
    }
}
 
 
// ═══════════════════════════════════════════════════
// EXTERNAL ADAPTERS: Abstract external dependencies
// ═══════════════════════════════════════════════════
 
// Abstract storage interface
public interface FileStorage {
    String upload(String path, byte[] content, ContentType type);
    byte[] download(String path);
    void delete(String path);
    boolean exists(String path);
    String getPublicUrl(String path);
}
 
// AWS S3 implementation
public class S3FileStorage implements FileStorage {
    private final S3Client s3;
    private final String bucket;
    
    @Override
    public String upload(String path, byte[] content, ContentType type) {
        s3.putObject(
            PutObjectRequest.builder()
                .bucket(bucket)
                .key(path)
                .contentType(type.getMimeType())
                .build(),
            RequestBody.fromBytes(content)
        );
        return path;
    }
    // ... other implementations
}
 
// Google Cloud Storage implementation
public class GcsFileStorage implements FileStorage {
    private final Storage storage;
    private final String bucket;
    
    @Override
    public String upload(String path, byte[] content, ContentType type) {
        BlobId blobId = BlobId.of(bucket, path);
        BlobInfo blobInfo = BlobInfo.newBuilder(blobId)
            .setContentType(type.getMimeType())
            .build();
        storage.create(blobInfo, content);
        return path;
    }
    // ... other implementations
}
 
// Local filesystem for development/testing
public class LocalFileStorage implements FileStorage {
    private final Path basePath;
    
    @Override
    public String upload(String path, byte[] content, ContentType type) {
        Path fullPath = basePath.resolve(path);
        Files.createDirectories(fullPath.getParent());
        Files.write(fullPath, content);
        return path;
    }
    // ... other implementations
}
 
 
// ═══════════════════════════════════════════════════
// USAGE: Application code uses interfaces
// ═══════════════════════════════════════════════════
 
// Service layer - doesn't know or care which storage is used
public class DocumentService {
    private final FileStorage storage;
    
    public DocumentService(FileStorage storage) {
        this.storage = storage;
    }
    
    public Document upload(MultipartFile file) {
        String path = generatePath(file.getName());
        storage.upload(path, file.getBytes(), file.getContentType());
        return new Document(path, storage.getPublicUrl(path));
    }
}
 
// Configuration - chooses implementation based on environment
@Configuration
public class StorageConfig {
    
    @Bean
    @Profile("production")
    public FileStorage productionStorage() {
        return new S3FileStorage(S3Client.create(), "prod-bucket");
    }
    
    @Bean
    @Profile("staging")
    public FileStorage stagingStorage() {
        return new GcsFileStorage(StorageOptions.getDefaultInstance().getService(), "staging-bucket");
    }
    
    @Bean
    @Profile("local")
    public FileStorage localStorage() {
        return new LocalFileStorage(Paths.get("./uploads"));
    }
}