Merge branch 'master' of https://github.com/naman-sriv/java-design-patterns

Author: naman-sriv

Diff for: leader-followers/src/main/java/com/iluwatar/leaderfollowers/App.java

@@ -1,61 +1,13 @@
-/*
- * 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;
 import java.util.concurrent.Executors;
 import java.util.concurrent.TimeUnit;
+import lombok.extern.slf4j.Slf4j;
 
-/**
- * Leader/Followers pattern is a concurrency pattern. This pattern behaves like a taxi stand where
- * one of the threads acts as leader thread which listens for event from event sources,
- * de-multiplexes, dispatches and handles the event. It promotes the follower to be the new leader.
- * When processing completes the thread joins the followers queue, if there are no followers then it
- * becomes the leader and cycle repeats again.
- *
- * <p>In this example, one of the workers becomes Leader and listens on the {@link TaskSet} for
- * work. {@link TaskSet} basically acts as the source of input events for the {@link Worker}, who
- * are spawned and controlled by the {@link WorkCenter} . When {@link Task} arrives then the leader
- * takes the work and calls the {@link TaskHandler}. It also calls the {@link WorkCenter} to
- * promotes one of the followers to be the new leader, who can then process the next work and so on.
- *
- * <p>The pros for this pattern are: It enhances CPU cache affinity and eliminates unbound
- * allocation and data buffer sharing between threads by reading the request into buffer space
- * allocated on the stack of the leader or by using the Thread-Specific Storage pattern [22] to
- * allocate memory. It minimizes locking overhead by not exchanging data between threads, thereby
- * reducing thread synchronization. In bound handle/thread associations, the leader thread
- * dispatches the event based on the I/O handle. It can minimize priority inversion because no extra
- * queuing is introduced in the server. It does not require a context switch to handle each event,
- * reducing the event dispatching latency. Note that promoting a follower thread to fulfill the
- * leader role requires a context switch. Programming simplicity: The Leader/Followers pattern
- * simplifies the programming of concurrency models where multiple threads can receive requests,
- * process responses, and de-multiplex connections using a shared handle set.
- */
+@Slf4j
 public class App {
 
-  /** The main method for the leader followers pattern. */
   public static void main(String[] args) throws InterruptedException {
     var taskSet = new TaskSet();
     var taskHandler = new TaskHandler();
@@ -64,18 +16,23 @@ public static void main(String[] args) throws InterruptedException {
     execute(workCenter, taskSet);
   }
 
-  /** Start the work, dispatch tasks and stop the thread pool at last. */
   private static void execute(WorkCenter workCenter, TaskSet taskSet) throws InterruptedException {
     var workers = workCenter.getWorkers();
     var exec = Executors.newFixedThreadPool(workers.size());
-    workers.forEach(exec::submit);
-    Thread.sleep(1000);
-    addTasks(taskSet);
-    exec.awaitTermination(2, TimeUnit.SECONDS);
-    exec.shutdownNow();
+
+    try {
+      workers.forEach(exec::submit);
+      Thread.sleep(1000);
+      addTasks(taskSet);
+      boolean terminated = exec.awaitTermination(2, TimeUnit.SECONDS);
+      if (!terminated) {
+        LOGGER.warn("Executor did not terminate in the given time.");
+      }
+    } finally {
+      exec.shutdownNow();
+    }
   }
 
-  /** Add tasks. */
   private static void addTasks(TaskSet taskSet) throws InterruptedException {
     var rand = new SecureRandom();
     for (var i = 0; i < 5; i++) {

Diff for: saga/README.md

@@ -31,6 +31,10 @@ Wikipedia says
 
 > Long-running transactions (also known as the saga interaction pattern) are computer database transactions that avoid locks on non-local resources, use compensation to handle failures, potentially aggregate smaller ACID transactions (also referred to as atomic transactions), and typically use a coordinator to complete or abort the transaction. In contrast to rollback in ACID transactions, compensation restores the original state, or an equivalent, and is business-specific. For example, the compensating action for making a hotel reservation is canceling that reservation.
 
+Flowchart
+
+![Saga flowchart](./etc/saga-flowchart.png)
+
 ## Programmatic Example of Saga Pattern in Java
 
 The Saga design pattern is a sequence of local transactions where each transaction updates data within a single service. It's particularly useful in a microservices architecture where each service has its own database. The Saga pattern ensures data consistency and fault tolerance across services. Here are the key components of the Saga pattern:

Diff for: saga/etc/saga-flowchart.png

@@ -31,6 +31,10 @@ In plain words
 
 > Defines a client interface separate from its implementation to allow for flexible and interchangeable components.
 
+Sequence diagram
+
+![Separated Interface sequence diagram](./etc/separated-interface-sequence-diagram.png)
+
 ## Programmatic Example of Separated Interface Pattern in Java
 
 The Java Separated Interface design pattern is a crucial software architecture strategy that promotes separating the interface definition from its implementation, crucial for enhancing system flexibility and scalability. This allows the client to be completely unaware of the implementation, promoting loose coupling and enhancing flexibility.

Diff for: separated-interface/README.md

@@ -32,6 +32,10 @@ Wikipedia says
 
 > In computing, serialization is the process of translating a data structure or object state into a format that can be stored (e.g. files in secondary storage devices, data buffers in primary storage devices) or transmitted (e.g. data streams over computer networks) and reconstructed later (possibly in a different computer environment). When the resulting series of bits is reread according to the serialization format, it can be used to create a semantically identical clone of the original object. For many complex objects, such as those that make extensive use of references, this process is not straightforward. Serialization of objects does not include any of their associated methods with which they were previously linked.
 
+Flowchart
+
+![Serialized Entity flowchart](./etc/serialized-entity-flowchart.png)
+
 ## Programmatic Example of Serialized Entity Pattern in Java
 
 The Serialized Entity design pattern is a way to easily persist Java objects to the database. It uses the `Serializable` interface and the DAO (Data Access Object) pattern. The pattern first uses `Serializable` to convert a Java object into a set of bytes, then it uses the DAO pattern to store this set of bytes as a BLOB (Binary Large OBject) in the database.

Diff for: separated-interface/etc/separated-interface-sequence-diagram.png

@@ -30,6 +30,10 @@ In plain words
 
 > The Serialized LOB design pattern manages the storage of large objects, such as files or multimedia, by serializing and storing them directly within a database.
 
+Flowchart
+
+![Serialized LOB flowchart](./etc/serialized-lob-flowchart.png)
+
 ## Programmatic Example of Serialized LOB Pattern in Java
 
 The Serialized Large Object (LOB) design pattern is a way to handle large objects in a database. It involves serializing an object graph into a single large object (a BLOB or CLOB, for Binary Large Object or Character Large Object, respectively) and storing it in the database. When the object graph needs to be retrieved, it is read from the database and deserialized back into the original object graph.

Diff for: serialized-entity/README.md

@@ -34,6 +34,10 @@ Wikipedia says
 
 > In software engineering, the servant pattern defines an object used to offer some functionality to a group of classes without defining that functionality in each of them. A Servant is a class whose instance (or even just class) provides methods that take care of a desired service, while objects for which (or with whom) the servant does something, are taken as parameters.
 
+Sequence diagram
+
+![Servant sequence diagram](./etc/servant-sequence-diagram.png)
+
 ## Programmatic Example of Servant Pattern in Java
 
 The Servant design pattern is a behavioral design pattern that defines a class that provides some sort of service to a group of classes. This pattern is particularly useful when these classes lack some common functionality that can't be added to the superclass. The Servant class brings this common functionality to a group of classes.

Diff for: serialized-entity/etc/serialized-entity-flowchart.png

@@ -34,6 +34,10 @@ Wikipedia says
 
 > A session token is a unique identifier that is generated and sent from a server to a client to identify the current interaction session. The client usually stores and sends the token as an HTTP cookie and/or sends it as a parameter in GET or POST queries. The reason to use session tokens is that the client only has to handle the identifier—all session data is stored on the server (usually in a database, to which the client does not have direct access) linked to that identifier.
 
+Sequence diagram
+
+![Server Session sequence diagram](./etc/server-session-sequence-diagram.png)
+
 ## Programmatic Example of Server Session Pattern in Java
 
 The Server Session design pattern is a behavioral design pattern that assigns the responsibility of storing session data on the server side. This pattern is particularly useful in the context of stateless protocols like HTTP where all requests are isolated events independent of previous requests.

Diff for: serialized-lob/README.md

@@ -40,7 +40,6 @@ Architecture diagram
 
 ![Service Layer Architecture Diagram](./etc/service-layer-architecture-diagram.png)
 
-
 ## Programmatic Example of Service Layer Pattern in Java
 
 Our Java implementation uses the Service Layer pattern to streamline interactions between data access objects (DAOs) and the business logic, ensuring a clean separation of concerns.
@@ -358,10 +357,6 @@ INFO  [2024-05-27 09:16:40,681] com.iluwatar.servicelayer.app.App: Find wizards
 INFO  [2024-05-27 09:16:40,683] com.iluwatar.servicelayer.app.App: Aderlard Boud has 'Fireball'
 ```
 
-## Detailed Explanation of Service Layer Pattern with Real-World Examples
-
-![Service Layer](./etc/service-layer.png "Service Layer")
-
 ## When to Use the Service Layer Pattern in Java
 
 * Use when you need to separate business logic from presentation logic.

Diff for: serialized-lob/etc/serialized-lob-flowchart.png

@@ -33,6 +33,10 @@ Wikipedia says
 
 > The service locator pattern is a design pattern used in software development to encapsulate the processes involved in obtaining a service with a strong abstraction layer. This pattern uses a central registry known as the "service locator", which on request returns the information necessary to perform a certain task. Proponents of the pattern say the approach simplifies component-based applications where all dependencies are cleanly listed at the beginning of the whole application design, consequently making traditional dependency injection a more complex way of connecting objects. Critics of the pattern argue that it is an antipattern which obscures dependencies and makes software harder to test.
 
+Sequence diagram
+
+![Service Locator sequence diagram](./etc/service-locator-sequence-diagram.png)
+
 ## Programmatic Example of Service Locator Pattern in Java
 
 The Service Locator design pattern is used to abstract the processes involved in obtaining a service. It uses a central registry, the "service locator", which returns the necessary information to perform a task upon request. This Java design pattern is particularly useful in enterprise Java applications where services need centralized management.

Diff for: servant/README.md

@@ -34,6 +34,10 @@ Wikipedia says
 
 > A test stub is a dummy component used during testing to isolate behavior.
 
+Sequence diagram
+
+![Service Stub sequence diagram](./etc/service-stub-sequence-diagram.png)
+
 ## Programmatic Example of Service Stub Pattern in Java
 
 We define a `SentimentAnalysisService` interface and provide two implementations:

Diff for: servant/etc/servant-sequence-diagram.png

@@ -26,6 +26,10 @@ In plain words
 
 > Separates the processing logic from the view in web applications to improve maintainability and scalability.
 
+Sequence diagram
+
+![Service to Worker sequence diagram](./etc/service-to-worker-sequence-diagram.png)
+
 ## Programmatic Example of Service to Worker Pattern in Java
 
 The Service to Worker design pattern separates the processing logic from the view in web applications to improve maintainability and scalability. It combines the Dispatcher View and Service Locator patterns to facilitate the separation of processing, control flow, and view management in web applications.

Diff for: server-session/README.md

@@ -34,6 +34,10 @@ In plain words
 
 > The Session Facade design pattern is an excellent choice for decoupling complex components of the system that need to be interacting frequently. 
 
+Sequence diagram
+
+![Session Facade sequence diagram](./etc/session-facade-sequence-diagram.png)
+
 ## Programmatic Example of Session Facade Pattern in Java
 
 The Session Facade design pattern is a structural design pattern that provides a simplified interface to a set of complex subsystems, reducing the complexity for the client. This pattern is particularly useful in situations where the client needs to interact with multiple services or systems but doesn’t need to know the internal workings of each service.

Diff for: server-session/etc/server-session-sequence-diagram.png

@@ -35,6 +35,10 @@ Wikipedia says
 >
 > There are numerous advantages to the horizontal partitioning approach. Since the tables are divided and distributed into multiple servers, the total number of rows in each table in each database is reduced. This reduces index size, which generally improves search performance. A database shard can be placed on separate hardware, and multiple shards can be placed on multiple machines. This enables a distribution of the database over a large number of machines, greatly improving performance. In addition, if the database shard is based on some real-world segmentation of the data (e.g., European customers v. American customers) then it may be possible to infer the appropriate shard membership easily and automatically, and query only the relevant shard.
 
+Flowchart
+
+![Sharding flowchart](./etc/sharding-flowchart.png)
+
 ## Programmatic Example of Sharding Pattern in Java
 
 Sharding is a type of database partitioning that separates very large databases into smaller, faster, more easily managed parts called data shards. The word shard means a small part of a whole. In software architecture, it refers to a horizontal partition in a database or search engine. Each individual partition is referred to as a shard or database shard.

Diff for: service-layer/README.md

@@ -36,6 +36,10 @@ Wikipedia says
 
 > Single table inheritance is a way to emulate object-oriented inheritance in a relational database. When mapping from a database table to an object in an object-oriented language, a field in the database identifies what class in the hierarchy the object belongs to. All fields of all the classes are stored in the same table, hence the name "Single Table Inheritance".
 
+Flowchart
+
+![Single Table Inheritance flowchart](./etc/single-table-inheritance-flowchart.png)
+
 ## Programmatic Example of Single Table Inheritance Pattern in Java
 
 Single Table Inheritance is a design pattern that maps an inheritance hierarchy of classes to a single database table. Each row in the table represents an instance of a class in the hierarchy. A special discriminator column is used to identify the class to which each row belongs.

Diff for: service-locator/README.md

@@ -33,6 +33,10 @@ Wikipedia says
 
 > In software engineering, the singleton pattern is a software design pattern that restricts the instantiation of a class to one object. This is useful when exactly one object is needed to coordinate actions across the system.
 
+Sequence diagram
+
+![Singleton Pattern sequence diagram](./etc/singleton-sequence-diagram.png)
+
 ## Programmatic Example of Singleton Pattern in Java
 
 Joshua Bloch, Effective Java 2nd Edition p.18

Diff for: service-locator/etc/service-locator-sequence-diagram.png

@@ -39,6 +39,10 @@ Wikipedia says
 >
 > For example, in ray tracing, space partitioning helps quickly determine the objects a ray might intersect by narrowing down the search space, leading to faster rendering times. Similarly, in game development, Quadtrees can efficiently manage 2D game environments by segmenting the space into smaller regions, facilitating quicker collision detection and rendering.
 
+Flowchart
+
+![Spatial Partition flowchart](./etc/spatial-partition-flowchart.png)
+
 ## Programmatic Example of Spatial Partition Pattern in Java
 
 The Spatial Partition design pattern in Java is a strategic approach for handling multiple objects in expansive game worlds or detailed simulation environments, boosting query efficiency and operational speed. It allows us to efficiently manage these objects and perform operations like collision detection or range queries. The pattern works by dividing the space into smaller, manageable regions, and each object is associated with the region it belongs to. This way, we can limit our operations to a specific region, instead of checking every object against every other object.

Diff for: service-stub/README.md

@@ -37,6 +37,10 @@ In [Patterns of Enterprise Application Architecture](https://amzn.to/3WfKBPR) Ma
 
 > If you’ll pardon the unresistable pun, I see [Null Object](https://java-design-patterns.com/patterns/null-object/) as special case of Special Case.
 
+Sequnce diagram
+
+![Special Case sequence diagram](./etc/special-case-sequence-diagram.png)
+
 ## Programmatic Example of Special Case Pattern in Java
 
 The Special Case Pattern is a software design pattern that is used to handle a specific, often uncommon, case separately from the general case in the code. This pattern is useful when a class has behavior that requires conditional logic based on its state. Instead of cluttering the class with conditional logic, we can encapsulate the special behavior in a subclass.

Diff for: service-stub/etc/service-stub-sequence-diagram.png

@@ -37,6 +37,10 @@ Wikipedia says
 
 > In computer programming, the specification pattern is a particular software design pattern, whereby business rules can be recombined by chaining the business rules together using boolean logic.
 
+Flowchart
+
+![Specification Pattern flowchart](./etc/specification-flowchart.png)
+
 ## Programmatic Example of Specification Pattern in Java
 
 Let's consider a creature pool example. We have a collection of creatures with specific properties. These properties might belong to a predefined, limited set (represented by enums like `Size`, `Movement`, and `Color`) or they might be continuous values (e.g., the mass of a `Creature`). In cases with continuous values, it's better to use a "parameterized specification," where the property value is provided as an argument when the `Creature` is instantiated, allowing for greater flexibility. Additionally, predefined and/or parameterized properties can be combined using boolean logic, offering almost limitless selection possibilities (this is known as a "composite specification," explained further below). The advantages and disadvantages of each approach are detailed in the table at the end of this document.