From d80eca177b2fada0f31a1e3350663096f3076cda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= Date: Wed, 16 Apr 2025 21:31:31 +0300 Subject: [PATCH 01/19] docs: update book link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 881563902e26..a52d7f3f1fed 100644 --- a/README.md +++ b/README.md @@ -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. From 1cde704bcbf7029e28bd8f671ac53943fe6ec6f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= Date: Tue, 22 Apr 2025 07:56:11 +0300 Subject: [PATCH 02/19] docs: remove some old diagrams --- data-access-object/README.md | 4 ---- data-locality/README.md | 4 ---- 2 files changed, 8 deletions(-) diff --git a/data-access-object/README.md b/data-access-object/README.md index bd020252d253..7e84299e23e1 100644 --- a/data-access-object/README.md +++ b/data-access-object/README.md @@ -199,10 +199,6 @@ The program output: 10:02:09.898 [main] INFO com.iluwatar.dao.App -- customerDao.getAllCustomers(): java.util.stream.ReferencePipeline$Head@f2f2cc1 ``` -## Detailed Explanation of Data Access Object Pattern with Real-World Examples - -![Data Access Object](./etc/dao.png "Data Access Object") - ## When to Use the Data Access Object Pattern in Java Use the Data Access Object in any of the following situations: diff --git a/data-locality/README.md b/data-locality/README.md index e9f556b8ad5c..a59103b3f89b 100644 --- a/data-locality/README.md +++ b/data-locality/README.md @@ -128,10 +128,6 @@ The console output: In this way, the data-locality module demonstrates the Data Locality pattern. By updating all components of the same type together, it increases the likelihood that the data needed for the update is already in the cache, thereby improving performance. -## Detailed Explanation of Data Locality Pattern with Real-World Examples - -![Data Locality](./etc/data-locality.urm.png "Data Locality pattern class diagram") - ## When to Use the Data Locality Pattern in Java This pattern is applicable in scenarios where large datasets are processed and performance is critical. It's particularly useful in: From fe522fd70d050494d197d3c4aa443aedef4aae1a Mon Sep 17 00:00:00 2001 From: ssrijan-007-sys <137605821+ssrijan-007-sys@users.noreply.github.com> Date: Tue, 22 Apr 2025 23:59:58 +0530 Subject: [PATCH 03/19] feat: Implement Actor Model pattern * feat: Implement Actor Model pattern #3232 * feat: Implement Actor Model pattern #3232 * feat: update Actor Model implementation with multi-actor logic #3251 * feat: update Actor Model implementation with multi-actor logic and loose coupling #3251 * test: add unit test for actor model #3251 * test: add test for App.java to increase coverage * docs: add complete README for Actor Model pattern also implemented changes #3251 --- actor-model/README.md | 201 ++++++++++++++++++ .../etc/Actor_Model_UML_Class_Diagram.png | Bin 0 -> 47298 bytes actor-model/etc/actor-model.urm.puml | 35 +++ actor-model/pom.xml | 114 ++++++++++ .../java/com/iluwatar/actormodel/Actor.java | 63 ++++++ .../com/iluwatar/actormodel/ActorSystem.java | 51 +++++ .../java/com/iluwatar/actormodel/App.java | 64 ++++++ .../com/iluwatar/actormodel/ExampleActor.java | 53 +++++ .../iluwatar/actormodel/ExampleActor2.java | 46 ++++ .../java/com/iluwatar/actormodel/Message.java | 35 +++ .../com/iluwatar/actor/ActorModelTest.java | 63 ++++++ pom.xml | 3 + 12 files changed, 728 insertions(+) create mode 100644 actor-model/README.md create mode 100644 actor-model/etc/Actor_Model_UML_Class_Diagram.png create mode 100644 actor-model/etc/actor-model.urm.puml create mode 100644 actor-model/pom.xml create mode 100644 actor-model/src/main/java/com/iluwatar/actormodel/Actor.java create mode 100644 actor-model/src/main/java/com/iluwatar/actormodel/ActorSystem.java create mode 100644 actor-model/src/main/java/com/iluwatar/actormodel/App.java create mode 100644 actor-model/src/main/java/com/iluwatar/actormodel/ExampleActor.java create mode 100644 actor-model/src/main/java/com/iluwatar/actormodel/ExampleActor2.java create mode 100644 actor-model/src/main/java/com/iluwatar/actormodel/Message.java create mode 100644 actor-model/src/test/java/com/iluwatar/actor/ActorModelTest.java diff --git a/actor-model/README.md b/actor-model/README.md new file mode 100644 index 000000000000..be8065ffefef --- /dev/null +++ b/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 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) + diff --git a/actor-model/etc/Actor_Model_UML_Class_Diagram.png b/actor-model/etc/Actor_Model_UML_Class_Diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..a4c34d7a75fdeec17c2665cb7012233805ae7454 GIT binary patch literal 47298 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 GjQTf&f{mL1 literal 0 HcmV?d00001 diff --git a/actor-model/etc/actor-model.urm.puml b/actor-model/etc/actor-model.urm.puml new file mode 100644 index 000000000000..020c1fc735a4 --- /dev/null +++ b/actor-model/etc/actor-model.urm.puml @@ -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 + -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 diff --git a/actor-model/pom.xml b/actor-model/pom.xml new file mode 100644 index 000000000000..76c288829b8d --- /dev/null +++ b/actor-model/pom.xml @@ -0,0 +1,114 @@ + + + + + 4.0.0 + + + com.iluwatar + java-design-patterns + 1.26.0-SNAPSHOT + + + actor-model + Actor Model + + + + + + org.junit + junit-bom + 5.11.0 + pom + import + + + + + + + org.junit.jupiter + junit-jupiter-api + test + + + org.junit.jupiter + junit-jupiter-engine + test + + + org.junit.platform + junit-platform-launcher + test + + + org.slf4j + slf4j-api + + + ch.qos.logback + logback-classic + + + + + + + + org.apache.maven.plugins + maven-assembly-plugin + 3.3.0 + + + jar-with-dependencies + + + + com.iluwatar.actormodel.App + + + + + + make-assembly + package + + single + + + + + + + + + diff --git a/actor-model/src/main/java/com/iluwatar/actormodel/Actor.java b/actor-model/src/main/java/com/iluwatar/actormodel/Actor.java new file mode 100644 index 000000000000..6e2aaccd1937 --- /dev/null +++ b/actor-model/src/main/java/com/iluwatar/actormodel/Actor.java @@ -0,0 +1,63 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.actormodel; + +import java.util.concurrent.BlockingQueue; +import java.util.concurrent.LinkedBlockingQueue; +import lombok.Getter; +import lombok.Setter; + +public abstract class Actor implements Runnable { + + @Setter @Getter private String actorId; + private final BlockingQueue mailbox = new LinkedBlockingQueue<>(); + private volatile boolean active = + true; // always read from main memory and written back to main memory, + + // rather than being cached in a thread's local memory. To make it consistent to all Actors + + public void send(Message message) { + mailbox.add(message); // Add message to queue + } + + public void stop() { + active = false; // Stop the actor loop + } + + @Override + public void run() { + while (active) { + try { + Message message = mailbox.take(); // Wait for a message + onReceive(message); // Process it + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + } + } + + // Child classes must define what to do with a message + protected abstract void onReceive(Message message); +} diff --git a/actor-model/src/main/java/com/iluwatar/actormodel/ActorSystem.java b/actor-model/src/main/java/com/iluwatar/actormodel/ActorSystem.java new file mode 100644 index 000000000000..db7c21cb6088 --- /dev/null +++ b/actor-model/src/main/java/com/iluwatar/actormodel/ActorSystem.java @@ -0,0 +1,51 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.actormodel; + +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.atomic.AtomicInteger; + +public class ActorSystem { + private final ExecutorService executor = Executors.newCachedThreadPool(); + private final ConcurrentHashMap actorRegister = new ConcurrentHashMap<>(); + private final AtomicInteger idCounter = new AtomicInteger(0); + + 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 + } +} diff --git a/actor-model/src/main/java/com/iluwatar/actormodel/App.java b/actor-model/src/main/java/com/iluwatar/actormodel/App.java new file mode 100644 index 000000000000..79fe79e48a6f --- /dev/null +++ b/actor-model/src/main/java/com/iluwatar/actormodel/App.java @@ -0,0 +1,64 @@ +/* + * 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-2022 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. + */ + +/** + * The Actor Model is a design pattern used to handle concurrency in a safe, scalable, and + * message-driven way. + * + *

In the Actor Model: - An **Actor** is an independent unit that has its own state and behavior. + * - Actors **communicate only through messages** — they do not share memory. - An **ActorSystem** + * is responsible for creating, starting, and managing the lifecycle of actors. - Messages are + * delivered asynchronously, and each actor processes them one at a time. + * + *

💡 Key benefits: - No shared memory = no need for complex thread-safety - Easy to scale with + * many actors - Suitable for highly concurrent or distributed systems + * + *

🔍 This example demonstrates the Actor Model: - `ActorSystem` starts two actors: `srijan` and + * `ansh`. - `ExampleActor` and `ExampleActor2` extend the `Actor` class and override the + * `onReceive()` method to handle messages. - Actors communicate using `send()` to pass `Message` + * objects that include the message content and sender's ID. - The actors process messages + * **asynchronously in separate threads**, and we allow a short delay (`Thread.sleep`) to let them + * run. - The system is shut down gracefully at the end. + */ +package com.iluwatar.actormodel; + +public class App { + public static void main(String[] args) throws InterruptedException { + 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 + } +} diff --git a/actor-model/src/main/java/com/iluwatar/actormodel/ExampleActor.java b/actor-model/src/main/java/com/iluwatar/actormodel/ExampleActor.java new file mode 100644 index 000000000000..fd49325f44bd --- /dev/null +++ b/actor-model/src/main/java/com/iluwatar/actormodel/ExampleActor.java @@ -0,0 +1,53 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.actormodel; + +import java.util.ArrayList; +import java.util.List; +import lombok.Getter; +import lombok.extern.slf4j.Slf4j; + +@Slf4j +public class ExampleActor extends Actor { + private final ActorSystem actorSystem; + @Getter private final List receivedMessages = new ArrayList<>(); + + public ExampleActor(ActorSystem actorSystem) { + this.actorSystem = actorSystem; + } + + // Logger log = Logger.getLogger(getClass().getName()); + + @Override + protected void onReceive(Message message) { + LOGGER.info( + "[{}]Received : {} from : [{}]", getActorId(), message.getContent(), message.getSenderId()); + Actor sender = actorSystem.getActorById(message.getSenderId()); // sender actor id + // Reply of the message + if (sender != null && !message.getSenderId().equals(getActorId())) { + sender.send(new Message("I got your message ", getActorId())); + } + } +} diff --git a/actor-model/src/main/java/com/iluwatar/actormodel/ExampleActor2.java b/actor-model/src/main/java/com/iluwatar/actormodel/ExampleActor2.java new file mode 100644 index 000000000000..037f96716558 --- /dev/null +++ b/actor-model/src/main/java/com/iluwatar/actormodel/ExampleActor2.java @@ -0,0 +1,46 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.actormodel; + +import java.util.ArrayList; +import java.util.List; +import lombok.Getter; +import lombok.extern.slf4j.Slf4j; + +@Slf4j +public class ExampleActor2 extends Actor { + private final ActorSystem actorSystem; + @Getter private final List receivedMessages = new ArrayList<>(); + + public ExampleActor2(ActorSystem actorSystem) { + this.actorSystem = actorSystem; + } + + @Override + protected void onReceive(Message message) { + receivedMessages.add(message.getContent()); + LOGGER.info("[{}]Received : {}", getActorId(), message.getContent()); + } +} diff --git a/actor-model/src/main/java/com/iluwatar/actormodel/Message.java b/actor-model/src/main/java/com/iluwatar/actormodel/Message.java new file mode 100644 index 000000000000..03ca6e02cac0 --- /dev/null +++ b/actor-model/src/main/java/com/iluwatar/actormodel/Message.java @@ -0,0 +1,35 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.actormodel; + +import lombok.AllArgsConstructor; +import lombok.Getter; + +@AllArgsConstructor +@Getter +public class Message { + private final String content; + private final String senderId; +} diff --git a/actor-model/src/test/java/com/iluwatar/actor/ActorModelTest.java b/actor-model/src/test/java/com/iluwatar/actor/ActorModelTest.java new file mode 100644 index 000000000000..a4a0dee569ab --- /dev/null +++ b/actor-model/src/test/java/com/iluwatar/actor/ActorModelTest.java @@ -0,0 +1,63 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.actor; + +import static org.junit.jupiter.api.Assertions.*; + +import com.iluwatar.actormodel.ActorSystem; +import com.iluwatar.actormodel.App; +import com.iluwatar.actormodel.ExampleActor; +import com.iluwatar.actormodel.ExampleActor2; +import com.iluwatar.actormodel.Message; +import org.junit.jupiter.api.Test; + +public class ActorModelTest { + @Test + void testMainMethod() throws InterruptedException { + App.main(new String[] {}); + } + + @Test + public void testMessagePassing() throws InterruptedException { + ActorSystem system = new ActorSystem(); + + ExampleActor srijan = new ExampleActor(system); + ExampleActor2 ansh = new ExampleActor2(system); + + system.startActor(srijan); + system.startActor(ansh); + + // Ansh recieves a message from Srijan + ansh.send(new Message("Hello ansh", srijan.getActorId())); + + // Wait briefly to allow async processing + Thread.sleep(200); + + // Check that Srijan received the message + assertTrue( + ansh.getReceivedMessages().contains("Hello ansh"), + "ansh should receive the message from Srijan"); + } +} diff --git a/pom.xml b/pom.xml index 46429c75af7c..bc12b56e9d98 100644 --- a/pom.xml +++ b/pom.xml @@ -71,6 +71,7 @@ Java Design Patterns + abstract-document abstract-factory active-object @@ -243,6 +244,8 @@ virtual-proxy visitor backpressure + actor-model + From e359f1b031cc310318b3656efda1a2c36cb6d436 Mon Sep 17 00:00:00 2001 From: "allcontributors[bot]" <46447321+allcontributors[bot]@users.noreply.github.com> Date: Tue, 22 Apr 2025 21:31:01 +0300 Subject: [PATCH 04/19] docs: add ssrijan-007-sys as a contributor for code (#3263) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> --- .all-contributorsrc | 9 +++++++++ README.md | 3 ++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/.all-contributorsrc b/.all-contributorsrc index b2fef6640890..d403e424c6d6 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -3493,6 +3493,15 @@ "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" + ] } ], "contributorsPerLine": 6, diff --git a/README.md b/README.md index a52d7f3f1fed..45f590cffec3 100644 --- a/README.md +++ b/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](https://img.shields.io/badge/all_contributors-383-orange.svg?style=flat-square)](#contributors-) +[![All Contributors](https://img.shields.io/badge/all_contributors-384-orange.svg?style=flat-square)](#contributors-)
@@ -570,6 +570,7 @@ This project is licensed under the terms of the MIT license. Sanura Hettiarachchi
Sanura Hettiarachchi
💻 Kim Gi Uk
Kim Gi Uk
💻 Suchismita Deb
Suchismita Deb
💻 + ssrijan-007-sys
ssrijan-007-sys
💻 From 55bef7ca39e4a80565a3e9eed890372e663fa919 Mon Sep 17 00:00:00 2001 From: e5LA Date: Tue, 22 Apr 2025 20:44:59 +0200 Subject: [PATCH 05/19] chore: removed duplicated dependency (#3258) --- pom.xml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/pom.xml b/pom.xml index bc12b56e9d98..808b30d38601 100644 --- a/pom.xml +++ b/pom.xml @@ -319,12 +319,6 @@ ${junit.version} test - - org.junit.jupiter - junit-jupiter-params - ${junit.version} - test - org.junit.jupiter junit-jupiter-migrationsupport From e4681e4a7ca3120f86faf63a324b6b085819ae9a Mon Sep 17 00:00:00 2001 From: "allcontributors[bot]" <46447321+allcontributors[bot]@users.noreply.github.com> Date: Tue, 22 Apr 2025 21:45:40 +0300 Subject: [PATCH 06/19] docs: add e5LA as a contributor for code (#3264) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> --- .all-contributorsrc | 9 +++++++++ README.md | 5 ++++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/.all-contributorsrc b/.all-contributorsrc index d403e424c6d6..afa0038a4141 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -3502,6 +3502,15 @@ "contributions": [ "code" ] + }, + { + "login": "e5LA", + "name": "e5LA", + "avatar_url": "https://avatars.githubusercontent.com/u/208197507?v=4", + "profile": "https://github.com/e5LA", + "contributions": [ + "code" + ] } ], "contributorsPerLine": 6, diff --git a/README.md b/README.md index 45f590cffec3..0b9b5b0d90ad 100644 --- a/README.md +++ b/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](https://img.shields.io/badge/all_contributors-384-orange.svg?style=flat-square)](#contributors-) +[![All Contributors](https://img.shields.io/badge/all_contributors-385-orange.svg?style=flat-square)](#contributors-)
@@ -572,6 +572,9 @@ This project is licensed under the terms of the MIT license. Suchismita Deb
Suchismita Deb
💻 ssrijan-007-sys
ssrijan-007-sys
💻 + + e5LA
e5LA
💻 + From 6e20d3221383c1954bb5b4b89c5aeeb051e68f3e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 22 Apr 2025 21:50:26 +0300 Subject: [PATCH 07/19] build(deps): bump org.springframework:spring-web (#3262) Bumps [org.springframework:spring-web](https://github.com/spring-projects/spring-framework) from 7.0.0-M3 to 7.0.0-M4. - [Release notes](https://github.com/spring-projects/spring-framework/releases) - [Commits](https://github.com/spring-projects/spring-framework/compare/v7.0.0-M3...v7.0.0-M4) --- updated-dependencies: - dependency-name: org.springframework:spring-web dependency-version: 7.0.0-M4 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- dynamic-proxy/pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dynamic-proxy/pom.xml b/dynamic-proxy/pom.xml index 236723c52682..586dbc1b6ab4 100644 --- a/dynamic-proxy/pom.xml +++ b/dynamic-proxy/pom.xml @@ -56,7 +56,7 @@ org.springframework spring-web - 7.0.0-M3 + 7.0.0-M4 org.junit.jupiter From ad6bdf802d1b7a890a6801e3064cec586f55f760 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 22 Apr 2025 21:52:25 +0300 Subject: [PATCH 08/19] build(deps): bump org.sonarsource.scanner.maven:sonar-maven-plugin (#3261) Bumps [org.sonarsource.scanner.maven:sonar-maven-plugin](https://github.com/SonarSource/sonar-scanner-maven) from 5.0.0.4389 to 5.1.0.4751. - [Release notes](https://github.com/SonarSource/sonar-scanner-maven/releases) - [Commits](https://github.com/SonarSource/sonar-scanner-maven/compare/5.0.0.4389...5.1.0.4751) --- updated-dependencies: - dependency-name: org.sonarsource.scanner.maven:sonar-maven-plugin dependency-version: 5.1.0.4751 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 808b30d38601..20f468706502 100644 --- a/pom.xml +++ b/pom.xml @@ -63,7 +63,7 @@ 3.14.0 - 5.0.0.4389 + 5.1.0.4751 https://sonarcloud.io iluwatar iluwatar_java-design-patterns From dae93adfeec9632a1400dae7d2098c3e63c09dd8 Mon Sep 17 00:00:00 2001 From: Maziyar Gerami <122622721+maziyar-gerami@users.noreply.github.com> Date: Tue, 22 Apr 2025 22:25:07 +0330 Subject: [PATCH 09/19] translation: Translate selected patterns to persian (#3256) * Persian Translation: Add persian translation to abstract-document * Persian Translation: Add abstract-document.png to abstract-document folder * Persian Translation: Add codes to README.md of abstract-document * Persian Translation: some improvements in abstract-document * Persian Translation: Add refrence links in abstract-document * Persian Translation: add rtl tag in abstract-document * active-object : translate * active-object: improve when to use * active-object: improve when to use * active-object: improve bullets (test) * active-object: improve bullets (test) * active-object: improve bullets (test) * active-object: improve bullets (test) * active-object: improve bullets * active-object: Fix all bullets * -added persian translation of factory pattern * -renamed file * -changed wikipedia definition * -fixed table problem * -fixed problems in bullet alignments * Update README.md -fixed alignment in bullets * Update README.md -changed tags to English --------- Co-authored-by: Seyyed Keivan Shirkoubian --- localization/fa/abstract-document/README.md | 243 ++++++++++++++++++ .../etc/abstract-document.png | Bin 0 -> 96228 bytes localization/fa/active-object/README.md | 220 ++++++++++++++++ .../etc/active-object-sequence-diagram.png | Bin 0 -> 83490 bytes .../active-object/etc/active-object.urm.png | Bin 0 -> 19466 bytes .../active-object/etc/active-object.urm.puml | 25 ++ localization/fa/factory/README.md | 155 +++++++++++ .../factory/etc/factory-sequence-diagram.png | Bin 0 -> 29457 bytes 8 files changed, 643 insertions(+) create mode 100644 localization/fa/abstract-document/README.md create mode 100644 localization/fa/abstract-document/etc/abstract-document.png create mode 100644 localization/fa/active-object/README.md create mode 100644 localization/fa/active-object/etc/active-object-sequence-diagram.png create mode 100644 localization/fa/active-object/etc/active-object.urm.png create mode 100644 localization/fa/active-object/etc/active-object.urm.puml create mode 100644 localization/fa/factory/README.md create mode 100644 localization/fa/factory/etc/factory-sequence-diagram.png diff --git a/localization/fa/abstract-document/README.md b/localization/fa/abstract-document/README.md new file mode 100644 index 000000000000..7097ffc8b4ea --- /dev/null +++ b/localization/fa/abstract-document/README.md @@ -0,0 +1,243 @@ +--- +title: "الگوی Abstract Document در جاوا: ساده‌سازی مدیریت داده با انعطاف‌پذیری" +shortTitle: Abstract Document +description: "الگوی طراحی Abstract Document در جاوا را بررسی کنید. با هدف، توضیح، کاربرد، مزایا و نمونه‌های دنیای واقعی برای پیاده‌سازی ساختارهای داده‌ای پویا و انعطاف‌پذیر آشنا شوید." +category: Structural +language: fa +tag: + - Abstraction + - Decoupling + - Dynamic typing + - Encapsulation + - Extensibility + - Polymorphism +--- + +## هدف الگوی طراحی Abstract Document + +الگوی طراحی Abstract Document در جاوا یک الگوی طراحی ساختاری مهم است که راهی یکپارچه برای مدیریت ساختارهای داده‌ای سلسله‌مراتبی و درخت‌ی فراهم می‌کند، با تعریف یک واسط مشترک برای انواع مختلف اسناد. این الگو ساختار اصلی سند را از فرمت‌های خاص داده جدا می‌کند، که باعث به‌روزرسانی پویا و نگهداری ساده‌تر می‌شود. + +## توضیح دقیق الگوی Abstract Document با نمونه‌های دنیای واقعی + +الگوی طراحی Abstract Document در جاوا امکان مدیریت پویا ویژگی‌های پویا(غیر استاتیک) را فراهم می‌کند. این الگو از مفهوم traits استفاده می‌کند تا ایمنی نوع‌داده (type safety) را فراهم کرده و ویژگی‌های کلاس‌های مختلف را به مجموعه‌ای از واسط‌ها تفکیک کند. + +مثال دنیای واقعی + +> فرض کنید یک سیستم کتابخانه از الگوی Abstract Document در جاوا استفاده می‌کند، جایی که کتاب‌ها می‌توانند فرمت‌ها و ویژگی‌های متنوعی داشته باشند: کتاب‌های فیزیکی، کتاب‌های الکترونیکی، و کتاب‌های صوتی. هر فرمت ویژگی‌های خاص خود را دارد، مانند تعداد صفحات برای کتاب‌های فیزیکی، حجم فایل برای کتاب‌های الکترونیکی، و مدت‌زمان برای کتاب‌های صوتی. الگوی Abstract Document به سیستم کتابخانه اجازه می‌دهد تا این فرمت‌های متنوع را به‌صورت انعطاف‌پذیر مدیریت کند. با استفاده از این الگو، سیستم می‌تواند ویژگی‌ها را به‌صورت پویا ذخیره و بازیابی کند، بدون نیاز به ساختار سفت و سخت برای هر نوع کتاب، و این کار افزودن فرمت‌ها یا ویژگی‌های جدید را در آینده بدون تغییرات عمده در کد آسان می‌سازد. + +به زبان ساده + +> الگوی Abstract Document اجازه می‌دهد ویژگی‌هایی به اشیاء متصل شوند بدون اینکه خود آن اشیاء از آن اطلاع داشته باشند. + +ویکی‌پدیا می‌گوید + +> یک الگوی طراحی ساختاری شی‌ء‌گرا برای سازماندهی اشیاء در کلید-مقدارهایی با تایپ آزاد و ارائه داده‌ها از طریق نمای تایپ است. هدف این الگو دستیابی به انعطاف‌پذیری بالا بین اجزا در یک زبان strongly typed است که در آن بتوان ویژگی‌های جدیدی را به‌صورت پویا به ساختار درختی اشیاء اضافه کرد، بدون از دست دادن پشتیبانی از type safety. این الگو از traits برای جداسازی ویژگی‌های مختلف یک کلاس در اینترفیس‌های متفاوت استفاده می‌کند. + +نمودار کلاس + +![Abstract Document class diagram](./etc/abstract-document.png "Abstract Document class diagram") + +## مثال برنامه‌نویسی از الگوی Abstract Document در جاوا + +فرض کنید یک خودرو داریم که از قطعات مختلفی تشکیل شده است. اما نمی‌دانیم آیا این خودرو خاص واقعاً همه قطعات را دارد یا فقط برخی از آن‌ها. خودروهای ما پویا و بسیار انعطاف‌پذیر هستند. + +بیایید ابتدا کلاس‌های پایه `Document` و `AbstractDocument` را تعریف کنیم. این کلاس‌ها اساساً یک شیء را قادر می‌سازند تا یک نقشه از ویژگی‌ها و هر تعداد شیء فرزند را نگه دارد. + +```java +public interface Document { + + Void put(String key, Object value); + + Object get(String key); + + Stream children(String key, Function, T> constructor); +} + +public abstract class AbstractDocument implements Document { + + private final Map properties; + + protected AbstractDocument(Map properties) { + Objects.requireNonNull(properties, "properties map is required"); + this.properties = properties; + } + + @Override + public Void put(String key, Object value) { + properties.put(key, value); + return null; + } + + @Override + public Object get(String key) { + return properties.get(key); + } + + @Override + public Stream children(String key, Function, T> constructor) { + return Stream.ofNullable(get(key)) + .filter(Objects::nonNull) + .map(el -> (List>) el) + .findAny() + .stream() + .flatMap(Collection::stream) + .map(constructor); + } + + // Other properties and methods... +} +``` +در ادامه، یک enum به نام Property و مجموعه‌ای از واسط‌ها برای type، price، model و parts تعریف می‌کنیم. این کار به ما اجازه می‌دهد یک واسط با ظاهر استاتیک برای کلاس Car ایجاد کنیم. +```java +public enum Property { + + PARTS, TYPE, PRICE, MODEL +} + +public interface HasType extends Document { + + default Optional getType() { + return Optional.ofNullable((String) get(Property.TYPE.toString())); + } +} + +public interface HasPrice extends Document { + + default Optional getPrice() { + return Optional.ofNullable((Number) get(Property.PRICE.toString())); + } +} + +public interface HasModel extends Document { + + default Optional getModel() { + return Optional.ofNullable((String) get(Property.MODEL.toString())); + } +} + +public interface HasParts extends Document { + + default Stream getParts() { + return children(Property.PARTS.toString(), Part::new); + } +} + +public class Part extends AbstractDocument implements HasType, HasModel, HasPrice { + + public Part(Map properties) { + super(properties); + } +} +``` +اکنون آماده‌ایم تا کلاس Car را معرفی کنیم. +```java +public class Car extends AbstractDocument implements HasModel, HasPrice, HasParts { + + public Car(Map properties) { + super(properties); + } +} +``` +و در نهایت، نحوه ساخت و استفاده از Car را در یک مثال کامل می‌بینید. +```java + public static void main(String[] args) { + LOGGER.info("Constructing parts and car"); + + var wheelProperties = Map.of( + Property.TYPE.toString(), "wheel", + Property.MODEL.toString(), "15C", + Property.PRICE.toString(), 100L); + + var doorProperties = Map.of( + Property.TYPE.toString(), "door", + Property.MODEL.toString(), "Lambo", + Property.PRICE.toString(), 300L); + + var carProperties = Map.of( + Property.MODEL.toString(), "300SL", + Property.PRICE.toString(), 10000L, + Property.PARTS.toString(), List.of(wheelProperties, doorProperties)); + + var car = new Car(carProperties); + + LOGGER.info("Here is our car:"); + LOGGER.info("-> model: {}", car.getModel().orElseThrow()); + LOGGER.info("-> price: {}", car.getPrice().orElseThrow()); + LOGGER.info("-> parts: "); + car.getParts().forEach(p -> LOGGER.info("\t{}/{}/{}", + p.getType().orElse(null), + p.getModel().orElse(null), + p.getPrice().orElse(null)) + ); +} +``` +خروجی برنامه: +``` +07:21:57.391 [main] INFO com.iluwatar.abstractdocument.App -- Constructing parts and car +07:21:57.393 [main] INFO com.iluwatar.abstractdocument.App -- Here is our car: +07:21:57.393 [main] INFO com.iluwatar.abstractdocument.App -- -> model: 300SL +07:21:57.394 [main] INFO com.iluwatar.abstractdocument.App -- -> price: 10000 +07:21:57.394 [main] INFO com.iluwatar.abstractdocument.App -- -> parts: +07:21:57.395 [main] INFO com.iluwatar.abstractdocument.App -- wheel/15C/100 +07:21:57.395 [main] INFO com.iluwatar.abstractdocument.App -- door/Lambo/300 +``` + + ### چه زمانی از الگوی Abstract Document در جاوا استفاده کنیم؟ + +الگوی طراحی Abstract Document به‌ویژه در سناریوهایی مفید است که نیاز به مدیریت انواع مختلفی از اسناد در جاوا وجود دارد که برخی ویژگی‌ها یا رفتارهای مشترک دارند، ولی ویژگی‌ها یا رفتارهای خاص خود را نیز دارند. در ادامه چند سناریوی مناسب برای این الگو آورده شده است: + +* سیستم‌های مدیریت محتوا (CMS): ممکن است انواع مختلفی از محتوا مانند مقاله، تصویر، ویدئو و... وجود داشته باشد. هر نوع محتوا ویژگی‌های مشترکی مثل تاریخ ایجاد، نویسنده و تگ‌ها دارد، ولی همچنین ویژگی‌های خاصی مثل ابعاد تصویر یا مدت‌زمان ویدئو. + +* سیستم‌های فایل: اگر یک سیستم فایل طراحی می‌کنید که باید انواع مختلف فایل مانند اسناد، تصاویر، فایل‌های صوتی و دایرکتوری‌ها را مدیریت کند، این الگو می‌تواند راهی یکپارچه برای دسترسی به ویژگی‌هایی مانند اندازه فایل یا تاریخ ایجاد، فراهم کند و در عین حال ویژگی‌های خاص هر نوع فایل را هم مدیریت کند. + +* سیستم‌های تجارت الکترونیک: یک پلتفرم فروش آنلاین ممکن است محصولات مختلفی داشته باشد مثل محصولات فیزیکی، فایل‌های دیجیتال، و اشتراک‌ها. این محصولات ویژگی‌هایی مثل نام، قیمت و توضیح را به اشتراک می‌گذارند، ولی ویژگی‌های خاصی هم دارند مانند وزن حمل برای محصولات فیزیکی یا لینک دانلود برای دیجیتال‌ها. + +* سیستم‌های سوابق پزشکی: در مراقبت سلامت، پرونده بیماران ممکن است داده‌های مختلفی مثل مشخصات فردی، سوابق پزشکی، نتایج آزمایش‌ها و نسخه‌ها را شامل شود. این الگو می‌تواند ویژگی‌های مشترک مثل شماره بیمار یا تاریخ تولد را مدیریت کند و هم‌زمان ویژگی‌های خاصی مثل نتایج آزمایش یا داروهای تجویزی را هم پوشش دهد. + +* مدیریت پیکربندی: هنگام کار با تنظیمات پیکربندی نرم‌افزار، ممکن است انواع مختلفی از عناصر پیکربندی وجود داشته باشد، هر یک با ویژگی‌های خاص خود. این الگو می‌تواند برای مدیریت این عناصر مفید باشد. + +* پلتفرم‌های آموزشی: سیستم‌های آموزشی ممکن است انواع مختلفی از منابع یادگیری داشته باشند مثل محتوای متنی، ویدیوها، آزمون‌ها و تمرین‌ها. ویژگی‌های مشترکی مثل عنوان، نویسنده و تاریخ انتشار وجود دارد، ولی ویژگی‌های خاصی مانند مدت ویدیو یا مهلت تحویل تمرین نیز ممکن است وجود داشته باشد. + +* ابزارهای مدیریت پروژه: در برنامه‌های مدیریت پروژه، ممکن است انواع مختلفی از وظایف مانند آیتم‌های to-do، milestoneها و issueها داشته باشید. این الگو می‌تواند برای مدیریت ویژگی‌های عمومی مانند نام وظیفه و مسئول آن استفاده شود و در عین حال ویژگی‌های خاص مانند تاریخ milestone یا اولویت issue را نیز پوشش دهد. + +* اسناد ساختار ویژگی‌های متنوع و در حال تحول دارند. + +* افزودن ویژگی‌های جدید به‌صورت پویا یک نیاز رایج است. + +* جداسازی دسترسی به داده از فرمت‌های خاص حیاتی است. + +* نگهداری‌پذیری و انعطاف‌پذیری برای کد اهمیت دارد. + +ایده اصلی پشت الگوی Abstract Document فراهم کردن روشی انعطاف‌پذیر و قابل توسعه برای مدیریت انواع مختلف اسناد یا موجودیت‌ها با ویژگی‌های مشترک و خاص است. با تعریف یک واسط مشترک و پیاده‌سازی آن در انواع مختلف اسناد، می‌توان به شیوه‌ای منظم و یکپارچه برای مدیریت ساختارهای پیچیده داده دست یافت. +### مزایا و معایب الگوی Abstract Document +

+مزایا: + +* انعطاف‌پذیری: پشتیبانی از ساختارهای متنوع اسناد و ویژگی‌ها. + +* قابلیت توسعه: افزودن ویژگی‌های جدید بدون شکستن کد موجود. + +* نگهداری‌پذیری: ارتقاء کد تمیز و قابل تطبیق به‌واسطه جداسازی وظایف. + +* قابلیت استفاده مجدد: نمای دید تایپ‌شده باعث استفاده مجدد از کد برای دسترسی به نوع خاصی از ویژگی می‌شود. + +معایب: + +* پیچیدگی: نیاز به تعریف واسط‌ها و نماها، که باعث اضافه شدن سربار پیاده‌سازی می‌شود. + +* کارایی: ممکن است سربار کمی نسبت به دسترسی مستقیم به داده داشته باشد. +
+ +منابع و اعتبارها + +* [Design Patterns: Elements of Reusable Object-Oriented Software](https://amzn.to/3w0pvKI) + +* [Java Design Patterns: A Hands-On Experience with Real-World Examples](https://amzn.to/3yhh525) + +* [Pattern-Oriented Software Architecture Volume 4: A Pattern Language for Distributed Computing (v. 4)] (https://amzn.to/49zRP4R) + +* [Patterns of Enterprise Application Architecture] (https://amzn.to/3WfKBPR) + +* [Abstract Document Pattern (Wikipedia)] (https://en.wikipedia.org/wiki/Abstract_Document_Pattern) + +* [Dealing with Properties (Martin Fowler)] (http://martinfowler.com/apsupp/properties.pdf) diff --git a/localization/fa/abstract-document/etc/abstract-document.png b/localization/fa/abstract-document/etc/abstract-document.png new file mode 100644 index 0000000000000000000000000000000000000000..6bc0b29a4e77680d8eda277c93b97277bbe7193b GIT binary patch literal 96228 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∈MtPMEwTr6eK$ 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 تصور کنید در یک رستوران شلوغ، مشتریان سفارش خود را به گارسون‌ها می‌سپارند. به‌جای آنکه گارسون‌ها خودشان به آشپزخانه بروند و غذا را آماده کنند، سفارش‌ها را روی کاغذهایی می‌نویسند و به یک هماهنگ‌کننده می‌دهند. این هماهنگ‌کننده گروهی از سرآشپزها را مدیریت می‌کند که غذاها را به صورت ناهمگام آماده می‌کنند. هرگاه آشپزی آزاد شود، سفارش بعدی را از صف برمی‌دارد، غذا را آماده می‌کند و پس از آن گارسون را برای سرو غذا مطلع می‌سازد. +> +> در این قیاس، گارسون‌ها نماینده threadهای کلاینت هستند، هماهنگ‌کننده نقش زمان‌بند (scheduler) را ایفا می‌کند، و آشپزها نمایان‌گر اجرای متدها در threadهای جداگانه هستند. این ساختار باعث می‌شود گارسون‌ها بتوانند بدون مسدود شدن توسط فرایند آماده‌سازی غذا، سفارش‌های بیشتری دریافت کنند—درست مانند اینکه الگوی Active Object، فراخوانی متد را از اجرای آن جدا می‌کند تا هم‌زمانی (concurrency) را افزایش دهد. + +به زبان ساده + +> الگوی Active Object، اجرای متد را از فراخوانی آن جدا می‌کند تا در برنامه‌های چندریسمانی (multithreaded)، هم‌زمانی و پاسخ‌گویی بهتری فراهم شود. + +طبق تعریف ویکی‌پدیا + +> الگوی طراحی Active Object اجرای متد را از فراخوانی آن جدا می‌کند، برای شیءهایی که هرکدام thread کنترل مخصوص به خود را دارند. هدف، معرفی هم‌زمانی با استفاده از فراخوانی متد به‌صورت ناهمگام و یک زمان‌بند برای مدیریت درخواست‌ها است. +> +> این الگو شامل شش جزء کلیدی است: +> +> * یک proxy، که رابطی برای کلاینت‌ها با متدهای عمومی فراهم می‌کند. +> * یک interface که درخواست متد برای شیء فعال (active object) را تعریف می‌کند. +> * فهرستی از درخواست‌های معلق از سوی کلاینت‌ها. +> * یک زمان‌بند (scheduler) که تصمیم می‌گیرد کدام درخواست بعدی اجرا شود. +> * پیاده‌سازی متد شیء فعال. +> * یک callback یا متغیر برای اینکه کلاینت نتیجه را دریافت کند. + +نمودار توالی + +![Active Object sequence diagram](./etc/active-object-sequence-diagram.png) + +## مثال برنامه‌نویسی از Active Object در جاوا + +این بخش نحوه عملکرد الگوی Active Object در جاوا را توضیح می‌دهد و کاربرد آن در مدیریت وظایف ناهمگام و کنترل هم‌زمانی را نشان می‌دهد. + +اورک‌ها به دلیل ذات وحشی و غیرقابل مهارشان شناخته می‌شوند. به‌نظر می‌رسد هرکدام thread کنترل مخصوص خود را دارند. برای پیاده‌سازی یک موجود که دارای سازوکار thread مستقل خود باشد و فقط API را در اختیار قرار دهد نه اجرای داخلی را، می‌توان از الگوی Active Object استفاده کرد. + +```java +public abstract class ActiveCreature { + private final Logger logger = LoggerFactory.getLogger(ActiveCreature.class.getName()); + + private BlockingQueue requests; + + private String name; + + private Thread thread; + + public ActiveCreature(String name) { + this.name = name; + this.requests = new LinkedBlockingQueue(); + thread = new Thread(new Runnable() { + @Override + public void run() { + while (true) { + try { + requests.take().run(); + } catch (InterruptedException e) { + logger.error(e.getMessage()); + } + } + } + } + ); + thread.start(); + } + + public void eat() throws InterruptedException { + requests.put(new Runnable() { + @Override + public void run() { + logger.info("{} is eating!", name()); + logger.info("{} has finished eating!", name()); + } + } + ); + } + + public void roam() throws InterruptedException { + requests.put(new Runnable() { + @Override + public void run() { + logger.info("{} has started to roam the wastelands.", name()); + } + } + ); + } + + public String name() { + return this.name; + } +} +``` + +می‌توان دید هر کلاسی که از ActiveCreature ارث‌بری کند، دارای thread کنترل مختص به خود برای فراخوانی و اجرای متدها خواهد بود. + +برای مثال، کلاس Orc: + +```java +public class Orc extends ActiveCreature { + + public Orc(String name) { + super(name); + } +} +``` +اکنون می‌توان چند موجود مانند orc ایجاد کرد، به آن‌ها دستور داد که بخورند و پرسه بزنند، و آن‌ها این دستورات را در thread مختص به خود اجرا می‌کنند: + +```java +public class App implements Runnable { + + private static final Logger logger = LoggerFactory.getLogger(App.class.getName()); + + private static final int NUM_CREATURES = 3; + + public static void main(String[] args) { + var app = new App(); + app.run(); + } + + @Override + public void run() { + List creatures = new ArrayList<>(); + try { + for (int i = 0; i < NUM_CREATURES; i++) { + creatures.add(new Orc(Orc.class.getSimpleName() + i)); + creatures.get(i).eat(); + creatures.get(i).roam(); + } + Thread.sleep(1000); + } catch (InterruptedException e) { + logger.error(e.getMessage()); + Thread.currentThread().interrupt(); + } finally { + for (int i = 0; i < NUM_CREATURES; i++) { + creatures.get(i).kill(0); + } + } + } +} +``` + +خروجی برنامه: + +``` +09:00:02.501 [Thread-0] INFO com.iluwatar.activeobject.ActiveCreature -- Orc0 is eating! +09:00:02.501 [Thread-2] INFO com.iluwatar.activeobject.ActiveCreature -- Orc2 is eating! +09:00:02.501 [Thread-1] INFO com.iluwatar.activeobject.ActiveCreature -- Orc1 is eating! +09:00:02.504 [Thread-0] INFO com.iluwatar.activeobject.ActiveCreature -- Orc0 has finished eating! +09:00:02.504 [Thread-1] INFO com.iluwatar.activeobject.ActiveCreature -- Orc1 has finished eating! +09:00:02.504 [Thread-0] INFO com.iluwatar.activeobject.ActiveCreature -- Orc0 has started to roam in the wastelands. +09:00:02.504 [Thread-2] INFO com.iluwatar.activeobject.ActiveCreature -- Orc2 has finished eating! +09:00:02.504 [Thread-1] INFO com.iluwatar.activeobject.ActiveCreature -- Orc1 has started to roam in the wastelands. +09:00:02.504 [Thread-2] INFO com.iluwatar.activeobject.ActiveCreature -- Orc2 has started to roam in the wastelands. +``` + +چه زمانی از الگوی Active Object در جاوا استفاده کنیم؟ + +از الگوی Active Object در جاوا استفاده کنید زمانی که: +> * نیاز دارید وظایف ناهمگام را بدون مسدود کردن thread اصلی مدیریت کنید تا عملکرد و پاسخ‌گویی بهتری داشته باشید. +> * نیاز به تعامل ناهمگام با منابع خارجی دارید. +> * می‌خواهید پاسخ‌گویی برنامه را افزایش دهید. +> * نیاز به مدیریت وظایف هم‌زمان به‌صورت ماژولار و قابل نگهداری دارید. + +آموزش‌های Java برای الگوی Active Object +> [Android and Java Concurrency: The Active Object Pattern (Douglas Schmidt)]((https://www.youtube.com/watch?v=Cd8t2u5Qmvc)) + +کاربردهای دنیای واقعی الگوی Active Object در جاوا + +> سیستم‌های معاملات بلادرنگ که درخواست‌ها به‌صورت ناهمگام پردازش می‌شوند. +> که در آن وظایف طولانی در پس‌زمینه اجرا می‌شوند بدون آنکه رابط کاربری را متوقف کنند. +> رابط‌های کاربری گرافیکی (GUI) +> برنامه‌نویسی بازی‌ها برای مدیریت به‌روزرسانی‌های هم‌زمان وضعیت بازی یا محاسبات هوش مصنوعی. + +مزایا و ملاحظات الگوی Active Object + +با مزایا و معایب استفاده از الگوی Active Object در جاوا آشنا شوید؛ از جمله بهبود ایمنی threadها و ملاحظات سربار احتمالی (overhead). + +> مزایا: +> +> * پاسخ‌گویی بهتر thread اصلی. +> * محصورسازی مسائل مربوط به هم‌زمانی درون شیءها. +> * بهبود سازمان‌دهی کد و قابلیت نگهداری. +> * فراهم‌سازی ایمنی در برابر شرایط بحرانی (thread safety) و جلوگیری از مشکلات وضعیت مشترک. + +> معایب: +> +> * سربار اضافی به دلیل ارسال پیام و مدیریت threadها. +> * برای تمام سناریوهای هم‌زمانی مناسب نیست. + +الگوهای طراحی مرتبط در جاوا + +> * [Command](https://java-design-patterns.com/patterns/command/): درخواست را به‌عنوان یک شیء کپسوله می‌کند، مشابه روشی که Active Object فراخوانی متد را کپسوله می‌کند. +> * [Promise](https://java-design-patterns.com/patterns/promise/): راهی برای دریافت نتیجه یک فراخوانی متد ناهمگام فراهم می‌کند؛ اغلب همراه با Active Object استفاده می‌شود. +> * [Proxy](https://java-design-patterns.com/patterns/proxy/): الگوی Active Object می‌تواند از proxy برای مدیریت فراخوانی‌های متد به‌صورت ناهمگام استفاده کند. + +منابع و مراجع + +> * [Design Patterns: Elements of Reusable Object Software](https://amzn.to/3HYqrBE) +> * [Concurrent Programming in Java: Design Principles and Patterns](https://amzn.to/498SRVq) +> * [Java Concurrency in Practice](https://amzn.to/4aRMruW) +> * [Learning Concurrent Programming in Scala](https://amzn.to/3UE07nV) +> * [Pattern Languages of Program Design 3](https://amzn.to/3OI1j61) +> * [Pattern-Oriented Software Architecture Volume 2: Patterns for Concurrent and Networked Objects](https://amzn.to/3UgC24V) + diff --git a/localization/fa/active-object/etc/active-object-sequence-diagram.png b/localization/fa/active-object/etc/active-object-sequence-diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..b725d9b07b6d14936f2453c4febe630b92526d10 GIT binary patch literal 83490 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�TxYE36Yk<#Jh(y%^~6xa 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%0ATK8Me7XO|L7n+5a_@btd{)e()=Fo|26^A z|2Dz@Ho^asO@Or*mwfHo^?dPXg1@d<|982?Jt$=P7t?-2{ zA<{yDOrujVnTf;veZj3=!a4+Y}%s#fGHMmnmg z`|E*th^nJ!MUnn9^%EhcYBTkH8+&2Vsz|W~ZR~5*WQ^`Ivc+X(O|7kBKz$27@EAE0 zP5&_>Mb8&Rzr{{p+Xw8zGKL+WM>S=O*$r(K{jPbUVzzEUg!lAYP6BG048lhFCa{VP zsvd#9^df`7VBMD|F!zSk+S#JE_0RneYJRMWdekGKN{OTTBU>8)rl`)|5Td0u%v+w( zp!SnVXb2cf0CgU(K}$DgUjzT2)1V%9vrhlXl0!gGfl1AWC-+APvIM9n#VzAl=Oyzd|LUVE*z*KzD1dD-_5aL94)+`04MgXBBKJ9p5)z|ZqO zCeYFoX!{EIgJ!4rUi41s0Ocm|&pi_n8Ie18Dk5;N^f7?{v8^RF?C#vbZ@c}WbwctD z@7$3}`|wUg*%`c(f}Je0deeEs68AZX)(~3*M`MJ3E6=YdI`bQ`hUVAD8GfJX42I~> z>88VsNTp6vXxqwUzKzhw;+RF{?0E?e&aLy>tD+*m8iC z{cbK>ZeIAUJd}!OJ=XD1=IPjFVd0t z3FchZu*KBT3u@W!Mb;o)T^6NR9r0va-plqLQNDN8l{ta0B|+j22ZeNv`@U!NIrYY| z6pp)XPrY8GRDQ*n+ej`Ag3ifjpX}_l+?>dWgTaC=k!mM{hC=i*iP>u|*XQd-6U7>p z?&r4STSiV|pP3Bds55xPYH8zcG%g4#KfsH4#i&~RoddEkrja6r(D2R~6DAbtG!@ydFdS6q$d>__jr7|P&JpE4l@ zKSvNhRCkNlnouXROesQMp1{jq%G4)VE>wJu%4VSsf`@%?R2Jsy?Nk=RsrXhd5M^rX zYui5tRcj;03sqt=!~%PQ2pPusBNtMsO5`UGH?kr=2I5nVos)BzMwW5>kelgfPzt-wZ(WLT`ZGIk9^dSkbiJ6zw)m{PKzEgljMw%2NYaKLiOV0 zOTR%n4OQ&wDQeB`E{saKp$(Gu3vPQ&d2zV30=oJ1xYLKt*B2IEsS8#GiaE*`(Ne4m zn;jt}MI7NWx|H4B-94c;vZZyuaUAem1prf1Iux!e89!GqYaSnG*NGVDP2w(Nj|EId zJHhm6Lh0m+6TTx}gLIlw^7|C5A3mO_V>K@w?`dH+y=)ulsnUfAL}{b!HR@ECQ!d{D z?mUqdL2s_xr>U-ejb+O4{r2HKwUUm$R5HdE;s4^e_*soUe zSwmO0Arh;2b_|#%xD$g!JN*RPmLl4)0UWbPHZtqPiRT^~)*h}G25~R6chHkuP_tP=n09ED&Jz-$2l)-=!$N3{u<@Sm;J^kSP8k|;h zZ#fr3K+Rpd0i_dv7OiY10YPIa^{wnMi{V(6fi!%DyUWN#5fAb6I}{<`Xm zd}*s?whHg!<|htd=|<;iTK}0%FE5p^(loFI(+~C|h|K5eDn26OvDlJ7g4WxYT7Ade zGbUc!+nHuG-f`KG7#TU-^x&M2uuf(uYQEg%GdkIr_yp``=E<;0O){CoWW$Ey0mOJw z{Ku@p0kdYO1()}$8I9j*1Yx=;9{2uuQLJPh3+e(Nxj*ko?q8yvzC% z{n32_Sn}HC$t(nQ?ws>O#21sPMIww`F<<^!ECHc}P)^*g6ZCSoQH9)F?&$oE>Lzhs zHD|6-19eKxZf)Es54%oT_a0t7l`lBYV=AVk#>)JMcMd|$=dQ^HpyN#_b2m=>S7L|^kO~p{TK6G zkGITc8;lArWyMMiWCYuCm0aUX?444`Y~PVyyV=o2ETi=EoVE91BBXV$t_yEsm2Y)Ca-k66IB z0x_JZR@9;ra4?>5)RHfOJ6%09o_^c)Qg{gP0meU%)o{0Xz)LQu<4KSDg@-2vvMIdV zR$mo{of&(4e_1STgm?jtYHI$WZzfXl8&Yj9PjjyuDL%<@fP)Xx*=X@!(6SwU z-Wn@l8o-pWUD^?2x>z-Zl77L5Q@t?`W!Dvz92m|1KzIzJ4YA_uAb^iwNVUw$iu z#QzH3pnnhdU;gEc{mjn~zi(0|99ASo{hPTBF;N0!6?cnNOB5%cmcDlj33evD0&8%A zUl~@ii7PyD(465zn)6@4k!(+1C~UXgF@pkWi+=QpEY#uacj`2+>w0#*OE%#@Y0UTR zCc?6`GH{dT12n($nLxA=XU5>nU$i?Z=$Lr&Vt4eLP5+P9Gmh^lC6p?lgWFz3$luId zKz>p<9VpTXjGml^bUni>rCn1%9M9SNjUO{n#?M zt@lYri*FjEAHMJe$8Qz!WCQ_e6|ot7UV#3Yr7Q8X@NHS?bfltkU3M4=$z;pT?$h=t zn#n#u^QW&Gy zD^NZ+9>>!-l!PSc7KPF3I4d=Xe1m>in}F)XIc?IVv7|6D$XPjoQ%N(zoXl??F-`br zrBg86u6L#>*8*fAg{hlUvv=E^g|0x0CV|fb+NbkcX3gV!=JoTit7#Rjp1G}(75K`B zaKy9LVHjV|qICklOQpqszQM7e#Gq(&XkZqgS(?!I!Tkf7B^%pfv8{~Jw3u915d1SL zAed`m+V}A{WJ5yUU%9KuK+;Y|Kf$1s9UmLscPO7K5Mspfk1p1&h%g1YpLap>wFHZ1Ws0FhqIR^w^lUBGPYZ| zb?%1c8-*r^>Lfj0t?PVmw&u=O&zC5*ba}MSRbw^FjDSoYOVC4Ik81UU^+D!%ZADq* zLF&!7a<4?;Ir(f%nxRhb%S;Tf;c|TB8%kLhg^0>4y4BTwqL{05!nh{74%U~{L(c2= zh!++#JMg+DVLa-quXB!CVr1+quj`K|0hWdV+fM9$SJQcd&0umzkxNdvKj0Yc<9P4UoAN(tIOx#l(DTJ%-9;oR9Y}QU@Korx(RRm!$|!lOL~<;~8{SDocz%?z zFhE@(a<0!wSjZV-nd3Q`PI>>;am)c{q|0ndShc-B`&L6cI#=Gom+TUV>VgGT?fSd* zfm*2$;;^gD46(-U)p#|9QMQRU18>`OF$FJPe!wAO();hJzZ|F43n3vGwbluj^6anR zf2h8w-A25Z=GDvqq~G6sFb1Qd=|Y&+RwULL8C5<5ec_<@(0DQ2`FcUt#zY zl)2QD8P{0Wnq#PRP_VGHm#Mn2r(Gombxyjo-}TeV)}}g`-34`o*PDM}2IN2Vg-5_{1Se(92o0K&Q<)P$<<+>0^xBwUwC2db?p+S?cpHfvRlt;ey+C)4g}nU zzH$}m-T-*8t7l=*m|c#|Wc_Y^?gw-S%TM>o@aj&g9deZGN0`c-yAO?K;xrQC5fkrg zjAyicA={??l>=1x6qHna#DLi6BQ0;KP;?OMmWrX^GyvLn9y5$n(zVt_bcD@ zH5jU21Kp*nw7nuVA$;%%T3?gxnDnZte(he^q|U9UdTAcY{h-}kvcSG5`*RAyG#B=C zLd<{7+(UM@8;1kz^w;mOgUho_gfxa%L_S=n`DP@R+hx3}Yxd1PVMEN)ZN95UQVSh5 z7H;@`fd@uhm`m(pUp|t7g*ZbgtPr%!5KnpHCZWY?ZS)GG@a(H~K@BephHC0Oz-eU8 zI6KfW+%r5@nqF20oXi)q%+<#Hk&?>mejE0i7g#aX6=$pWG~|)Q)s!;a_Md(^J4Jku zCrW8&Xe1;wh3en&sOm+`F-n0TFAx{_k(`GN-O*L>FONXlZ^RZ--YBS^cuEkD1D)M$fEP9r@2gUzGrR88rWn3jLb3)Gg0_=!XzwRrH)c`_PO4#-dOCXIz(G?8 znTvF-myModXmp5!A?{w-#|$@pdHP&7*Zkwm!H3nv?$h4sb;LbD(-a&Fk~T~#P4h9y zj=h_vxzBtA7yUUQ>!w&(rcm0Mbfm<6JZ!D6!?^hLI1f!PhDGLcJ{^B#>hVg2x@3>! z#O6q#5^c?zdMV>S6wZix;vv;1%e_L`6Z23csOvG}u)>=g9|6cwyX^l!8zNiBRXciauQT%biBs-Fkn@-ePCe zTMmwe`xQ{I)-h6u0o}t~S=V816~qXFlzv|sOe^1JVRRHheu0G?vp}I?z;JcHgQZr- z)!uY|*qNygv)_zvrlyj2{oU@Z*zC?&znNR4d<|(SiNE#l)zJ#eH16d_0S?aCHpO_;Q*&3%;fp;|?g_+Lk_?l`^dPvVZ;8VAK`Rg*lf4Nhsf_WuVDVCDr35{? zSc5at4mFx#b?Q&z+C>-tEhdqZx#%G3h1*51bop*XDvZS61~0#tS*rIs&`rA za%fl$c^l`6;=PD?GgT?OE&?LKBZv5XPubHvQ91=}%7bkP$>A zf}V{DZ*-5=xy@{=UxBYGg#;Y7*o=sI!&Z-u=IXI+;bCfpW`~&skqD1r3|vrF){@dbVaY4m)JQloNGz7-7r?t~E*- z@MQ!{XnEo{i%v!;uNA+Z9TUO3Y)$A1M6Eudh9t-V?r*c&pTwYa!^e8X?=lb3Mh*N*f9T%#oQGfpP^12mepdjL)ZI17Pghnxo^QgZpk zx!^L!2~?~7^_2_C$n@z_y}yUx!_SMJ=SC$LdFc_WqjKx#w^}_pe28;v)pI!!w{dz7 z9<6Klir`(o2lRMLg=DpF1(~aBw%;b5d4rDN+L?XN zTXeZ*3~i08hA=+?HZc$@#U@Q?R62EXR8DqAD(Wz&W`JWj&DmsCS%It78tR5#_ z3f+8;0g@AiV|244Ml5#jrJDIguf^=R;X|vLqZ;L6byyl#YlF9v9&#(weV=wnw`fncMd)c^^^$rJWG}vR0&$Bu2zaW!d^TyJY%=t)iPV+I0 z=BD@?qn$U9^7P{!1~km0F4fK&x#a`+Dx4NQSlSMreiH;EPNE$7!u8e-;jj;i^|l(v z>7^!vZeyMf4orImXbh=GPc=FX+5<1B1QV}u)q2z zu)#2YnR!0eU~ATqiy%MFt}-2dDds{8`2L45^DeT?e&?WC^@bxA2NH#xk1m|N&lwiB zvyl>{5)2{y9N@>6fSbdEBPFQ+dU&2Y(lNT}Un&1Sv3uxg$HLy;fHYp;bg?4rzoh

g&PP^2jM@s~hWjflTfUPfARW^1-y1WsLeqUtgaSZJ^>`iRjg7K))mPw8*L4=Pf#;Vt_##RBRt# z8rD7zRI1lun7`Y+BEj~(_%UxdAB!p9KfRr81~S^z_cjIk ztL?uHFX%(#;m&XhP&nKuh1SZjcEA;=9H4>O!J^V%cZorrNEj!Wva^@>!(5kD%CR5v zw{Y@>f~5NwE$%Wh5Q5g`#ciS>WeX(nw?X>HXZ4tgviVqk@%2EefMV>k{iCmsB1|+T;KbEEPoVLOIZ_mz z>@rYN&~pgjJKwt=neM5ls@S7AcqVE2+x?LPs3WQZGp%%~>2@uW)j?pUvCiB%+UxG7qM znWf5COb+U;C;A0`=U!msWB7<9(UQtL_b^=QSzjIYN9D|IIF=HjGDALI_%c}JN|UV- z2<1KKycp)MB2DCmEJdL68g?0&FHDr&z#%M%)l|3AkYGB^3{f+U`hy2IT#p~S793~f zgdIc(rN-#<+;f(2=?FF&vqfDBWsj&2ZjBROA#5&}bYEUwAb5#(goY|vw7?*f)P(DT zSmv_gs7+`(XK@(MR7Io5&xh-_L+ODiGd>_Gcq5cZyWZm5*dlwP&M(}j_UoXpKM#zLyQ*F;a}z{6RSf#!sNYh z(Q?+Ty!8Q@eXP)l-u|>S>JqPkWQE&kbA#a<@(`96?{K-4mZCS0=5ZUO zj-~-*d0q+4`6Xrumx?$nKF3-D(o#)Mk$LZpsua^V3q1z2CWSGB#gvcBW$)g5&?!VO z4WHw*a4cz&PSYC0%|aPc3dsvQLgJXL7)yFL2NU$_ zfzW~kndr!s6I>hl1HSmB-FvAj`_0GK#E(vTt)LT!pIDp#vG+{T+O?`Zjeg2jk(DW> zP}Xo+r`(%wTwHAl0RX2G#p0=YGR+*6+K$lqzyc)EEzfCp8j zjH#CuthSf`$s4rzcpd#1K;0CBMg4K|_rfwL*V(mU6x-S{`wtIcNwI=pdom7l<;ffC z2dLUuCY^6JX@n{>R?pK#d}qRS9spUA!ipotyn!mqaetXQq$VwXHaBdrjNk;R}Rk*-@8(VKn#7Hht#d z&|X0E$5(GYtGim$VOz-*wvB=Bt4CH~CgMoyxbPH;VKgMj-Z zKi$}PXBFM;3{bsUXbQPHfgVd?P5%+W#eM%fK8{H zi8|;VHHI*dhjAxQ-4rCmp}C>(97{hq13{B?Zb1AH_X&@9IsxhP7Q6M?H~kQQSds(0 zdO|J+*m3B$2VA5Tl=dPW8J!Q5GBO|hb@sF~U$NmGfpF`m?Fs0;c|2>KIN+r zMp*h&(tBTYi9XMA>hL+$6r)<$>DhAD!C`~4Q14@gk0VRN?A15-6Gk9)yf33C$cx7m zjceV0RlLe|cKfJIx|cnMO$JWiAYZ}2@lY^uXOVEfha3Im)l{?tul&$+xBX;2L=|SJ zEw1y?FI)j-GMIl>>|0wyIj;n4@clVMfe3Opa5g&MY9Vr_+Nd|KswevS8{Bqq@^ZZ(TB&co?FcLo!;coUUk7FGW@) zgsr`gnx8@a4g(b__B|YDzsYI+#0dwDJWepdoZ(`C((Q0AJADb-w$-PJBvM-^9z~bkbG>7TVu#cRhuq; zLW*w%OijWzq|qA{NHz~->02@%t6oN>5!t@6j`5(7b&0~?USWiHNYq-+<~rVCq29*( zV4~_jOKY}4+F7Z7_uo-`u?Q~yj>61$&uXjXxwX3FrFd8s7n<7)$5iwz?+%RO;~fU> zw!3VLJF_PFtU<6agj8oZ3(81?E)Si1I^M1)#9og3Dia$&vF^+gwZTIr5iu0Dow!bRB{H*{fd$z<`z+T$)gwipIT-BI8xsP$-3u`UG z9(!2p!&kX?g75%I#(Ii)dm@U2_H**Bd)l3K7cMHFcrDvUQeLsd3{4zk;Ak_*A~Ee} z%%R^WIWWb_zu%>02jrAb!%w2+OO-tO`x;0V$~?;4CO|@9?P2s*9*UMyLk@ZQn$)M` z$fxkbNgSnb)ntynU&1sAfV<* zu|6Z<+TgywkK6ntRtG?+Qog6NvWg}Pqk!%e;hxBpSFb!mE;t^>dYHlK+V7D=C@sv6 z9S;y#jqZ$0e7v4#`BzZZ@xjXWplAS{lHL&#%{`(hW#tgPf(rPzPE+7g}sH_{EbSQV}W$2RputfsG9FgQTc5(KnHRVp=Dqw z3c)48ex@o9k{6Pflh*~P0DDCO-s12uG?d%cw^w!P1y|?&Xu9}BtjnTPK*6-(V`hQi6U&d+3d}D*;AB>ghftpdxAFxByj zG_M#JamY8N8_LsF`6sJHKri(oa{DOs-r9@XUgAKniBgiqsIlEFcK}RNyIkN>YSj%B&xUkj?K_rNQb^jKW{nG$=I#$5rt=^K@W`T9^4yU=$!RY5XSKHr1 zDLo-_0p5CNaebJ-ty?vGi|BF#DkR(?d!r<{!Tak!4OH`&|JuE{LOnBJ^k$nmPTgg* zg2%T*u>fC@q&e|W5%je3xuwln1;HrZ^VV&8RTev90c)2(_c)9@{AjO0sdC9D_h6kH z%bh2|;rE8_Hdb!_{SX+1$;`#i!-EbBJNE*6RP{~zc1q+cMB+&#&pJmo0BZUHQoZru zb_y$oOeo=dLDdAQF5+;~-`qecj1V5aD@7kd46QN{9(IaPh!}6DbU*HJbVhl4VTUfk zV`98AUzB+o`7X0ZjLc7%7nk*OX)eISOE!hReswhInN;<$+IYB796?+%x2Py|*dL|v zzU53dPTMx{b}resrm)Q1b|0%g^V+xYh8R`XdNdn8UkM%XxHX?BU}^!?r(x%nzk{(> z#*l=~lujt9eqOQF)cCCe6#=!^aaB2g6m(s4(CyI?dNuzFktDPXEXl2`2HIXXM@hlM zUnV}YWe7Rj&0hceQT(H}=zjAjZOFFw9y|lTtSe9X@R5MJgTDdcD09pT)a^!vd9FBc zakV-fec}8^@wdVfE+Yt~ifUsZ#-;nKh7+ZaV!|$c8H0NofY)g8NR%qbn^D8@F$!!t zK-^S_BDxKI(_M^}YXR?-e^NFM^?%vL49gLHPub z&0yId2deH(^6Kfmt_mk1`6oo4z;bDuF8_}G1l0_UjJ*Hg!=G_-#?Ex^jfy<9zbBUW zlBp740x*51{q=s}qJ?=>$PwuCF185fb~UuOHTs73beh|!;9_W1&Z34dj_}jRay@Bf zRtk_OZB^y{XBBOO2t^OIw?vYuYzy-Sk4JJ%9*Jgtp9f$du$ap)XJi)Yat~ir^2s4Q zQ3Gfi2B;YNA{2Xo2d^~hC7!Og%VUoQ(#YPZ7w_HG1Tg-24gu2Y=;-LoP{Y|8%N}Wb zYP{=Mg!ALDNrPnm1g6Hg!5AkRDq1^M25J#OS+hc|j$zk$e%Q?lb2>@CX9Tqhc)XX1Tw`Y#mF7Or4K$iK zCg|P1*|FuC7S_A2T2#}Av-=2*}+)|jk{W0iIqj2~Dd53O2_wsKalaopRh z^AxqkAup>ph1Peac9;cgyC za@+(F&c0bqcpPrfHE?3^;ICrZ6Rifjw;A5^k>?w4F{FL){^g(ZIhM(G0fR&mshDH9 zmf944=uI8fc{m7S0xCQ#7&t5Orwd8Z8ScOQ&=i|4Ito{Vto+7{ z7_wEu{iB7vz(!+TAOK4nH&1t8S&LVmUH%_Duo!KJK>bmN~>6!ixEPl(QEw_ z`3CKR+?K9kR|mZ_Upn`RZH?UFSS9Aj4&4g)PO@(oPeN?&-%FS0Nxp!~R5W zmEI=-ZpY)CMjJy`g?*c(w+NaGqNMfuC{rAs?TPBW+LW)QksEUE7l-%Lt!X>|=v%04 zn-=!ac3o8|%;7`*7+h_k*^cBtKlsoD;|7dKQcKsiAXMTv3@A>}>NZ2Kwa$Rz6)R9B z%E|S*FslYgDMMb3kUXh)E_Qe4Q#_Y2^6}VuJHj!JKKH9LlW`8sVN(`(95su4)l;WE z*%MGL0K1KkqqX_!BitFv!$f?kPx9s`@vSqr>)PZ_N7V z1P(?I-R;ghgdGjn7YO?_kY+m^Ca@zH*no2O`A2SU$&gy3$-wb?hfK=|2Fm!>3*v8F z7D%fpwhtw^^xg{ScShNWzeSLZYRx;&#-nfSz0+MgT?C!3FLP1UE;T@i0|J|eh?rr$ zIq|ATLVmwocWO_`kJ4202q>sF#|D-AlOtMM+ZUk8ii?R0)& z#SYyaGV9aLYv$N(+HuOu92LwLJv`zSJXbss?_H% zJ6ZTO2b|>tEz=`Z%b2Gw!0r`!+Fl+4<9k3I5~19}tO=Fmqe7>q%#^wp5VGoa+N|5} zYotKEby9NJfzAQ88+Nt}vJ^;jpd8^LU6hS0DXhw>L65j-c`5~J z5sS;~?-bPeP4`Cz*Ra1_9QeOnoPkFGozb1sFf@zgYv&(#Ep;Co_s@KR{Kxy&&_T~= zUjf3cVgqaxdJ&YVU*v|7)2F*(lk%x-U{T3!VfX`9InuqZb6;s9OtOzv6lg$q3r!X>Bar5mQo8J z04Dqfe~QEgno_wJO2#d)+RZ#0U6v7L4qM7Gy{tvFVHA^Ux})PpN!)U(X*aNV>&s)r z%Z`vV3*`XN!h(mBQh^HM@$sguJ0_}eFRp;S$-_PUQE&6L>wbis`CKS>Vz_TR12AQA ze}H-b;RcbaD2_;(yZ-z#V7u2;d)B+ZI_GjYA|wzF>e7_yE-C&HQ)C1%;ZU0eN`Z`{ zzc^|l?AYzrLauF@g|6#9mNpK2UMz9m0gljOa85O8iak(EaqN#lK`Gf(=@yymm6-ai zA8WEkX`Z};kdIbIfdr6mKL&V}Jm|HRei$2J^i-e#ZovtN0_P7{`B$`IXEBcAMNh3V zyiI^~Sy+`Kyk;gU3owEr{yy)hLf)OrL}=}Jqc;LqS@Iym0Au)RcXyDvD-g^)m2gxY zM`hFs98wN2UI;mEdra5AL6JV!hd%vx?j2BMgTS|$I-6+aQf*b>Vu<4A^dU8)(%Rju zN?)wW9^h^Z{dkdXF}3vao)kzRqsNC#wOnukAQy^RO4;2qFxbneu%0;rRu+r{f8aNI zm9gJRqjfc!B_Y7bqRGL|bVy!dOG(?1flTZ@gi(BmWA#uGP%c!=fs(UVyE#=VBusvd zg+CpB0Iai(CDbo+|IdDofB2aAkL5lV{RNnuHV2rX9NLr;| zkqTs6XOnPZJ^Ck}D2Ei+##jFX+?nsis!i7;UC(60j^g4Hm*#aZC0jboa$w4P( z0D#F9_7ucMu7jU7I%>C0f2J!xbPJ+gJ5D9@WMvC`Uqwf=%jVc12;if=4H(}m2#fjB zA&Xc!*2_NTDIOR6Pc0^(o1jr+a~T66hkbGjmvRFq-0xzNj(~od>BG3auA$dQ%^p(O z?}84m%%Fm9<0_oWAtWs00O)C=F54m)vWi2@-`SGvAkccZ&+xx-E_TzQHl{`MVqVJ! zV1qwUSKR|YKlIyuI^w(|k@H|}P-s!9L>=lG@-J$I@x7aMuSH0uCyu2cH|2y`ex^Wr z?+pNakOOc1?r}yA;RLuW3A-lyf}42HdgtQoJ~m=}$Hst;G#Yj@+g_bvUGv|gf{f*t zCI;xQ^~O)??pCD%6~Vc?YY(G!{>P?T`>;Hc>SEtJwJo(qob~#!n8*R&sen&(;=+MY zcCS)I4dX)pk(~bCg7~$|ZQ2K%0~7)REgJd~f%{8VXm&QKH;kk8P%T~7%0uxKHGYR?U~}6khx7;glV8Wc9r{E z^do?=qzbBDBHfxOS@SX&LZ}Z4fV)H%&u^}|XKfZF;U|11wfI08@~>@@Ccw-*`M|i( z34?HdHV**#Nzt;2caIp|2+7V=g-5o28?SjX=ZG^Lzir`Rb-!Slns71xRdretHX-JU zX4Tu;MaHp3c^ci9fO94y0+5B~Qa#?UcwmY9#6!l23C67tUQMp!D#iCkE1Fs-E^kpA zdGgRf@$;@Ifj1aU*c@r#K-xXxMEof%FA z_?OpZ1Cxh_bi#w;B(Z%*2i@No+s5jDRe9V*aiORxe-x*@c+XXc`gJbykZxsqvc+WZ zE~o5VL0^NV&YFGmT#smku~5dD@2DyhqL%3`8TZ569>#hIXMd-j}-MJ9#)BVlkfa4 zk^!~|uGbOA&U;O#M|r;=k&xD+crE8mq!+E*h_-&cPjG1Z4s#*k6ea+_YfW--6?}l# zw^MC4y7-K*_wH3zt0w^Jyh|8{M=X|r-wi`v%}n0>4iSib%@?at8@4ID-dlpFjtEpr zXSjlkleg>$oN}DTYn;+e*}%`NJBOPtb!?FxMq@}ge_a#3+@B3z#`#sc{0r9!DQ22G zJ9k^hqm5tKHDG1!Il;wSY$=SZ>MVJJ%(Pj)yo|8ZCj`HYW41RXyjHs&cbwxIdj(*a zwIO=%^rqR#3LX=f!$L{eR}jaac$v{$^`H~09Bkk!zt@&Rg4r@&f!nWe%U?BEvSDiO zwGb7{-HeJ!ksKmw@#ky)5xow>73XMH^R#27u0+qnxrFM*xwz9H5N1*OodayK3YZFJ zNuV(75_Q_EQYRs>x1I(%ich%L<6U3{WSikO`+)dOOSnL#8*PueXxN%-q%(UPGWy z)rBdl$d4@9e!bob4h;?*ifnZ3S2H_u+G1a-S-2&Born)MnvKpDcHAMX#Jsg@*`y`= zJ_Fd1>ik{VRa3@I;MT0uhIK$p-mh zJXt8HQEV|)Zj}(XH+w2#HgiNi?lXFR;u2YtTBL{OIs^$tq1E+Icnl>LU*k{fOklS| zhjds^;FxE5d6zoqw{m0f#kbxSNZ{ATb)4H!tAU-c-6my&6cAa1vK3nX@0c5{mh7SR zGD)yPqBRZzB>kUk@Rs(4j(*fG_=>K&b-?;YV`@M z!+2?fTN6XHeYy6Hgr!sT_n){o;JhPZD*BpviI~5gMHpMSXqa(IR@Hi@)>MG_G0i{z z_kP~FH|Kqsd}E?l&XVbO=zg+Hg~x6mAzgRW?+@Q5&@Mo}`|ftY|92*A3M4+|w*i77 z)M@bhz2hvPMj8K~8YT9#3IL(31Mq)0Sh(W+gWF7e@Vmml1x%h}GN3z_JvT5Ia9!$e zZvF2Uf$QaeQ>kDLxcHavP~dt`1oaM8@6J@qxbfpI`X}~7w(T9_<%!1qr79VuDQo>q zCk9{dy=4Gm!dOKg;xlmA_87&Fn*1NG7Y3ixaz24nd@~bp71`!h2*z!o)__y-)kNG@ zoN#u-tiQ@0s@nwb60y?DkQYmz0vP1wVa;b3hMjkEU2HU61GOWSc6ju&9q}Mu`??Nb zm~{N7zh-JIN3UG&hn;tjFq-pD)#FZbZ<|k+G6C0xrYc^|+-5jTp-#WB%09%}?Bpz! z&#oLy(nNN+jrck>dgC+$u3$@vyFn#OB&5XU5cAqPNGyP#cwfu%JI$&bzfFXfOI5DT zBN~AQjT~Q(*~k7=>rlSfX|FUQrQdq`t6u33)msxV8F_ zfpnFKIZmPX7^p9PG!U5Zl59QcenK@TFjVP1kRm8#`T$`^wmroSNi7yN|5Oi9qmAzu z1U2}b!FZ{p{u+RX3!+!?%70?S%#((!?!e`^R$5d`?a;qFth>uYFs##*2TKRWlaKpUuo~Q9^c!*Q2Io%>*Bp ze_@RCBGCppEf$XAc~Y1W=eMM+6Z3JVGvBTkYZc?pY9)zJA5csn^9-dPpaOs_`RgC(%MB9%eWN6M*U4>+TIes zBF)MLt~1gjCQxcJSimHLkO2rSv(|7lvm#_brOu^|-nsCi7rNEu*VQAn*X7!+KI>=k zKT11SwEcRnQOw`!v*?1K?l&B7+LsoucWUlBZlCOpYX}wGbKH}SV>e>m|Br|m0Sion zIo0+hFh2L4`;5GqvGA)i7%3Ak6SoyoBtsO#@V3OqUj*Yb>R~e*&8=`h(~rJr@aGEG zTjWBY3Z&vQ=8c=KjY)yzOi%g?8ddGvUmOmSU?y`zOk~zuc67L;afbUQJPT{o326$QAV$>INOlqtMIc`&V zJ|#6@t~lXE^GkRH3xK(ckDK`0TWG>hEZ?x%{1&di*h(y{&N-~HO3Acx*qKGsK&d98 zNN=%ubD7;4PTib}Mb`!S+7Re-aUA0f^ZSN^R+k$!$x6WX;lyZJjHW9yJPQo*wA4}a zL0wPSmmB13R{NME4ajfyON=&JBv7N9>bK>#L5e-7j?#)xl;xEN6s3k21;F@N+i-C& zR@Rqpg4Dl@0W!1OlDJ!&MWb^2mR5L0U)m5ZmA zyjBoQ3Ob>=`7*5Hz1S=sB2nqI_xy&xwRt=bpmga21ZZ=I)+MD~6+{vY4Y zG8Kr8b{TV}j&Ca}>G)SNw*%$E(7EqVNf>Hk?utQTq;xl*hWOwy;HpKEt!SXPefjUs zm%jrP5`0#^kvrre)EBHV5?c2eE%Znq_WnBtaC~9TuD0JP!*h~yp*MU ziKh$u+4SFNUZxb89EH%uBc)|X7BNl^<&N`Bei%*lk2!j+E=aR1#BY#LS8gH*#z zoxUqmfiWGnk%Xd^=zk-5eGn&`bn(BP|C1;Duc(xXl!&y(n4B&L_93kR_#|H;tMVcQ zw3_)!UXMnmTrQRHG3#x3!GU+Y47ecV?XFii+Drr9XeBkoa{{opL?Hr$sFt(m;xc>~ zCl$88-(5^vVF%sDe?VL7dx_8Kba_z~z1~Fujh@?z6vK9d4hm@2Ov*1=fLkrgAc7}P z--7~QH@xiZd|jb^b4^gdG2t7}aOCQP@f%ysnyNka=lZYzZ);y~OX7dCxPNi^``=gV z7K2yi?mT#XhW^eabE4M8@9&d5W-ctm11Tm$W$oVE<-F}?ydTrNGhzOPM=n**&WKN) z_@Zb#gC(e3zNlrJeoo_S)*J_AXm>1Cen&ma$3t-buGiJwvTWRy{_*a}i z^x7zQ*)@|s=Ht2g{AGC`p56rxNA=6=&%99K3F`a-8y2NqR~yW4FdfZm*!kpqz16-$ z@UB0|GQa(4JxJaCk1k3(&VdTlpTGij`@53YH-Vk~-ta~K^L*YXZJ4%uuJjw@sB2Z0 z**x4%z~wQZoK;=;D0XJl9$PW{*S8*Rm7ZueA%N*g#B|_-Rn|wHB?WW8-=D7qT=f@n z+3&Y3XwhmvaA)@>ZeS7s4%uytK9<^bJX&pG?ghKJ>?rAu=mweXPv>09YpggV8S@-8 zq75vbelUM;03NC0CS|&6^|H5(wR8FoAE|Hz?c9)MTqZdAP?Vd80VMG@UEj7(X?jnt zK5P43HPiUr_e(>Z4T?EM6x44NeJk1EV6%|rI%IKZEO7H|XsqOm_S}n$Cce2_Z57vI zx}pDa;S8zw$9gAUDf{qXEpX0CqI^aRaGNHm-FeZ&gzb9c$=5Ff7tae}%hy#u0-3B6 zRFZ0bonZfQ!3Jpgz+rXPy+fElQ!Y^@#<7s2(+!etV|P^Vx>EPoQPXD6(iqEy!5)r9 zMOq#{JDMH|2(5+0;@qzvZx{XR-u^p&!Hb<04O9I0XuseVvGU-FGdnOlOX6JX^%md+ zi@yDz3ICW_Il?c@DPTRSs1gMkQtK91f3u#)es___1qDl>o`#ibs(Y6#W9NCH^Zj1+ zu2iYM1(plhfa=8{>R*efq~EypaGhh(8potJh8%W3Q`Sw)p!!4Muu}?*S3qgUqp_kvPC@R|Y>*5AypaSOW z`s!}_bJU2!N` zTzdImbYtS5_9JgO%UT44Y9IVMTH5nk^7>cs`T|Q<;L6sIk0018*J*s=OjJiP!n*7X z#0b#35;+(2vlkYvkP*XiECWy~ETX6U&5ey&vjm(x3Leb7X%^?ip}26e>SNoI7XfVI z@^&>lcq9xQ*7gWEby%+lZduI!;p6^zD|g@734JXBNp2fH%yc_;8qD?sv%6U(FHID1 hI#a+uU-Q#{hX*>rZ`MB01D@Z-;OXk;vd$@?2>{}{dP@KR literal 0 HcmV?d00001 diff --git a/localization/fa/active-object/etc/active-object.urm.puml b/localization/fa/active-object/etc/active-object.urm.puml new file mode 100644 index 000000000000..3fc3c8e1e921 --- /dev/null +++ b/localization/fa/active-object/etc/active-object.urm.puml @@ -0,0 +1,25 @@ +@startuml +package com.iluwatar.activeobject { + abstract class ActiveCreature { + - logger : Logger + - name : String + - requests : BlockingQueue + - thread : Thread + + ActiveCreature(name : String) + + eat() + + name() : String + + roam() + } + class App { + - creatures : Integer + - logger : Logger + + App() + + main(args : String[]) {static} + + run() + } + class Orc { + + Orc(name : String) + } +} +Orc --|> ActiveCreature +@enduml \ No newline at end of file diff --git a/localization/fa/factory/README.md b/localization/fa/factory/README.md new file mode 100644 index 000000000000..db41813464e3 --- /dev/null +++ b/localization/fa/factory/README.md @@ -0,0 +1,155 @@ +--- +title: "الگوی factory در جاوا: ساده‌سازی ایجاد اشیاء" +shortTitle: factory +description: "الگوی طراحی factory در جاوا را با مثال‌ها و توضیحات دقیق بیاموزید. یاد بگیرید چگونه با استفاده از الگوی factory کدی انعطاف‌پذیر و مقیاس‌پذیر ایجاد کنید. مناسب برای توسعه‌دهندگانی که به دنبال بهبود مهارت‌های طراحی شیءگرا هستند." +category: structural +language: fa +tag: + - Abstraction + - Encapsulation + - Gang of Four + - Instantiation + - Polymorphism +--- + +## هدف از الگوی طراحی factory + +الگوی طراحی factory در جاوا یک الگوی ساختاری است که یک رابط برای ایجاد یک شیء تعریف می‌کند اما به زیرکلاس‌ها اجازه می‌دهد نوع اشیائی را که ایجاد خواهند شد تغییر دهند. این الگو انعطاف‌پذیری و مقیاس‌پذیری را در کد شما ترویج می‌دهد. + +## توضیح دقیق الگوی factory با مثال‌های دنیای واقعی + +### مثال دنیای واقعی + +> تصور کنید در یک نانوایی انواع مختلف کیک‌ها با استفاده از الگوی طراحی factory ساخته می‌شوند. `CakeFactory` فرآیند ایجاد را مدیریت می‌کند و امکان افزودن آسان انواع جدید کیک‌ها را بدون تغییر در فرآیند اصلی فراهم می‌کند. `CakeFactory` می‌تواند انواع مختلفی از کیک‌ها مانند کیک شکلاتی، کیک وانیلی و کیک توت‌فرنگی تولید کند. به جای اینکه کارکنان نانوایی به صورت دستی مواد اولیه را انتخاب کنند و دستورالعمل‌های خاصی را برای هر نوع کیک دنبال کنند، از `CakeFactory` برای مدیریت فرآیند استفاده می‌کنند. مشتری فقط نوع کیک را درخواست می‌کند و `CakeFactory` مواد اولیه و دستورالعمل مناسب را تعیین کرده و نوع خاصی از کیک را ایجاد می‌کند. این تنظیم به نانوایی اجازه می‌دهد تا انواع جدید کیک‌ها را به راحتی اضافه کند بدون اینکه فرآیند اصلی تغییر کند، که این امر انعطاف‌پذیری و مقیاس‌پذیری را ترویج می‌دهد. + +### تعریف ویکی‌پدیا + +> الگوی factory یک شیء برای ایجاد اشیاء دیگر است – به طور رسمی، factory یک تابع یا متدی است که اشیاء با نمونه‌ها یا کلاس‌های مختلف را بازمی‌گرداند. + +### نمودار توالی + +![نمودار توالی factory](./etc/factory-sequence-diagram.png) + +## مثال برنامه‌نویسی از الگوی factory در جاوا + +تصور کنید یک کیمیاگر قصد دارد سکه‌هایی تولید کند. کیمیاگر باید بتواند هم سکه‌های طلا و هم سکه‌های مسی ایجاد کند و تغییر بین آن‌ها باید بدون تغییر در کد موجود امکان‌پذیر باشد. الگوی factory این امکان را فراهم می‌کند با ارائه یک متد ایجاد استاتیک که می‌توان آن را با پارامترهای مرتبط فراخوانی کرد. + +در جاوا، می‌توانید الگوی factory را با تعریف یک رابط `Coin` و پیاده‌سازی‌های آن `GoldCoin` و `CopperCoin` پیاده‌سازی کنید. کلاس `CoinFactory` یک متد استاتیک `getCoin` ارائه می‌دهد تا اشیاء سکه را بر اساس نوع ایجاد کند. + +```java +public interface Coin { + String getDescription(); +} +``` + +```java +public class GoldCoin implements Coin { + + static final String DESCRIPTION = "This is a gold coin."; + + @Override + public String getDescription() { + return DESCRIPTION; + } +} +``` + +```java +public class CopperCoin implements Coin { + + static final String DESCRIPTION = "This is a copper coin."; + + @Override + public String getDescription() { + return DESCRIPTION; + } +} +``` + +کد زیر انواع سکه‌هایی که پشتیبانی می‌شوند (`GoldCoin` و `CopperCoin`) را نشان می‌دهد. + +```java +@RequiredArgsConstructor +@Getter +public enum CoinType { + + COPPER(CopperCoin::new), + GOLD(GoldCoin::new); + + private final Supplier constructor; +} +``` + +سپس متد استاتیک `getCoin` برای ایجاد اشیاء سکه در کلاس factory `CoinFactory` کپسوله شده است. + +```java +public class CoinFactory { + + public static Coin getCoin(CoinType type) { + return type.getConstructor().get(); + } +} +``` + +اکنون، در کد کلاینت، می‌توانیم انواع مختلفی از سکه‌ها را با استفاده از کلاس factory تولید کنیم. + +```java +public static void main(String[] args) { + LOGGER.info("The alchemist begins his work."); + var coin1 = CoinFactory.getCoin(CoinType.COPPER); + var coin2 = CoinFactory.getCoin(CoinType.GOLD); + LOGGER.info(coin1.getDescription()); + LOGGER.info(coin2.getDescription()); +} +``` + +خروجی برنامه: + +``` +06:19:53.530 [main] INFO com.iluwatar.factory.App -- The alchemist begins his work. +06:19:53.533 [main] INFO com.iluwatar.factory.App -- This is a copper coin. +06:19:53.533 [main] INFO com.iluwatar.factory.App -- This is a gold coin. +``` + +## زمان استفاده از الگوی factory در جاوا + +* از الگوی طراحی factory در جاوا زمانی استفاده کنید که کلاس از قبل نوع دقیق و وابستگی‌های اشیائی که نیاز به ایجاد آن دارد را نمی‌داند. +* زمانی که یک متد یکی از چندین کلاس ممکن که یک کلاس والد مشترک دارند را بازمی‌گرداند و می‌خواهد منطق انتخاب شیء را کپسوله کند. +* این الگو معمولاً هنگام طراحی فریم‌ورک‌ها یا کتابخانه‌ها برای ارائه بهترین انعطاف‌پذیری و جداسازی از انواع کلاس‌های خاص استفاده می‌شود. + +## کاربردهای دنیای واقعی الگوی factory در جاوا + +> * [java.util.Calendar#getInstance()](https://docs.oracle.com/javase/8/docs/api/java/util/Calendar.html#getInstance--) +> * [java.util.ResourceBundle#getBundle()](https://docs.oracle.com/javase/8/docs/api/java/util/ResourceBundle.html#getBundle-java.lang.String-) +> * [java.text.NumberFormat#getInstance()](https://docs.oracle.com/javase/8/docs/api/java/text/NumberFormat.html#getInstance--) +> * [java.nio.charset.Charset#forName()](https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html#forName-java.lang.String-) +> * این مورد [java.net.URLStreamHandlerFactory#createURLStreamHandler(String)](https://docs.oracle.com/javase/8/docs/api/java/net/URLStreamHandlerFactory.html) اشیاء singleton مختلف را بر اساس یک پروتکل بازمی‌گرداند +> * [java.util.EnumSet#of()](https://docs.oracle.com/javase/8/docs/api/java/util/EnumSet.html#of(E)) +> * [javax.xml.bind.JAXBContext#createMarshaller()](https://docs.oracle.com/javase/8/docs/api/javax/xml/bind/JAXBContext.html#createMarshaller--) و متدهای مشابه دیگر. +> +> * کتابخانه‌ی JavaFX از الگوهای factory برای ایجاد کنترل‌های مختلف رابط کاربری متناسب با نیازهای محیط کاربر استفاده می‌کند. + +## مزایا و معایب الگوی factory + +### مزایا: + +> * پیاده‌سازی الگوی factory در برنامه جاوای شما، وابستگی بین پیاده‌سازی و کلاس‌هایی که استفاده می‌کند را کاهش می‌دهد. +> * از [اصل Open/Closed](https://java-design-patterns.com/principles/#open-closed-principle) پشتیبانی می‌کند، زیرا سیستم می‌تواند انواع جدیدی را بدون تغییر کد موجود معرفی کند. + +### معایب: + +> * کد می‌تواند به دلیل معرفی چندین کلاس اضافی پیچیده‌تر شود. +> * استفاده بیش از حد می‌تواند کد را کمتر خوانا کند اگر پیچیدگی ایجاد اشیاء کم یا غیرضروری باشد. + +## الگوهای طراحی مرتبط با جاوا + +> * الگوی [Abstract Factory](https://java-design-patterns.com/patterns/abstract-factory/): می‌توان آن را نوعی factory در نظر گرفت که با گروهی از محصولات کار می‌کند. +> * الگوی [Singleton](https://java-design-patterns.com/patterns/singleton/): اغلب همراه با factory استفاده می‌شود تا اطمینان حاصل شود که یک کلاس تنها یک نمونه دارد. +> * الگوی [Builder](https://java-design-patterns.com/patterns/builder/): ساخت یک شیء پیچیده را از نمایش آن جدا می‌کند، مشابه نحوه‌ای که factoryها مدیریت نمونه‌سازی را انجام می‌دهند. +> * الگوی [Factory Kit](https://java-design-patterns.com/patterns/factory-kit/): یک factory از محتوای غیرقابل تغییر با رابط‌های builder و factory جداگانه است. + +## منابع و اعتبارات + +* [Design Patterns: Elements of Reusable Object-Oriented Software](https://amzn.to/3w0Rk5y) +* [Effective Java](https://amzn.to/4cGk2Jz) +* [Head First Design Patterns: Building Extensible and Maintainable Object-Oriented Software](https://amzn.to/3UpTLrG) diff --git a/localization/fa/factory/etc/factory-sequence-diagram.png b/localization/fa/factory/etc/factory-sequence-diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..260bea92f24736656584c4714398e47e2dbb61c2 GIT binary patch literal 29457 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

a2pE@iOs1kiD%Yk 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�=nt6c0Wf(41WEl3CS?Fjz#jnoc5nbbUbAIJDWn@L{tc!TV#TiY z-jc$6dR|Wz90hHqI3IG5A literal 0 HcmV?d00001 From f8f33f586a605e1685ea24cb2631acf961d1a182 Mon Sep 17 00:00:00 2001 From: "allcontributors[bot]" <46447321+allcontributors[bot]@users.noreply.github.com> Date: Tue, 22 Apr 2025 21:55:51 +0300 Subject: [PATCH 10/19] docs: add maziyar-gerami as a contributor for translation (#3265) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> --- .all-contributorsrc | 9 +++++++++ README.md | 3 ++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/.all-contributorsrc b/.all-contributorsrc index afa0038a4141..9509bc095ae7 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -3511,6 +3511,15 @@ "contributions": [ "code" ] + }, + { + "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" + ] } ], "contributorsPerLine": 6, diff --git a/README.md b/README.md index 0b9b5b0d90ad..c2c3a5c7af10 100644 --- a/README.md +++ b/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](https://img.shields.io/badge/all_contributors-385-orange.svg?style=flat-square)](#contributors-) +[![All Contributors](https://img.shields.io/badge/all_contributors-386-orange.svg?style=flat-square)](#contributors-)
@@ -574,6 +574,7 @@ This project is licensed under the terms of the MIT license. e5LA
e5LA
💻 + Maziyar Gerami
Maziyar Gerami
🌍 From 8a64f4c5743f41a2b4fc8d28ecf1e9f13acb5a3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= Date: Sat, 26 Apr 2025 23:14:07 +0300 Subject: [PATCH 11/19] docs: update dependency injection --- dependency-injection/README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/dependency-injection/README.md b/dependency-injection/README.md index c3fc2c15a977..c9a2848bdfde 100644 --- a/dependency-injection/README.md +++ b/dependency-injection/README.md @@ -118,10 +118,6 @@ The program output: 11:54:05.308 [main] INFO com.iluwatar.dependency.injection.Tobacco -- GuiceWizard smoking RivendellTobacco ``` -## Detailed Explanation of Dependency Injection Pattern with Real-World Examples - -![Dependency Injection](./etc/dependency-injection.png "Dependency Injection") - ## When to Use the Dependency Injection Pattern in Java * When aiming to reduce the coupling between classes and increase the modularity of the application. From 7d2e6262cc91a5385c670f35bab9f5a4d59a8ca9 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 1 May 2025 10:01:53 +0300 Subject: [PATCH 12/19] build(deps): bump com.mycila:license-maven-plugin from 4.6 to 5.0.0 (#3268) Bumps [com.mycila:license-maven-plugin](https://github.com/mathieucarbou/license-maven-plugin) from 4.6 to 5.0.0. - [Release notes](https://github.com/mathieucarbou/license-maven-plugin/releases) - [Commits](https://github.com/mathieucarbou/license-maven-plugin/compare/license-maven-plugin-4.6...v5.0.0) --- updated-dependencies: - dependency-name: com.mycila:license-maven-plugin dependency-version: 5.0.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 20f468706502..d9667ed354d2 100644 --- a/pom.xml +++ b/pom.xml @@ -59,7 +59,7 @@ 3.5.2 - 4.6 + 5.0.0 3.14.0 From a62601a64f3f200450e08a45d71edcedf70a8a53 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 1 May 2025 10:02:39 +0300 Subject: [PATCH 13/19] build(deps): bump com.fasterxml.jackson.core:jackson-core (#3270) Bumps [com.fasterxml.jackson.core:jackson-core](https://github.com/FasterXML/jackson-core) from 2.18.2 to 2.19.0. - [Commits](https://github.com/FasterXML/jackson-core/compare/jackson-core-2.18.2...jackson-core-2.19.0) --- updated-dependencies: - dependency-name: com.fasterxml.jackson.core:jackson-core dependency-version: 2.19.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- dynamic-proxy/pom.xml | 2 +- event-sourcing/pom.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/dynamic-proxy/pom.xml b/dynamic-proxy/pom.xml index 586dbc1b6ab4..decbb24fd02d 100644 --- a/dynamic-proxy/pom.xml +++ b/dynamic-proxy/pom.xml @@ -46,7 +46,7 @@ com.fasterxml.jackson.core jackson-core - 2.18.2 + 2.19.0 com.fasterxml.jackson.core diff --git a/event-sourcing/pom.xml b/event-sourcing/pom.xml index 4cfd05d7adac..5660054d8195 100644 --- a/event-sourcing/pom.xml +++ b/event-sourcing/pom.xml @@ -50,7 +50,7 @@ com.fasterxml.jackson.core jackson-core - 2.18.2 + 2.19.0 com.fasterxml.jackson.core From 0da4dcda5b3af64b071a71f766c6ed54bcbf10cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= Date: Fri, 2 May 2025 21:55:32 +0300 Subject: [PATCH 14/19] docs: update producer-consumer --- producer-consumer/README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/producer-consumer/README.md b/producer-consumer/README.md index bb62c799a08f..575be804cd45 100644 --- a/producer-consumer/README.md +++ b/producer-consumer/README.md @@ -181,10 +181,6 @@ Program output: 08:10:17.483 [pool-1-thread-5] INFO com.iluwatar.producer.consumer.Consumer -- Consumer [Consumer_2] consume item [10] produced by [Producer_1] ``` -## Detailed Explanation of Producer-Consumer Pattern with Real-World Examples - -![Producer-Consumer](./etc/producer-consumer.png "Producer-Consumer") - ## When to Use the Producer-Consumer Pattern in Java * When you need to manage a buffer or queue where producers add data and consumers take data, often in a multithreaded environment. From 3ac1a36b058864b5fcd6fb9e42435f8fe7799591 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= Date: Fri, 2 May 2025 22:02:40 +0300 Subject: [PATCH 15/19] docs: update prototype --- prototype/README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/prototype/README.md b/prototype/README.md index 48f10868a86c..b97df0707ffc 100644 --- a/prototype/README.md +++ b/prototype/README.md @@ -156,10 +156,6 @@ Here's the console output from running the example. 08:36:19.014 [main] INFO com.iluwatar.prototype.App -- Orcish wolf attacks with laser ``` -## Detailed Explanation of Prototype Pattern with Real-World Examples - -![alt text](./etc/prototype.urm.png "Prototype pattern class diagram") - ## When to Use the Prototype Pattern in Java * When the classes to instantiate are specified at run-time, for example, by dynamic loading. From 8529017e025e4b0c8887730b5204926ef410f629 Mon Sep 17 00:00:00 2001 From: yoobin_mion <113106136+yybmion@users.noreply.github.com> Date: Fri, 16 May 2025 03:53:37 +0900 Subject: [PATCH 16/19] feat: Implement Thread-Pool Executor pattern (#3271) - Add implementation of Thread-Pool Executor pattern using hotel front desk example - Include unit tests - Create detailed README with pattern explanation and examples - Add Java source code with appropriate Javadoc comments Closes #3226 --- pom.xml | 1 + thread-pool-executor/README.md | 200 ++++++++++++++ .../etc/thread-pool-executor.urm.png | Bin 0 -> 86163 bytes .../etc/thread-pool-executor.urm.puml | 66 +++++ thread-pool-executor/pom.xml | 83 ++++++ .../com/iluwatar/threadpoolexecutor/App.java | 90 +++++++ .../threadpoolexecutor/FrontDeskService.java | 108 ++++++++ .../threadpoolexecutor/GuestCheckInTask.java | 52 ++++ .../VipGuestCheckInTask.java | 52 ++++ .../iluwatar/threadpoolexecutor/AppTest.java | 38 +++ .../FrontDeskServiceTest.java | 248 ++++++++++++++++++ .../GuestCheckInTaskTest.java | 55 ++++ .../VipGuestCheckInTaskTest.java | 48 ++++ 13 files changed, 1041 insertions(+) create mode 100644 thread-pool-executor/README.md create mode 100644 thread-pool-executor/etc/thread-pool-executor.urm.png create mode 100644 thread-pool-executor/etc/thread-pool-executor.urm.puml create mode 100644 thread-pool-executor/pom.xml create mode 100644 thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/App.java create mode 100644 thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/FrontDeskService.java create mode 100644 thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/GuestCheckInTask.java create mode 100644 thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTask.java create mode 100644 thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/AppTest.java create mode 100644 thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/FrontDeskServiceTest.java create mode 100644 thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/GuestCheckInTaskTest.java create mode 100644 thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTaskTest.java diff --git a/pom.xml b/pom.xml index d9667ed354d2..8337c97966da 100644 --- a/pom.xml +++ b/pom.xml @@ -231,6 +231,7 @@ table-module template-method templateview + thread-pool-executor throttling tolerant-reader trampoline diff --git a/thread-pool-executor/README.md b/thread-pool-executor/README.md new file mode 100644 index 000000000000..fa1d5a2c8062 --- /dev/null +++ b/thread-pool-executor/README.md @@ -0,0 +1,200 @@ +--- +title: "Thread-Pool Executor Pattern in Java: Efficient Concurrent Task Management" +shortTitle: Thread-Pool Executor +description: "Learn the Thread-Pool Executor pattern in Java with practical examples, class +diagrams, and implementation details. Understand how to manage concurrent tasks efficiently, +improving resource utilization and application performance." +category: Concurrency +language: en +tag: + +- Performance +- Resource Management +- Concurrency +- Multithreading +- Scalability + +--- + +## Intent of Thread-Pool Executor Design Pattern + +The Thread-Pool Executor pattern maintains a pool of worker threads to execute tasks concurrently, +optimizing resource usage by reusing existing threads instead of creating new ones for each task. + +## Detailed Explanation of Thread-Pool Executor Pattern with Real-World Examples + +### Real-world example + +> Imagine a busy airport security checkpoint where instead of opening a new lane for each traveler, +> a fixed number of security lanes (threads) are open to process all passengers. Each security +> officer (thread) processes one passenger (task) at a time, and when finished, immediately calls the +> next passenger in line. During peak travel times, passengers wait in a queue, but the system is much +> more efficient than trying to open a new security lane for each individual traveler. The airport can +> handle fluctuating passenger traffic throughout the day with consistent staffing, optimizing both +> resource utilization and passenger throughput. + +### In plain words + +> Thread-Pool Executor keeps a set of reusable threads that process multiple tasks throughout their +> lifecycle, rather than creating a new thread for each task. + +### Wikipedia says + +> A thread pool is a software design pattern for achieving concurrency of execution in a computer +> program. Often also called a replicated workers or worker-crew model, a thread pool maintains +> multiple threads waiting for tasks to be allocated for concurrent execution by the supervising +> program. + +### Class diagram + +![Thread-pool-executor Class diagram](./etc/thread-pool-executor.urm.png) + +## Programmatic Example of Thread-Pool Executor Pattern in Java + +Imagine a hotel front desk. + +The number of employees (thread pool) is limited, but guests (tasks) keep arriving endlessly. + +The Thread-Pool Executor pattern efficiently handles a large number of requests by reusing a small +set of threads. + +```java +@Slf4j +public class HotelFrontDesk { + public static void main(String[] args) throws InterruptedException, ExecutionException { + // Hire 3 front desk employees (threads) + ExecutorService frontDesk = Executors.newFixedThreadPool(3); + + LOGGER.info("Hotel front desk operation started!"); + + // 7 regular guests checking in (Runnable) + for (int i = 1; i <= 7; i++) { + String guestName = "Guest-" + i; + frontDesk.submit(() -> { + String employeeName = Thread.currentThread().getName(); + LOGGER.info("{} is checking in {}...", employeeName, guestName); + try { + Thread.sleep(2000); // Simulate check-in time + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + LOGGER.info("{} has been successfully checked in!", guestName); + }); + } + + // 3 VIP guests checking in (Callable with result) + Callable vipGuest1 = createVipGuest("VIP-Guest-1"); + Callable vipGuest2 = createVipGuest("VIP-Guest-2"); + Callable vipGuest3 = createVipGuest("VIP-Guest-3"); + + Future vipResult1 = frontDesk.submit(vipGuest1); + Future vipResult2 = frontDesk.submit(vipGuest2); + Future vipResult3 = frontDesk.submit(vipGuest3); + + // Shutdown after submitting all tasks + frontDesk.shutdown(); + + if (frontDesk.awaitTermination(1, TimeUnit.HOURS)) { + // Print VIP guests' check-in results + LOGGER.info("VIP Check-in Results:"); + LOGGER.info(vipResult1.get()); + LOGGER.info(vipResult2.get()); + LOGGER.info(vipResult3.get()); + LOGGER.info("All guests have been successfully checked in. Front desk is now closed."); + } else { + LOGGER.info("Check-in timeout. Forcefully shutting down the front desk."); + } + } + + private static Callable createVipGuest(String vipGuestName) { + return () -> { + String employeeName = Thread.currentThread().getName(); + LOGGER.info("{} is checking in VIP guest {}...", employeeName, vipGuestName); + Thread.sleep(1000); // VIPs are faster to check in + return vipGuestName + " has been successfully checked in!"; + }; + } +} +``` + +Here's the console output: + +```markdown +Hotel front desk operation started! +pool-1-thread-3 is checking in Guest-3... +pool-1-thread-2 is checking in Guest-2... +pool-1-thread-1 is checking in Guest-1... +Guest-2 has been successfully checked in! +Guest-1 has been successfully checked in! +Guest-3 has been successfully checked in! +pool-1-thread-2 is checking in Guest-5... +pool-1-thread-3 is checking in Guest-4... +pool-1-thread-1 is checking in Guest-6... +Guest-5 has been successfully checked in! +pool-1-thread-2 is checking in Guest-7... +Guest-4 has been successfully checked in! +pool-1-thread-3 is checking in VIP guest VIP-Guest-1... +Guest-6 has been successfully checked in! +pool-1-thread-1 is checking in VIP guest VIP-Guest-2... +pool-1-thread-3 is checking in VIP guest VIP-Guest-3... +Guest-7 has been successfully checked in! +VIP Check-in Results: +VIP-Guest-1 has been successfully checked in! +VIP-Guest-2 has been successfully checked in! +VIP-Guest-3 has been successfully checked in! +All guests have been successfully checked in. Front desk is now closed. +``` + +**Note:** Since this example demonstrates asynchronous thread execution, **the actual output may vary between runs**. The order of execution and timing can differ due to thread scheduling, system load, and other factors that affect concurrent processing. The core behavior of the thread pool (limiting concurrent tasks to the number of threads and reusing threads) will remain consistent, but the exact sequence of log messages may change with each execution. + +## When to Use the Thread-Pool Executor Pattern in Java + +* When you need to limit the number of threads running simultaneously to avoid resource exhaustion +* For applications that process a large number of short-lived independent tasks +* To improve performance by reducing thread creation/destruction overhead +* When implementing server applications that handle multiple client requests concurrently +* To execute recurring tasks at fixed rates or with fixed delays + +## Thread-Pool Executor Pattern Java Tutorial + +* [Thread-Pool Executor Pattern Tutorial (Baeldung)](https://www.baeldung.com/thread-pool-java-and-guava) + +## Real-World Applications of Thread-Pool Executor Pattern in Java + +* Application servers like Tomcat and Jetty use thread pools to handle HTTP requests +* Database connection pools in JDBC implementations +* Background job processing frameworks like Spring Batch +* Task scheduling systems like Quartz Scheduler +* Java EE's Managed Executor Service for enterprise applications + +## Benefits and Trade-offs of Thread-Pool Executor Pattern + +### Benefits + +* Improves performance by reusing existing threads instead of creating new ones +* Provides better resource management by limiting the number of active threads +* Simplifies thread lifecycle management and cleanup +* Facilitates easy implementation of task prioritization and scheduling +* Enhances application stability by preventing resource exhaustion + +### Trade-offs + +* May lead to thread starvation if improperly configured (too few threads) +* Potential for resource underutilization if improperly sized (too many threads) +* Requires careful shutdown handling to prevent task loss or resource leaks + +## Related Java Design Patterns + +* [Master-Worker Pattern](https://java-design-patterns.com/patterns/master-worker/): Tasks between a + master and multiple workers. +* [Producer-Consumer Pattern](https://java-design-patterns.com/patterns/producer-consumer/): + Separates task production and task consumption, typically using a blocking queue. +* [Object Pool Pattern](https://java-design-patterns.com/patterns/object-pool/): Reuses a set of + objects (e.g., threads) instead of creating/destroying them repeatedly. + +## References and Credits + +* [Java Documentation for ThreadPoolExecutor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ThreadPoolExecutor.html) +* [Java Concurrency in Practice](https://jcip.net/) by Brian Goetz +* [Effective Java](https://www.oreilly.com/library/view/effective-java-3rd/9780134686097/) by Joshua + Bloch diff --git a/thread-pool-executor/etc/thread-pool-executor.urm.png b/thread-pool-executor/etc/thread-pool-executor.urm.png new file mode 100644 index 0000000000000000000000000000000000000000..d426343f81712c249e609e27f433194a9b339479 GIT binary patch literal 86163 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%0AN&-T#}*(_KYE5EIwfo} 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 L=3J)G1=s%z2PWA^ literal 0 HcmV?d00001 diff --git a/thread-pool-executor/etc/thread-pool-executor.urm.puml b/thread-pool-executor/etc/thread-pool-executor.urm.puml new file mode 100644 index 000000000000..ca83f40c1b40 --- /dev/null +++ b/thread-pool-executor/etc/thread-pool-executor.urm.puml @@ -0,0 +1,66 @@ +@startuml + +interface Runnable { + +run(): void +} + +interface Callable { + +call(): T +} + +interface ExecutorService { + +submit(task: Runnable): Future + +submit(task: Callable): Future + +shutdown(): void + +awaitTermination(timeout: long, unit: TimeUnit): boolean +} + +class ThreadPoolExecutor { + -corePoolSize: int + -maximumPoolSize: int + -keepAliveTime: long + -workQueue: BlockingQueue + +execute(task: Runnable): void + +submit(task: Callable): Future +} + +class ThreadPoolManager { + -executorService: ExecutorService + +ThreadPoolManager(numThreads: int) + +submitTask(task: Runnable): void + +submitCallable(task: Callable): Future + +shutdown(): void + +awaitTermination(timeout: long, unit: TimeUnit): boolean +} + +class Task { + -id: int + -name: String + -processingTime: long + +Task(id: int, name: String, processingTime: long) + +run(): void + +call(): TaskResult +} + +class TaskResult { + -taskId: int + -taskName: String + -executionTime: long + +TaskResult(taskId: int, taskName: String, executionTime: long) +} + +class App { + +main(args: String[]): void + -executeRunnableTasks(poolManager: ThreadPoolManager): void + -executeCallableTasks(poolManager: ThreadPoolManager): void +} + +ExecutorService <|-- ThreadPoolExecutor : implements +Task ..|> Runnable : implements +Task ..|> Callable : implements +Task --> TaskResult : produces +ThreadPoolManager --> ExecutorService : wraps +App --> ThreadPoolManager : uses +App --> Task : creates + +@enduml \ No newline at end of file diff --git a/thread-pool-executor/pom.xml b/thread-pool-executor/pom.xml new file mode 100644 index 000000000000..f77cd92c67aa --- /dev/null +++ b/thread-pool-executor/pom.xml @@ -0,0 +1,83 @@ + + + + + 4.0.0 + + + com.iluwatar + java-design-patterns + 1.26.0-SNAPSHOT + + + thread-pool-executor + + + + org.slf4j + slf4j-api + + + ch.qos.logback + logback-classic + + + org.junit.jupiter + junit-jupiter-engine + test + + + org.mockito + mockito-core + test + + + + + + + org.apache.maven.plugins + maven-assembly-plugin + + + + + + com.iluwatar.threadpoolexecutor.App + + + + + + + + + diff --git a/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/App.java b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/App.java new file mode 100644 index 000000000000..0c1292b89c3a --- /dev/null +++ b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/App.java @@ -0,0 +1,90 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.threadpoolexecutor; + +import java.util.ArrayList; +import java.util.List; +import java.util.concurrent.ExecutionException; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; +import lombok.extern.slf4j.Slf4j; + +/** + * The Thread-Pool Executor pattern demonstrates how a pool of worker threads can be used to execute + * tasks concurrently. This pattern is particularly useful in scenarios where you need to execute a + * large number of independent tasks and want to limit the number of threads used. + * + *

In this example, a hotel front desk with a fixed number of employees processes guest + * check-ins. Each employee is represented by a thread, and each check-in is a task. + * + *

Key benefits demonstrated: + * + *

+ */ +@Slf4j +public class App { + + /** + * Program main entry point. + * + * @param args program runtime arguments + */ + public static void main(String[] args) throws InterruptedException, ExecutionException { + + FrontDeskService frontDesk = new FrontDeskService(5); + LOGGER.info("Hotel front desk operation started!"); + + LOGGER.info("Processing 30 regular guest check-ins..."); + for (int i = 1; i <= 30; i++) { + frontDesk.submitGuestCheckIn(new GuestCheckInTask("Guest-" + i)); + Thread.sleep(100); + } + + LOGGER.info("Processing 3 VIP guest check-ins..."); + List> vipResults = new ArrayList<>(); + + for (int i = 1; i <= 3; i++) { + Future result = + frontDesk.submitVipGuestCheckIn(new VipGuestCheckInTask("VIP-Guest-" + i)); + vipResults.add(result); + } + + frontDesk.shutdown(); + + if (frontDesk.awaitTermination(1, TimeUnit.HOURS)) { + LOGGER.info("VIP Check-in Results:"); + for (Future result : vipResults) { + LOGGER.info(result.get()); + } + LOGGER.info("All guests have been successfully checked in. Front desk is now closed."); + } else { + LOGGER.warn("Check-in timeout. Forcefully shutting down the front desk."); + } + } +} diff --git a/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/FrontDeskService.java b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/FrontDeskService.java new file mode 100644 index 000000000000..b80236ee5ecf --- /dev/null +++ b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/FrontDeskService.java @@ -0,0 +1,108 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.threadpoolexecutor; + +import java.util.concurrent.Callable; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; +import lombok.extern.slf4j.Slf4j; + +/** + * FrontDeskService represents the hotel's front desk with a fixed number of employees. This class + * demonstrates the Thread-Pool Executor pattern using Java's ExecutorService. + */ +@Slf4j +public class FrontDeskService { + + private final ExecutorService executorService; + private final int numberOfEmployees; + + /** + * Creates a new front desk with the specified number of employees. + * + * @param numberOfEmployees the number of employees (threads) at the front desk + */ + public FrontDeskService(int numberOfEmployees) { + this.numberOfEmployees = numberOfEmployees; + this.executorService = Executors.newFixedThreadPool(numberOfEmployees); + LOGGER.info("Front desk initialized with {} employees.", numberOfEmployees); + } + + /** + * Submits a regular guest check-in task to an available employee. + * + * @param task the check-in task to submit + * @return a Future representing pending completion of the task + */ + public Future submitGuestCheckIn(Runnable task) { + LOGGER.debug("Submitting regular guest check-in task"); + return executorService.submit(task, null); + } + + /** + * Submits a VIP guest check-in task to an available employee. + * + * @param task the VIP check-in task to submit + * @param the type of the task's result + * @return a Future representing pending completion of the task + */ + public Future submitVipGuestCheckIn(Callable task) { + LOGGER.debug("Submitting VIP guest check-in task"); + return executorService.submit(task); + } + + /** + * Closes the front desk after all currently checked-in guests are processed. No new check-ins + * will be accepted. + */ + public void shutdown() { + LOGGER.info("Front desk is closing - no new guests will be accepted."); + executorService.shutdown(); + } + + /** + * Waits for all check-in processes to complete or until timeout. + * + * @param timeout the maximum time to wait + * @param unit the time unit of the timeout argument + * @return true if all tasks completed, false if timeout elapsed + * @throws InterruptedException if interrupted while waiting + */ + public boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException { + LOGGER.info("Waiting for all check-ins to complete (max wait: {} {})", timeout, unit); + return executorService.awaitTermination(timeout, unit); + } + + /** + * Gets the number of employees at the front desk. + * + * @return the number of employees + */ + public int getNumberOfEmployees() { + return numberOfEmployees; + } +} diff --git a/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/GuestCheckInTask.java b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/GuestCheckInTask.java new file mode 100644 index 000000000000..d8a33fdfc8d2 --- /dev/null +++ b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/GuestCheckInTask.java @@ -0,0 +1,52 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.threadpoolexecutor; + +import lombok.AllArgsConstructor; +import lombok.extern.slf4j.Slf4j; + +/** + * GuestCheckInTask represents a regular guest check-in process. Implements Runnable because it + * performs an action without returning a result. + */ +@Slf4j +@AllArgsConstructor +public class GuestCheckInTask implements Runnable { + + private final String guestName; + + @Override + public void run() { + String employeeName = Thread.currentThread().getName(); + LOGGER.info("{} is checking in {}...", employeeName, guestName); + try { + Thread.sleep(2000); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + LOGGER.error("Check-in for {} was interrupted", guestName); + } + LOGGER.info("{} has been successfully checked in!", guestName); + } +} diff --git a/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTask.java b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTask.java new file mode 100644 index 000000000000..3948c114f0d6 --- /dev/null +++ b/thread-pool-executor/src/main/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTask.java @@ -0,0 +1,52 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.threadpoolexecutor; + +import java.util.concurrent.Callable; +import lombok.AllArgsConstructor; +import lombok.extern.slf4j.Slf4j; + +/** + * VipGuestCheckInTask represents a VIP guest check-in process. Implements Callable because it + * returns a result (check-in confirmation). + */ +@Slf4j +@AllArgsConstructor +public class VipGuestCheckInTask implements Callable { + + private final String vipGuestName; + + @Override + public String call() throws Exception { + String employeeName = Thread.currentThread().getName(); + LOGGER.info("{} is checking in VIP guest {}...", employeeName, vipGuestName); + + Thread.sleep(1000); + + String result = vipGuestName + " has been successfully checked in!"; + LOGGER.info("VIP check-in completed: {}", result); + return result; + } +} diff --git a/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/AppTest.java b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/AppTest.java new file mode 100644 index 000000000000..13e3a5beec3c --- /dev/null +++ b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/AppTest.java @@ -0,0 +1,38 @@ +/* + * 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-2022 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. + */ + +package com.iluwatar.threadpoolexecutor; + +import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; + +import org.junit.jupiter.api.Test; + +class AppTest { + + @Test + void appStartsWithoutException() { + assertDoesNotThrow(() -> App.main(new String[] {})); + } +} diff --git a/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/FrontDeskServiceTest.java b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/FrontDeskServiceTest.java new file mode 100644 index 000000000000..8d0396bf0541 --- /dev/null +++ b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/FrontDeskServiceTest.java @@ -0,0 +1,248 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.threadpoolexecutor; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.ArrayList; +import java.util.List; +import java.util.concurrent.Callable; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.Future; +import java.util.concurrent.RejectedExecutionException; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import org.junit.jupiter.api.Test; + +class FrontDeskServiceTest { + + /** + * Tests that the constructor correctly sets the number of employees (threads). This verifies the + * basic initialization of the thread pool. + */ + @Test + void testConstructorSetsCorrectNumberOfEmployees() { + int expectedEmployees = 3; + + FrontDeskService frontDesk = new FrontDeskService(expectedEmployees); + + assertEquals(expectedEmployees, frontDesk.getNumberOfEmployees()); + } + + /** + * Tests that the submitGuestCheckIn method returns a non-null Future object. This verifies the + * basic task submission functionality. + */ + @Test + void testSubmitGuestCheckInReturnsNonNullFuture() { + FrontDeskService frontDesk = new FrontDeskService(1); + + Runnable task = + () -> { + // Task that completes quickly + }; + + Future future = frontDesk.submitGuestCheckIn(task); + + assertNotNull(future); + } + + /** + * Tests that the submitVipGuestCheckIn method returns a non-null Future object. This verifies + * that tasks with return values can be submitted correctly. + */ + @Test + void testSubmitVipGuestCheckInReturnsNonNullFuture() { + FrontDeskService frontDesk = new FrontDeskService(1); + Callable task = () -> "VIP Check-in complete"; + + Future future = frontDesk.submitVipGuestCheckIn(task); + + assertNotNull(future); + } + + /** + * Tests that the shutdown and awaitTermination methods work correctly. This verifies the basic + * shutdown functionality of the thread pool. + */ + @Test + void testShutdownAndAwaitTermination() throws InterruptedException { + FrontDeskService frontDesk = new FrontDeskService(2); + CountDownLatch taskLatch = new CountDownLatch(1); + + Runnable task = taskLatch::countDown; + + frontDesk.submitGuestCheckIn(task); + frontDesk.shutdown(); + boolean terminated = frontDesk.awaitTermination(1, TimeUnit.SECONDS); + + assertTrue(terminated); + assertTrue(taskLatch.await(100, TimeUnit.MILLISECONDS)); + } + + /** + * Tests the thread pool's behavior under load with multiple tasks. This verifies that the thread + * pool limits concurrent execution to the number of threads, all submitted tasks are eventually + * completed, and threads are reused for multiple tasks. + */ + @Test + void testMultipleTasksUnderLoad() throws InterruptedException { + FrontDeskService frontDesk = new FrontDeskService(2); + int taskCount = 10; + CountDownLatch tasksCompletedLatch = new CountDownLatch(taskCount); + AtomicInteger concurrentTasks = new AtomicInteger(0); + AtomicInteger maxConcurrentTasks = new AtomicInteger(0); + + for (int i = 0; i < taskCount; i++) { + frontDesk.submitGuestCheckIn( + () -> { + try { + int current = concurrentTasks.incrementAndGet(); + maxConcurrentTasks.updateAndGet(max -> Math.max(max, current)); + + Thread.sleep(100); + + concurrentTasks.decrementAndGet(); + tasksCompletedLatch.countDown(); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + }); + } + + boolean allTasksCompleted = tasksCompletedLatch.await(2, TimeUnit.SECONDS); + + frontDesk.shutdown(); + frontDesk.awaitTermination(1, TimeUnit.SECONDS); + + assertTrue(allTasksCompleted); + assertEquals(2, maxConcurrentTasks.get()); + assertEquals(0, concurrentTasks.get()); + } + + /** + * Tests proper shutdown behavior under load. This verifies that after shutdown no new tasks are + * accepted, all previously submitted tasks are completed, and the executor terminates properly + * after all tasks complete. + */ + @Test + void testProperShutdownUnderLoad() throws InterruptedException { + FrontDeskService frontDesk = new FrontDeskService(2); + int taskCount = 5; + CountDownLatch startedTasksLatch = new CountDownLatch(2); + CountDownLatch tasksCompletionLatch = new CountDownLatch(taskCount); + + for (int i = 0; i < taskCount; i++) { + frontDesk.submitGuestCheckIn( + () -> { + try { + startedTasksLatch.countDown(); + Thread.sleep(100); + tasksCompletionLatch.countDown(); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + }); + } + + assertTrue(startedTasksLatch.await(1, TimeUnit.SECONDS)); + + frontDesk.shutdown(); + + assertThrows( + RejectedExecutionException.class, + () -> { + frontDesk.submitGuestCheckIn(() -> {}); + }); + + boolean allTasksCompleted = tasksCompletionLatch.await(2, TimeUnit.SECONDS); + + boolean terminated = frontDesk.awaitTermination(1, TimeUnit.SECONDS); + + assertTrue(allTasksCompleted); + assertTrue(terminated); + } + + /** + * Tests concurrent execution of different task types (regular and VIP). This verifies that both + * Runnable and Callable tasks can be processed concurrently, all tasks complete successfully, and + * Callable tasks return their results correctly. + */ + @Test + void testConcurrentRegularAndVipTasks() throws Exception { + FrontDeskService frontDesk = new FrontDeskService(3); + int regularTaskCount = 4; + int vipTaskCount = 3; + CountDownLatch allTasksLatch = new CountDownLatch(regularTaskCount + vipTaskCount); + + List> regularResults = new ArrayList<>(); + for (int i = 0; i < regularTaskCount; i++) { + Future result = + frontDesk.submitGuestCheckIn( + () -> { + try { + Thread.sleep(50); + allTasksLatch.countDown(); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + }); + regularResults.add(result); + } + + List> vipResults = new ArrayList<>(); + for (int i = 0; i < vipTaskCount; i++) { + final int guestNum = i; + Future result = + frontDesk.submitVipGuestCheckIn( + () -> { + Thread.sleep(25); + allTasksLatch.countDown(); + return "VIP-" + guestNum + " checked in"; + }); + vipResults.add(result); + } + + boolean allCompleted = allTasksLatch.await(2, TimeUnit.SECONDS); + + frontDesk.shutdown(); + frontDesk.awaitTermination(1, TimeUnit.SECONDS); + + assertTrue(allCompleted); + + for (Future result : regularResults) { + assertTrue(result.isDone()); + } + + for (int i = 0; i < vipTaskCount; i++) { + Future result = vipResults.get(i); + assertTrue(result.isDone()); + assertEquals("VIP-" + i + " checked in", result.get()); + } + } +} diff --git a/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/GuestCheckInTaskTest.java b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/GuestCheckInTaskTest.java new file mode 100644 index 000000000000..27bb75efd2db --- /dev/null +++ b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/GuestCheckInTaskTest.java @@ -0,0 +1,55 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.threadpoolexecutor; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import java.util.concurrent.atomic.AtomicReference; +import org.junit.jupiter.api.Test; + +class GuestCheckInTaskTest { + + /** + * Tests that the task executes in the current thread when called directly. This verifies that the + * thread name inside the task matches the calling thread. + */ + @Test + void testThreadNameInTask() { + String guestName = "TestGuest"; + AtomicReference capturedThreadName = new AtomicReference<>(); + + GuestCheckInTask task = + new GuestCheckInTask(guestName) { + @Override + public void run() { + capturedThreadName.set(Thread.currentThread().getName()); + } + }; + + task.run(); + + assertEquals(Thread.currentThread().getName(), capturedThreadName.get()); + } +} diff --git a/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTaskTest.java b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTaskTest.java new file mode 100644 index 000000000000..d76d90625c95 --- /dev/null +++ b/thread-pool-executor/src/test/java/com/iluwatar/threadpoolexecutor/VipGuestCheckInTaskTest.java @@ -0,0 +1,48 @@ +/* + * 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-2022 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. + */ +package com.iluwatar.threadpoolexecutor; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; + +import org.junit.jupiter.api.Test; + +class VipGuestCheckInTaskTest { + + /** + * Tests that the call method returns the expected result string. This verifies that the VIP + * check-in task correctly formats its result message. + */ + @Test + void testCallReturnsExpectedResult() throws Exception { + String vipGuestName = "TestVipGuest"; + VipGuestCheckInTask task = new VipGuestCheckInTask(vipGuestName); + + String result = task.call(); + + assertNotNull(result); + assertEquals("TestVipGuest has been successfully checked in!", result); + } +} From bf164009b4e1c0a3093ebcbaf1d6424d013a4ab4 Mon Sep 17 00:00:00 2001 From: "allcontributors[bot]" <46447321+allcontributors[bot]@users.noreply.github.com> Date: Thu, 15 May 2025 21:55:54 +0300 Subject: [PATCH 17/19] docs: add yybmion as a contributor for code (#3279) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> --- .all-contributorsrc | 9 +++++++++ README.md | 3 ++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/.all-contributorsrc b/.all-contributorsrc index 9509bc095ae7..25ecf853dee3 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -3520,6 +3520,15 @@ "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, diff --git a/README.md b/README.md index c2c3a5c7af10..5b003cc394ea 100644 --- a/README.md +++ b/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](https://img.shields.io/badge/all_contributors-386-orange.svg?style=flat-square)](#contributors-) +[![All Contributors](https://img.shields.io/badge/all_contributors-387-orange.svg?style=flat-square)](#contributors-)
@@ -575,6 +575,7 @@ This project is licensed under the terms of the MIT license. e5LA
e5LA
💻 Maziyar Gerami
Maziyar Gerami
🌍 + yoobin_mion
yoobin_mion
💻 From f6bb51581f6d2f0e5c643e5e1cc93d9987e96b72 Mon Sep 17 00:00:00 2001 From: e5LA <208197507+e5LA@users.noreply.github.com> Date: Sat, 17 May 2025 07:53:25 +0200 Subject: [PATCH 18/19] chore: adding missing license (#3273) Co-authored-by: SP --- .../com/iluwatar/leaderfollowers/App.java | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/leader-followers/src/main/java/com/iluwatar/leaderfollowers/App.java b/leader-followers/src/main/java/com/iluwatar/leaderfollowers/App.java index 28b039cc7738..88ff5c55fa56 100644 --- a/leader-followers/src/main/java/com/iluwatar/leaderfollowers/App.java +++ b/leader-followers/src/main/java/com/iluwatar/leaderfollowers/App.java @@ -1,3 +1,27 @@ +/* + * 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-2022 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. + */ package com.iluwatar.leaderfollowers; import java.security.SecureRandom; From ede37bd05568b1b8b814d8e9a1d2bbd71d9d615d Mon Sep 17 00:00:00 2001 From: "allcontributors[bot]" <46447321+allcontributors[bot]@users.noreply.github.com> Date: Sat, 17 May 2025 08:55:06 +0300 Subject: [PATCH 19/19] docs: add e5LA as a contributor for doc (#3281) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> --- .all-contributorsrc | 3 ++- README.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.all-contributorsrc b/.all-contributorsrc index 25ecf853dee3..32f5734184c4 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -3509,7 +3509,8 @@ "avatar_url": "https://avatars.githubusercontent.com/u/208197507?v=4", "profile": "https://github.com/e5LA", "contributions": [ - "code" + "code", + "doc" ] }, { diff --git a/README.md b/README.md index 5b003cc394ea..2c2e375bf4f9 100644 --- a/README.md +++ b/README.md @@ -573,7 +573,7 @@ This project is licensed under the terms of the MIT license. ssrijan-007-sys
ssrijan-007-sys
💻 - e5LA
e5LA
💻 + e5LA
e5LA
💻 📖 Maziyar Gerami
Maziyar Gerami
🌍 yoobin_mion
yoobin_mion
💻