From 076fc21e404b8abadc6cc14b41c30866a5b85267 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= Date: Mon, 14 Apr 2025 20:13:14 +0300 Subject: [PATCH] docs: update microservices idempotent consumer --- microservices-distributed-tracing/README.md | 6 +- microservices-idempotent-consumer/README.md | 94 +++++++++++------- ...services-idempotent-consumer-flowchart.png | Bin 0 -> 64392 bytes .../idempotentconsumer/RequestService.java | 7 +- .../iluwatar/idempotentconsumer/AppTest.java | 4 +- .../RequestServiceTests.java | 3 +- .../RequestStateMachineTests.java | 2 +- 7 files changed, 68 insertions(+), 48 deletions(-) create mode 100644 microservices-idempotent-consumer/etc/microservices-idempotent-consumer-flowchart.png diff --git a/microservices-distributed-tracing/README.md b/microservices-distributed-tracing/README.md index 1adf6db32..4fc271a68 100644 --- a/microservices-distributed-tracing/README.md +++ b/microservices-distributed-tracing/README.md @@ -1,6 +1,6 @@ --- -title: "Microservices Distributed Tracing Pattern: Enhancing Visibility in Service Communication" -shortTitle: Distributed Tracing in Microservices +title: "Microservices Distributed Tracing Pattern In Java: Enhancing Visibility in Service Communication" +shortTitle: Microservices Distributed Tracing description: "Learn how the Distributed Tracing pattern enhances visibility into service communication across microservices. Discover its benefits, implementation examples, and best practices." category: Architectural language: en @@ -8,8 +8,8 @@ tag: - Cloud distributed - Microservices - Resilience - - Scalability - Observability + - Scalability - System health --- diff --git a/microservices-idempotent-consumer/README.md b/microservices-idempotent-consumer/README.md index a3065861a..738bbcda5 100644 --- a/microservices-idempotent-consumer/README.md +++ b/microservices-idempotent-consumer/README.md @@ -1,53 +1,56 @@ --- -title: "Idempotent Consumer Pattern in Java: Ensuring Reliable Message Processing" -shortTitle: Idempotent Consumer +title: "Microservices Idempotent Consumer Pattern in Java: Ensuring Reliable Message Processing" +shortTitle: Microservices Idempotent Consumer description: "Learn about the Idempotent Consumer pattern in Java. Discover how it ensures reliable and consistent message processing, even in cases of duplicate messages." -category: Structural +category: Messaging language: en tag: + - Asynchronous + - Decoupling - Event-driven + - Messaging + - Microservices + - Resilience + - Retry --- ## Also known as -* Idempotency Pattern +* Idempotent Subscriber +* Repeatable Message Consumer +* Safe Consumer ## Intent of Idempotent Consumer Pattern -The Idempotent Consumer pattern is used to handle duplicate messages in distributed systems, ensuring that multiple processing of the same message does not cause undesired side effects. This pattern guarantees that the same message can be processed repeatedly with the same outcome, which is critical in ensuring reliable communication and data consistency in systems where message duplicates are possible. +Ensure that consuming the same message multiple times does not cause unintended side effects in a microservices-based architecture. ## Detailed Explanation of Idempotent Consumer Pattern with Real-World Examples -### Real-world Example +Real-world example > In a payment processing system, ensuring that payment messages are idempotent prevents duplicate transactions. For example, if a user’s payment message is accidentally processed twice, the system should recognize the second message as a duplicate and prevent it from executing a second time. By storing unique identifiers for each processed message, such as a transaction ID, the system can skip any duplicate messages. This ensures that a user is not charged twice for the same transaction, maintaining system integrity and customer satisfaction. -### In Plain Words +In plain words > The Idempotent Consumer pattern prevents duplicate messages from causing unintended side effects by ensuring that processing the same message multiple times results in the same outcome. This makes message processing safe in distributed systems where duplicates may occur. -### Wikipedia says + +Wikipedia says > In computing, idempotence is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application. -## When to Use the Idempotent Consumer Pattern +Flowchart -The Idempotent Consumer pattern is particularly useful in scenarios: - -* When messages can be duplicated due to network retries or communication issues. -* In distributed systems where message ordering is not guaranteed, making deduplication necessary to avoid repeated processing. -* In financial or critical systems, where duplicate processing would have significant side effects. - -## Real-World Applications of Idempotent Consumer Pattern - -* Payment processing systems that avoid duplicate transactions. -* E-commerce systems to prevent multiple entries of the same order. -* Inventory management systems to prevent multiple entries when updating stock levels. +![Microservices Idempotent Consumer flowchart](./etc/microservices-idempotent-consumer-flowchart.png) ## Programmatic example of Idempotent Consumer Pattern -In this Java example, we have an idempotent service that offers functionality to create and update (start, complete, etc.) orders. The service ensures that the **create order** operation is idempotent, meaning that performing it multiple times with the same order ID will lead to the same result without creating duplicates. For state transitions (such as starting or completing an order), the service enforces valid state changes and throws exceptions if an invalid transition is attempted. The state machine governs the valid order status transitions, ensuring that statuses progress in a defined and consistent sequence. + +In this Java example, we have an idempotent service that creates and updates orders. The `create` method is idempotent, meaning multiple calls with the same order ID return the same result without duplicates. For state changes (like starting or completing an order), the service checks whether the transition is valid and throws an exception if it’s not allowed. The `RequestStateMachine` ensures that order statuses move forward in a valid sequence (e.g., PENDING → STARTED → COMPLETED). + ### RequestService - Managing Idempotent Order Operations -The `RequestService` class is responsible for handling the creation and state transitions of orders. The `create` method is designed to be idempotent, ensuring that it either returns an existing order or creates a new one without any side effects if invoked multiple times with the same order ID. + +The `RequestService` class provides methods to create and transition an order. The `create` method returns an existing order if it already exists, making it idempotent. + ```java public class RequestService { // Idempotent: ensures that the same request is returned if it already exists @@ -76,8 +79,11 @@ public class RequestService { } } ``` + ### RequestStateMachine - Managing Order Transitions -The `RequestStateMachine` ensures that state transitions occur in a valid order. It handles the progression of an order's status, ensuring the correct sequence (e.g., from `PENDING` to `STARTED` to `COMPLETED`). + +The `RequestStateMachine` enforces valid state changes. If a requested transition is not allowed based on the current status, an exception is thrown. + ```java public class RequestStateMachine { @@ -102,9 +108,10 @@ public class RequestStateMachine { } } ``` + ### Main Application - Running the Idempotent Consumer Example -In the main application, we demonstrate how the `RequestService` can be used to perform idempotent operations. Whether the order creation or state transition is invoked once or multiple times, the result is consistent and does not produce unexpected side effects. +Here, we demonstrate how `RequestService` can be called multiple times without creating duplicate orders. We also show how invalid transitions (like trying to start an order twice) result in exceptions, while valid transitions proceed normally. ```java Request req = requestService.create(UUID.randomUUID()); @@ -127,32 +134,49 @@ req = requestService.complete(req.getUuid()); // Log the final status of the Request to confirm it's been completed LOGGER.info("Request: {}", req); ``` + Program output: + ``` 19:01:54.382 INFO [main] com.iluwatar.idempotentconsumer.App : Nb of requests : 1 19:01:54.395 ERROR [main] com.iluwatar.idempotentconsumer.App : Cannot start request twice! 19:01:54.399 INFO [main] com.iluwatar.idempotentconsumer.App : Request: Request(uuid=2d5521ef-6b6b-4003-9ade-81e381fe9a63, status=COMPLETED) ``` + +## When to Use the Idempotent Consumer Pattern + +* When messages can arrive more than once due to network glitches or retries +* When microservices must guarantee consistent state changes regardless of duplicates +* When fault-tolerant event-driven communication is critical to system reliability +* When horizontal scaling requires stateless consumer operations + +## Real-World Applications of Idempotent Consumer Pattern + +* Payment processing systems that receive duplicate charge events +* E-commerce order services that handle duplicate purchase requests +* Notification services that retry failed message deliveries +* Distributed transaction systems where duplicated events are common + ## Benefits and Trade-offs of the Idempotent Consumer Pattern -### Benefits +Benefits -* **Reliability**: Ensures that messages can be processed without unwanted side effects from duplicates. -* **Consistency**: Maintains data integrity by ensuring that duplicate messages do not cause redundant updates or actions. -* **Fault Tolerance**: Handles message retries gracefully, preventing them from causing errors. +* Prevents duplicate side effects +* Increases reliability under repeated or delayed messages +* Simplifies error handling and retry logic -### Trade-offs +Trade-offs -* **State Management**: Requires storing processed message IDs, which can add memory overhead. -* **Complexity**: Implementing deduplication mechanisms can increase the complexity of the system. -* **Scalability**: In high-throughput systems, maintaining a large set of processed messages can impact performance and resource usage. +* Requires careful design to track processed messages +* Can add overhead for maintaining idempotency tokens or state +* May require additional storage or database transactions ## Related Patterns in Java -* [Retry Pattern](https://java-design-patterns.com/patterns/retry/): Works well with the Idempotent Consumer pattern to handle failed messages. -* [Circuit Breaker Pattern](https://java-design-patterns.com/patterns/circuitbreaker/): Often used alongside idempotent consumers to prevent repeated failures from causing overload. +* Outbox Pattern: Uses a dedicated table or storage to reliably publish events and handle deduplication at the source. ## References and Credits +* [Building Microservices](https://amzn.to/3UACtrU) * [Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions](https://amzn.to/4dznP2Y) -* [Designing Data-Intensive Applications](https://amzn.to/3UADv7Q) +* [Microservices Patterns: With examples in Java](https://amzn.to/3UyWD5O) diff --git a/microservices-idempotent-consumer/etc/microservices-idempotent-consumer-flowchart.png b/microservices-idempotent-consumer/etc/microservices-idempotent-consumer-flowchart.png new file mode 100644 index 0000000000000000000000000000000000000000..e5bd5d83ac8b7496b69d0046844bb051144b3767 GIT binary patch literal 64392 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 D5M&ov literal 0 HcmV?d00001 diff --git a/microservices-idempotent-consumer/src/main/java/com/iluwatar/idempotentconsumer/RequestService.java b/microservices-idempotent-consumer/src/main/java/com/iluwatar/idempotentconsumer/RequestService.java index 796053330..39d496120 100644 --- a/microservices-idempotent-consumer/src/main/java/com/iluwatar/idempotentconsumer/RequestService.java +++ b/microservices-idempotent-consumer/src/main/java/com/iluwatar/idempotentconsumer/RequestService.java @@ -44,7 +44,7 @@ public class RequestService { } /** - * Creates a new Request or returns an existing one by it's UUID. This operation is idempotent: + * Creates a new Request or returns an existing one by its UUID. This operation is idempotent: * performing it once or several times successively leads to an equivalent result. * * @param uuid The unique identifier for the Request. @@ -52,10 +52,7 @@ public class RequestService { */ public Request create(UUID uuid) { Optional optReq = requestRepository.findById(uuid); - if (!optReq.isEmpty()) { - return optReq.get(); - } - return requestRepository.save(new Request(uuid)); + return optReq.orElseGet(() -> requestRepository.save(new Request(uuid))); } /** diff --git a/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/AppTest.java b/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/AppTest.java index 457febeda..f6cd88e0f 100644 --- a/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/AppTest.java +++ b/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/AppTest.java @@ -39,12 +39,12 @@ import org.springframework.boot.CommandLineRunner; class AppTest { @Test - void main() { + void testMain() { assertDoesNotThrow(() -> App.main(new String[] {})); } @Test - void run() throws Exception { + void testRun() throws Exception { RequestService requestService = Mockito.mock(RequestService.class); RequestRepository requestRepository = Mockito.mock(RequestRepository.class); UUID uuid = UUID.randomUUID(); diff --git a/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/RequestServiceTests.java b/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/RequestServiceTests.java index f883709a9..20470d515 100644 --- a/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/RequestServiceTests.java +++ b/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/RequestServiceTests.java @@ -43,11 +43,10 @@ import org.mockito.junit.jupiter.MockitoExtension; class RequestServiceTests { private RequestService requestService; @Mock private RequestRepository requestRepository; - private RequestStateMachine requestStateMachine; @BeforeEach void setUp() { - requestStateMachine = new RequestStateMachine(); + RequestStateMachine requestStateMachine = new RequestStateMachine(); requestService = new RequestService(requestRepository, requestStateMachine); } diff --git a/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/RequestStateMachineTests.java b/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/RequestStateMachineTests.java index 62837cbf5..d160814a0 100644 --- a/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/RequestStateMachineTests.java +++ b/microservices-idempotent-consumer/src/test/java/com/iluwatar/idempotentconsumer/RequestStateMachineTests.java @@ -35,7 +35,7 @@ class RequestStateMachineTests { private RequestStateMachine requestStateMachine; @BeforeEach - public void setUp() { + void setUp() { requestStateMachine = new RequestStateMachine(); }