Add Microservices Bulkhead pattern implementation (#3228)

microservices-bulkhead/README.md

@@ -0,0 +1,192 @@
+---
+title: "Bulkhead Pattern in Java: Isolating Resources for Resilient Microservices"
+shortTitle: Bulkhead
+description: "Learn how the Bulkhead pattern in Java isolates critical system resources to prevent cascade failures in microservices. Includes real-world examples, code demonstrations, and best practices for building resilient distributed systems."
+category: Resilience
+language: en
+tag:
+  - Resilience
+  - Fault tolerance
+  - Microservices
+  - Performance
+  - Scalability
+  - Thread management
+---
+
+## Also known as
+
+* Resource Isolation Pattern
+* Partition Pattern
+
+## Intent of Bulkhead Design Pattern
+
+The Bulkhead pattern isolates critical system resources for each service or component to prevent failures or heavy load in one part of the system from cascading and degrading the entire application. By partitioning resources—often via separate thread pools or connection pools—the system ensures other services remain operational even if one service becomes overloaded or fails.
+
+## Detailed Explanation of Bulkhead Pattern with Real-World Examples
+
+Real-world example
+
+> Consider a modern cruise ship with multiple watertight compartments (bulkheads). If one compartment is breached and starts flooding, the bulkheads prevent water from spreading to other compartments, keeping the ship afloat. Similarly, in software systems, the Bulkhead pattern creates isolated resource pools for different services. If one service experiences issues (like a slow external API or heavy load), it only affects its dedicated resources, while other services continue operating normally with their own resource pools.
+
+In plain words
+
+> The Bulkhead pattern partitions system resources into isolated pools so that failures in one area don't consume all available resources and bring down the entire system.
+
+## Programmatic Example of Bulkhead Pattern in Java
+
+The Bulkhead pattern implementation demonstrates resource isolation using dedicated thread pools for different services. Here we have a `UserService` handling critical user requests and a `BackgroundService` handling non-critical tasks.
+
+First, let's look at the base `BulkheadService` class that provides resource isolation:
+
+```
+public abstract class BulkheadService {
+private static final Logger LOGGER = LoggerFactory.getLogger(BulkheadService.class);
+
+protected final ThreadPoolExecutor executor;
+protected final String serviceName;
+
+protected BulkheadService(String serviceName, int maxPoolSize, int queueCapacity) {
+this.serviceName = serviceName;
+
+    // Create thread pool with bounded queue for resource isolation
+    this.executor = new ThreadPoolExecutor(
+        maxPoolSize,
+        maxPoolSize,
+        60L,
+        TimeUnit.SECONDS,
+        new ArrayBlockingQueue<>(queueCapacity),
+        new ThreadPoolExecutor.AbortPolicy() // fail-fast when full
+    );
+
+    LOGGER.info("Created {} with {} threads and queue capacity {}", 
+        serviceName, maxPoolSize, queueCapacity);
+}
+
+public boolean submitTask(Task task) {
+try {
+executor.execute(() -> processTask(task));
+LOGGER.info("[{}] Task '{}' submitted successfully", serviceName, task.getName());
+return true;
+} catch (RejectedExecutionException e) {
+LOGGER.warn("[{}] Task '{}' REJECTED - bulkhead is full", serviceName, task.getName());
+handleRejectedTask(task);
+return false;
+}
+}
+}
+```
+
+The `UserService` handles critical user-facing requests with dedicated resources:
+
+```
+public class UserService extends BulkheadService {
+private static final int DEFAULT_QUEUE_CAPACITY = 10;
+
+public UserService(int maxThreads) {
+super("UserService", maxThreads, DEFAULT_QUEUE_CAPACITY);
+}
+}
+```
+
+The `BackgroundService` handles non-critical background tasks with its own isolated resources:
+
+```
+public class BackgroundService extends BulkheadService {
+private static final int DEFAULT_QUEUE_CAPACITY = 20;
+
+public BackgroundService(int maxThreads) {
+super("BackgroundService", maxThreads, DEFAULT_QUEUE_CAPACITY);
+}
+}
+```
+
+Here's the demonstration showing how the Bulkhead pattern prevents cascade failures:
+
+```
+public class App {
+public static void main(String[] args) {
+BulkheadService userService = new UserService(3);
+BulkheadService backgroundService = new BackgroundService(2);
+
+    // Overload background service with many tasks
+    for (int i = 1; i <= 10; i++) {
+      Task task = new Task("Heavy-Background-Job-" + i, TaskType.BACKGROUND_PROCESSING, 2000);
+      backgroundService.submitTask(task);
+    }
+
+    // User service remains responsive despite background service overload
+    for (int i = 1; i <= 3; i++) {
+      Task task = new Task("Critical-User-Request-" + i, TaskType.USER_REQUEST, 300);
+      boolean accepted = userService.submitTask(task);
+      LOGGER.info("User request {} accepted: {}", i, accepted);
+    }
+}
+}
+```
+
+Program output:
+
+```
+[BackgroundService] Task 'Heavy-Background-Job-1' submitted successfully
+[BackgroundService] Task 'Heavy-Background-Job-2' submitted successfully
+[BackgroundService] Task 'Heavy-Background-Job-3' REJECTED - bulkhead is full
+...
+[UserService] Task 'Critical-User-Request-1' submitted successfully
+[UserService] Task 'Critical-User-Request-2' submitted successfully
+[UserService] Task 'Critical-User-Request-3' submitted successfully
+User request 1 accepted: true
+User request 2 accepted: true
+User request 3 accepted: true
+```
+
+The output demonstrates that even when the background service is overloaded and rejecting tasks, the user service continues to accept and process requests successfully due to resource isolation.
+
+## When to Use the Bulkhead Pattern in Java
+
+* When building microservices architectures where service failures should not cascade
+* When different operations have varying criticality levels (e.g., user-facing vs. background tasks)
+* When external dependencies (databases, APIs) might become slow or unavailable
+* When you need to guarantee minimum service levels for critical operations
+* In high-throughput systems where resource exhaustion in one area could impact other services
+
+## Real-World Applications of Bulkhead Pattern in Java
+
+* Netflix's Hystrix library implements bulkheads using thread pool isolation
+* Resilience4j provides bulkhead implementations for Java applications
+* AWS Lambda functions run in isolated execution environments (bulkheads)
+* Kubernetes resource limits and quotas implement bulkhead principles
+* Database connection pools per service in microservices architectures
+
+## Benefits and Trade-offs of Bulkhead Pattern
+
+Benefits:
+
+* Prevents cascade failures across services
+* Improves system resilience and availability
+* Provides predictable degradation under load
+* Enables independent scaling of different services
+* Facilitates easier capacity planning and monitoring
+
+Trade-offs:
+
+* Increased resource overhead (multiple thread pools)
+* More complex configuration and tuning
+* Potential for resource underutilization if pools are too large
+* Requires careful capacity planning for each bulkhead
+* May increase overall latency due to queuing
+
+## Related Java Design Patterns
+
+* [Circuit Breaker](https://java-design-patterns.com/patterns/circuit-breaker/): Often used together with Bulkhead; Circuit Breaker stops calling failing services while Bulkhead limits resources
+* [Retry](https://java-design-patterns.com/patterns/retry/): Can be combined with Bulkhead for transient failure handling
+* [Throttling](https://java-design-patterns.com/patterns/throttling/): Similar goal of resource management but focuses on rate limiting rather than isolation
+* [Load Balancer](https://java-design-patterns.com/patterns/load-balancer/): Works at request distribution level while Bulkhead works at resource isolation level
+
+## References and Credits
+
+* [Release It!: Design and Deploy Production-Ready Software](https://amzn.to/3Uul4kF) - Michael T. Nygard
+* [Microservices Patterns: With examples in Java](https://amzn.to/3UyWD5O) - Chris Richardson
+* [Building Microservices: Designing Fine-Grained Systems](https://amzn.to/3RYRz96) - Sam Newman
+* [Resilience4j Documentation - Bulkhead](https://resilience4j.readme.io/docs/bulkhead)
+* [Microsoft Azure Architecture - Bulkhead Pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/bulkhead)
+* [Microservices.io - Bulkhead Pattern](https://microservices.io/patterns/reliability/bulkhead.html)

microservices-bulkhead/pom.xml

@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~
+  ~ This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt).
+  ~
+  ~ The MIT License
+  ~ Copyright © 2014-2025 Ilkka Seppälä
+  ~
+  ~ Permission is hereby granted, free of charge, to any person obtaining a copy
+  ~ of this software and associated documentation files (the "Software"), to deal
+  ~ in the Software without restriction, including without limitation the rights
+  ~ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  ~ copies of the Software, and to permit persons to whom the Software is
+  ~ furnished to do so, subject to the following conditions:
+  ~
+  ~ The above copyright notice and this permission notice shall be included in
+  ~ all copies or substantial portions of the Software.
+  ~
+  ~ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  ~ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  ~ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  ~ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  ~ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  ~ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+  ~ THE SOFTWARE.
+  ~
+  -->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>com.iluwatar</groupId>
+        <artifactId>java-design-patterns</artifactId>
+        <version>1.26.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>bulkhead</artifactId>
+    <packaging>jar</packaging>
+
+    <name>Bulkhead</name>
+    <description>
+        The Bulkhead pattern isolates critical system resources for each service or component
+        to prevent failures or heavy load in one part from cascading and degrading the entire system.
+        By partitioning resources via separate thread pools, the system ensures other services
+        remain operational even if one service becomes overloaded or fails.
+    </description>
+
+    <properties>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <!-- SLF4J API for logging -->
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+        </dependency>
+
+        <!-- Logback for logging implementation -->
+        <dependency>
+            <groupId>ch.qos.logback</groupId>
+            <artifactId>logback-classic</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+
+        <!-- JUnit Jupiter for testing -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+
+        <!-- JUnit Jupiter Params for parameterized tests -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-params</artifactId>
+            <scope>test</scope>
+        </dependency>
+
+        <!-- Mockito for mocking in tests -->
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+
+        <!-- AssertJ for fluent assertions in tests -->
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <version>3.27.7</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <!-- Maven Compiler Plugin -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+            </plugin>
+
+            <!-- Maven Surefire Plugin for running tests -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+            </plugin>
+
+            <!-- Spotless Plugin for code formatting -->
+            <plugin>
+                <groupId>com.diffplug.spotless</groupId>
+                <artifactId>spotless-maven-plugin</artifactId>
+            </plugin>
+
+            <!-- Maven Checkstyle Plugin -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-checkstyle-plugin</artifactId>
+            </plugin>
+
+            <!-- PMD Plugin for static code analysis -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-pmd-plugin</artifactId>
+            </plugin>
+
+            <!-- SpotBugs Plugin for bug detection -->
+            <plugin>
+                <groupId>com.github.spotbugs</groupId>
+                <artifactId>spotbugs-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>