Skip to content

Add Microservices Bulkhead pattern implementation (#3228) #3326

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add Microservices Bulkhead pattern implementation (#3228) #3326

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 192 additions & 0 deletions microservices-bulkhead/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
144 changes: 144 additions & 0 deletions microservices-bulkhead/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
<?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>

<!-- Lombok for reducing boilerplate code -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</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>
<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>
Loading
Loading