Merge branch 'issue-2673' of https://github.com/quantdevv/java-design-patterns into issue-2673

Author: quantdevv

.all-contributorsrc

@@ -3493,6 +3493,43 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "ssrijan-007-sys",
+      "name": "ssrijan-007-sys",
+      "avatar_url": "https://avatars.githubusercontent.com/u/137605821?v=4",
+      "profile": "https://github.com/ssrijan-007-sys",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "e5LA",
+      "name": "e5LA",
+      "avatar_url": "https://avatars.githubusercontent.com/u/208197507?v=4",
+      "profile": "https://github.com/e5LA",
+      "contributions": [
+        "code",
+        "doc"
+      ]
+    },
+    {
+      "login": "maziyar-gerami",
+      "name": "Maziyar Gerami",
+      "avatar_url": "https://avatars.githubusercontent.com/u/122622721?v=4",
+      "profile": "http://maziyar-gerami.github.io/portfolio/",
+      "contributions": [
+        "translation"
+      ]
+    },
+    {
+      "login": "yybmion",
+      "name": "yoobin_mion",
+      "avatar_url": "https://avatars.githubusercontent.com/u/113106136?v=4",
+      "profile": "https://github.com/yybmion",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "contributorsPerLine": 6,

README.md

@@ -6,7 +6,7 @@
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=iluwatar_java-design-patterns&metric=coverage)](https://sonarcloud.io/dashboard?id=iluwatar_java-design-patterns)
 [![Join the chat at https://gitter.im/iluwatar/java-design-patterns](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/iluwatar/java-design-patterns?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-383-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-387-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 <br/>
@@ -45,7 +45,7 @@ If you are willing to contribute to the project you will find the relevant infor
 
 # The Book
 
-The design patterns are now available as an e-book. Find out more about "Open Source Java Design Patterns" here: https://payhip.com/b/kcaF9
+The design patterns are now available as an e-book. Find out more about "Open Source Java Design Patterns" here: https://payhip.com/b/bNQFX
 
 The project contributors can get the book for free. Contact the maintainer via [Gitter chatroom](https://gitter.im/iluwatar/java-design-patterns) or email (iluwatar (at) gmail (dot) com ). Send a message that contains your email address, Github username, and a link to an accepted pull request.
 
@@ -570,6 +570,12 @@ This project is licensed under the terms of the MIT license.
       <td align="center" valign="top" width="16.66%"><a href="https://github.com/sanurah"><img src="https://avatars.githubusercontent.com/u/16178588?v=4?s=100" width="100px;" alt="Sanura Hettiarachchi"/><br /><sub><b>Sanura Hettiarachchi</b></sub></a><br /><a href="https://github.com/iluwatar/java-design-patterns/commits?author=sanurah" title="Code">💻</a></td>
       <td align="center" valign="top" width="16.66%"><a href="https://github.com/2897robo"><img src="https://avatars.githubusercontent.com/u/31699375?v=4?s=100" width="100px;" alt="Kim Gi Uk"/><br /><sub><b>Kim Gi Uk</b></sub></a><br /><a href="https://github.com/iluwatar/java-design-patterns/commits?author=2897robo" title="Code">💻</a></td>
       <td align="center" valign="top" width="16.66%"><a href="https://github.com/Suchismita-Deb"><img src="https://avatars.githubusercontent.com/u/68535074?v=4?s=100" width="100px;" alt="Suchismita Deb"/><br /><sub><b>Suchismita Deb</b></sub></a><br /><a href="https://github.com/iluwatar/java-design-patterns/commits?author=Suchismita-Deb" title="Code">💻</a></td>
+      <td align="center" valign="top" width="16.66%"><a href="https://github.com/ssrijan-007-sys"><img src="https://avatars.githubusercontent.com/u/137605821?v=4?s=100" width="100px;" alt="ssrijan-007-sys"/><br /><sub><b>ssrijan-007-sys</b></sub></a><br /><a href="https://github.com/iluwatar/java-design-patterns/commits?author=ssrijan-007-sys" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="16.66%"><a href="https://github.com/e5LA"><img src="https://avatars.githubusercontent.com/u/208197507?v=4?s=100" width="100px;" alt="e5LA"/><br /><sub><b>e5LA</b></sub></a><br /><a href="https://github.com/iluwatar/java-design-patterns/commits?author=e5LA" title="Code">💻</a> <a href="https://github.com/iluwatar/java-design-patterns/commits?author=e5LA" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="16.66%"><a href="http://maziyar-gerami.github.io/portfolio/"><img src="https://avatars.githubusercontent.com/u/122622721?v=4?s=100" width="100px;" alt="Maziyar Gerami"/><br /><sub><b>Maziyar Gerami</b></sub></a><br /><a href="#translation-maziyar-gerami" title="Translation">🌍</a></td>
+      <td align="center" valign="top" width="16.66%"><a href="https://github.com/yybmion"><img src="https://avatars.githubusercontent.com/u/113106136?v=4?s=100" width="100px;" alt="yoobin_mion"/><br /><sub><b>yoobin_mion</b></sub></a><br /><a href="https://github.com/iluwatar/java-design-patterns/commits?author=yybmion" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

actor-model/README.md

@@ -0,0 +1,201 @@
+---
+title: "Actor Model Pattern in Java: Building Concurrent Systems with Elegance"
+shortTitle: Actor Model
+description: "Explore the Actor Model pattern in Java with real-world examples and practical implementation. Learn how to build scalable, message-driven systems using actors, messages, and asynchronous communication."
+category: Concurrency
+language: en
+tag:
+    - Concurrency
+    - Messaging
+    - Isolation
+    - Asynchronous
+    - Distributed Systems
+    - Actor Model
+---
+
+## Also Known As
+
+- Message-passing concurrency
+- Actor-based concurrency
+
+---
+
+## Intent of Actor Model Pattern
+
+The Actor Model pattern enables the construction of highly concurrent, distributed, and fault-tolerant systems by using isolated components (actors) that interact exclusively through asynchronous message passing.
+
+---
+
+## Detailed Explanation of Actor Model Pattern with Real-World Examples
+
+### 📦 Real-world Example
+
+Imagine a customer service system:
+- Each **customer support agent** is an **actor**.
+- Customers **send questions (messages)** to agents.
+- Each agent handles one request at a time and can **respond asynchronously** without interfering with other agents.
+
+---
+
+### 🧠 In Plain Words
+
+> "Actors are like independent workers that never share memory and only communicate through messages."
+
+---
+
+### 📖 Wikipedia Says
+
+> [Actor model](https://en.wikipedia.org/wiki/Actor_model) is a mathematical model of concurrent computation that treats "actors" as the universal primitives of concurrent computation.
+
+---
+
+### 🧹 Architecture Diagram
+
+![UML Class Diagram](./etc/Actor_Model_UML_Class_Diagram.png)
+
+---
+
+## Programmatic Example of Actor Model Pattern in Java
+
+### Actor.java
+
+```java
+public abstract class Actor implements Runnable {
+
+    @Setter @Getter private String actorId;
+    private final BlockingQueue<Message> mailbox = new LinkedBlockingQueue<>();
+    private volatile boolean active = true; 
+
+
+    public void send(Message message) {
+        mailbox.add(message); 
+    }
+
+    public void stop() {
+        active = false; 
+    }
+
+    @Override
+    public void run() {
+        
+    }
+
+    protected abstract void onReceive(Message message);
+}
+
+```
+
+### Message.java
+
+```java
+
+@AllArgsConstructor
+@Getter
+@Setter
+public class Message {
+    private final String content;
+    private final String senderId;
+}
+```
+
+### ActorSystem.java
+
+```java
+public class ActorSystem {
+    public void startActor(Actor actor) {
+        String actorId = "actor-" + idCounter.incrementAndGet(); // Generate a new and unique ID
+        actor.setActorId(actorId); // assign the actor it's ID
+        actorRegister.put(actorId, actor); // Register and save the actor with it's ID
+        executor.submit(actor); // Run the actor in a thread
+    }
+    public Actor getActorById(String actorId) {
+        return actorRegister.get(actorId); //  Find by Id
+    }
+
+    public void shutdown() {
+        executor.shutdownNow(); // Stop all threads
+    }
+}
+```
+
+### App.java
+
+```java
+public class App {
+  public static void main(String[] args) {
+    ActorSystem system = new ActorSystem();
+      Actor srijan = new ExampleActor(system);
+      Actor ansh = new ExampleActor2(system);
+
+      system.startActor(srijan);
+      system.startActor(ansh);
+      ansh.send(new Message("Hello ansh", srijan.getActorId()));
+      srijan.send(new Message("Hello srijan!", ansh.getActorId()));
+
+      Thread.sleep(1000); // Give time for messages to process
+
+      srijan.stop(); // Stop the actor gracefully
+      ansh.stop();
+      system.shutdown(); // Stop the actor system
+  }
+}
+```
+
+---
+
+## When to Use the Actor Model Pattern in Java
+
+- When building **concurrent or distributed systems**
+- When you want **no shared mutable state**
+- When you need **asynchronous, message-driven communication**
+- When components should be **isolated and loosely coupled**
+
+---
+
+## Actor Model Pattern Java Tutorials
+
+- [Baeldung – Akka with Java](https://www.baeldung.com/java-akka)
+- [Vaughn Vernon – Reactive Messaging Patterns](https://vaughnvernon.co/?p=1143)
+
+---
+
+## Real-World Applications of Actor Model Pattern in Java
+
+- [Akka Framework](https://akka.io/)
+- [Erlang and Elixir concurrency](https://www.erlang.org/)
+- [Microsoft Orleans](https://learn.microsoft.com/en-us/dotnet/orleans/)
+- JVM-based game engines and simulators
+
+---
+
+## Benefits and Trade-offs of Actor Model Pattern
+
+### ✅ Benefits
+- High concurrency support
+- Easy scaling across threads or machines
+- Fault isolation and recovery
+- Message ordering within actors
+
+### ⚠️ Trade-offs
+- Harder to debug due to asynchronous behavior
+- Slight performance overhead due to message queues
+- More complex to design than simple method calls
+
+---
+
+## Related Java Design Patterns
+
+- [Command Pattern](../command)
+- [Mediator Pattern](../mediator)
+- [Event-Driven Architecture](../event-driven-architecture)
+- [Observer Pattern](../observer)
+
+---
+
+## References and Credits
+
+- *Programming Erlang*, Joe Armstrong
+- *Reactive Design Patterns*, Roland Kuhn
+- *The Actor Model in 10 Minutes*, [InfoQ Article](https://www.infoq.com/articles/actor-model/)
+- [Akka Documentation](https://doc.akka.io/docs/akka/current/index.html)
+

actor-model/etc/Actor_Model_UML_Class_Diagram.png

@@ -0,0 +1,35 @@
+@startuml actor-model
+
+title Actor Model - UML Class Diagram
+
+class ActorSystem {
+  +actorOf(actor: Actor): Actor
+  +shutdown(): void
+}
+
+class Actor {
+  -mailbox: BlockingQueue<Message>
+  -active: boolean
+  +send(message: Message): void
+  +stop(): void
+  +run(): void
+  #onReceive(message: Message): void
+}
+
+class ExampleActor {
+  +onReceive(message: Message): void
+}
+
+class Message {
+  -content: String
+  -sender: Actor
+  +getContent(): String
+  +getSender(): Actor
+}
+
+ActorSystem --> Actor : creates
+Actor <|-- ExampleActor : extends
+Actor --> Message : processes
+ExampleActor --> Message : uses
+
+@enduml