diff --git a/abstract-document/README.md b/abstract-document/README.md
index 7c30819c7f6b..56f8e775c676 100644
--- a/abstract-document/README.md
+++ b/abstract-document/README.md
@@ -1,24 +1,29 @@
---
-title: Abstract Document
+title: "Abstract Document Pattern in Java: Simplifying Data Handling with Flexibility"
+shortTitle: Abstract Document
+description: "Explore the Abstract Document design pattern in Java. Learn its intent, explanation, applicability, benefits, and see real-world examples to implement flexible and dynamic data structures."
category: Structural
language: en
-tag:
- - Abstraction
- - Extensibility
- - Decoupling
+tag:
+ - Abstraction
+ - Decoupling
+ - Dynamic typing
+ - Encapsulation
+ - Extensibility
+ - Polymorphism
---
-## Intent
+## Intent of Abstract Document Design Pattern
-The Abstract Document design pattern is a structural design pattern that aims to provide a consistent way to handle hierarchical and tree-like data structures by defining a common interface for various document types. It separates the core document structure from specific data formats, enabling dynamic updates and simplified maintenance.
+The Abstract Document design pattern in Java is a crucial structural design pattern that provides a consistent way to handle hierarchical and tree-like data structures by defining a common interface for various document types. It separates the core document structure from specific data formats, enabling dynamic updates and simplified maintenance.
-## Explanation
+## Detailed Explanation of Abstract Document Pattern with Real-World Examples
-The Abstract Document pattern enables handling additional, non-static properties. This pattern uses concept of traits to enable type safety and separate properties of different classes into set of interfaces.
+The Abstract Document design pattern in Java allows dynamic handling of non-static properties. This pattern uses concept of traits to enable type safety and separate properties of different classes into set of interfaces.
-Real world example
+Real-world example
-> Consider a car that consists of multiple parts. However, we don't know if the specific car really has all the parts, or just some of them. Our cars are dynamic and extremely flexible.
+> Consider a library system implementing the Abstract Document design pattern in Java, where books can have diverse formats and attributes: physical books, eBooks, and audiobooks. Each format has unique properties, such as page count for physical books, file size for eBooks, and duration for audiobooks. The Abstract Document design pattern allows the library system to manage these diverse formats flexibly. By using this pattern, the system can store and retrieve properties dynamically, without needing a rigid structure for each book type, making it easier to add new formats or attributes in the future without significant changes to the codebase.
In plain words
@@ -28,86 +33,103 @@ Wikipedia says
> An object-oriented structural design pattern for organizing objects in loosely typed key-value stores and exposing the data using typed views. The purpose of the pattern is to achieve a high degree of flexibility between components in a strongly typed language where new properties can be added to the object-tree on the fly, without losing the support of type-safety. The pattern makes use of traits to separate different properties of a class into different interfaces.
-**Programmatic Example**
+Class diagram
+
+
+
+
+## Programmatic Example of Abstract Document Pattern in Java
+
+Consider a car that consists of multiple parts. However, we don't know if the specific car really has all the parts, or just some of them. Our cars are dynamic and extremely flexible.
Let's first define the base classes `Document` and `AbstractDocument`. They basically make the object hold a property map and any amount of child objects.
```java
public interface Document {
- Void put(String key, Object value);
+ Void put(String key, Object value);
- Object get(String key);
+ Object get(String key);
- Stream children(String key, Function, T> constructor);
+ 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);
- }
- ...
+ 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...
}
```
-Next we define an enum `Property` and a set of interfaces for type, price, model and parts. This allows us to create static looking interface to our `Car` class.
+
+Next we define an enum `Property` and a set of interfaces for type, price, model and parts. This allows us to create static looking interface to our `Car` class.
```java
public enum Property {
- PARTS, TYPE, PRICE, MODEL
+ PARTS, TYPE, PRICE, MODEL
}
public interface HasType extends Document {
- default Optional getType() {
- return Optional.ofNullable((String) get(Property.TYPE.toString()));
- }
+ 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()));
- }
+ 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()));
- }
+ 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);
- }
+ 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);
+ }
}
```
@@ -116,31 +138,32 @@ Now we are ready to introduce the `Car`.
```java
public class Car extends AbstractDocument implements HasModel, HasPrice, HasParts {
- public Car(Map properties) {
- super(properties);
- }
+ public Car(Map properties) {
+ super(properties);
+ }
}
```
And finally here's how we construct and use the `Car` in a full example.
```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);
+ 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);
+ 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));
+ Property.MODEL.toString(), "300SL",
+ Property.PRICE.toString(), 10000L,
+ Property.PARTS.toString(), List.of(wheelProperties, doorProperties));
var car = new Car(carProperties);
@@ -149,27 +172,28 @@ And finally here's how we construct and use the `Car` in a full example.
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))
+ p.getType().orElse(null),
+ p.getModel().orElse(null),
+ p.getPrice().orElse(null))
);
-
- // Constructing parts and car
- // Here is our car:
- // model: 300SL
- // price: 10000
- // parts:
- // wheel/15C/100
- // door/Lambo/300
+}
```
-## Class diagram
+The program output:
-
+```
+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
+```
-## Applicability
+## When to Use the Abstract Document Pattern in Java
-This pattern is particularly useful in scenarios where you have different types of documents that share some common attributes or behaviors, but also have unique attributes or behaviors specific to their individual types. Here are some scenarios where the Abstract Document design pattern can be applicable:
+The Abstract Document design pattern is especially beneficial in scenarios requiring management of different document types in Java that share some common attributes or behaviors, but also have unique attributes or behaviors specific to their individual types. Here are some scenarios where the Abstract Document design pattern can be applicable:
* Content Management Systems (CMS): In a CMS, you might have various types of content such as articles, images, videos, etc. Each type of content could have shared attributes like creation date, author, and tags, while also having specific attributes like image dimensions for images or video duration for videos.
@@ -195,9 +219,9 @@ This pattern is particularly useful in scenarios where you have different types
The key idea behind the Abstract Document design pattern is to provide a flexible and extensible way to manage different types of documents or entities with shared and distinct attributes. By defining a common interface and implementing it across various document types, you can achieve a more organized and consistent approach to handling complex data structures.
-## Consequences
+## Benefits and Trade-offs of Abstract Document Pattern
-Benefits
+Benefits:
* Flexibility: Accommodates varied document structures and properties.
@@ -207,14 +231,17 @@ Benefits
* Reusability: Typed views enable code reuse for accessing specific attribute types.
-Trade-offs
+Trade-offs:
* Complexity: Requires defining interfaces and views, adding implementation overhead.
* Performance: Might introduce slight performance overhead compared to direct data access.
-## Credits
+## References and Credits
-* [Wikipedia: Abstract Document Pattern](https://en.wikipedia.org/wiki/Abstract_Document_Pattern)
-* [Martin Fowler: Dealing with properties](http://martinfowler.com/apsupp/properties.pdf)
+* [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/abstract-document/pom.xml b/abstract-document/pom.xml
index 2b7d58519edd..ef190e088d5e 100644
--- a/abstract-document/pom.xml
+++ b/abstract-document/pom.xml
@@ -34,6 +34,14 @@
abstract-document
+
+ org.slf4j
+ slf4j-api
+
+
+ ch.qos.logback
+ logback-classic
+ org.junit.jupiterjunit-jupiter-engine
diff --git a/abstract-document/src/main/java/com/iluwatar/abstractdocument/AbstractDocument.java b/abstract-document/src/main/java/com/iluwatar/abstractdocument/AbstractDocument.java
index 665729008810..ab5ccada1414 100644
--- a/abstract-document/src/main/java/com/iluwatar/abstractdocument/AbstractDocument.java
+++ b/abstract-document/src/main/java/com/iluwatar/abstractdocument/AbstractDocument.java
@@ -31,48 +31,71 @@
import java.util.function.Function;
import java.util.stream.Stream;
-/**
- * Abstract implementation of Document interface.
- */
+/** Abstract implementation of Document interface. */
public abstract class AbstractDocument implements Document {
- private final Map properties;
+ private final Map documentProperties;
protected AbstractDocument(Map properties) {
Objects.requireNonNull(properties, "properties map is required");
- this.properties = properties;
+ this.documentProperties = properties;
}
@Override
public Void put(String key, Object value) {
- properties.put(key, value);
+ documentProperties.put(key, value);
return null;
}
@Override
public Object get(String key) {
- return properties.get(key);
+ return documentProperties.get(key);
}
@Override
- public Stream children(String key, Function, T> constructor) {
+ public Stream children(String key, Function, T> childConstructor) {
return Stream.ofNullable(get(key))
.filter(Objects::nonNull)
.map(el -> (List>) el)
.findAny()
.stream()
.flatMap(Collection::stream)
- .map(constructor);
+ .map(childConstructor);
}
@Override
public String toString() {
+ return buildStringRepresentation();
+ }
+
+ private String buildStringRepresentation() {
var builder = new StringBuilder();
builder.append(getClass().getName()).append("[");
- properties.forEach((key, value) -> builder.append("[").append(key).append(" : ").append(value)
- .append("]"));
+
+ // Explaining variable for document properties map
+ Map documentProperties = this.documentProperties;
+
+ // Explaining variable for the size of document properties map
+ int numProperties = documentProperties.size();
+
+ // Explaining variable for tracking the current property index
+ int currentPropertyIndex = 0;
+
+ // Iterate over document properties map
+ for (Map.Entry entry : documentProperties.entrySet()) {
+ String key = entry.getKey();
+ Object value = entry.getValue();
+
+ // Append key-value pair
+ builder.append("[").append(key).append(" : ").append(value).append("]");
+
+ // Add comma if not last property
+ if (++currentPropertyIndex < numProperties) {
+ builder.append(", ");
+ }
+ }
+
builder.append("]");
return builder.toString();
}
-
}
diff --git a/abstract-document/src/main/java/com/iluwatar/abstractdocument/App.java b/abstract-document/src/main/java/com/iluwatar/abstractdocument/App.java
index 6775523efff7..607b4a7f7913 100644
--- a/abstract-document/src/main/java/com/iluwatar/abstractdocument/App.java
+++ b/abstract-document/src/main/java/com/iluwatar/abstractdocument/App.java
@@ -49,20 +49,26 @@ public class App {
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 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 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 carProperties =
+ Map.of(
+ Property.MODEL.toString(),
+ "300SL",
+ Property.PRICE.toString(),
+ 10000L,
+ Property.PARTS.toString(),
+ List.of(wheelProperties, doorProperties));
var car = new Car(carProperties);
@@ -70,10 +76,13 @@ public static void main(String[] args) {
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))
- );
+ car.getParts()
+ .forEach(
+ p ->
+ LOGGER.info(
+ "\t{}/{}/{}",
+ p.getType().orElse(null),
+ p.getModel().orElse(null),
+ p.getPrice().orElse(null)));
}
}
diff --git a/abstract-document/src/main/java/com/iluwatar/abstractdocument/Document.java b/abstract-document/src/main/java/com/iluwatar/abstractdocument/Document.java
index 198a543b5c04..79a51b610337 100644
--- a/abstract-document/src/main/java/com/iluwatar/abstractdocument/Document.java
+++ b/abstract-document/src/main/java/com/iluwatar/abstractdocument/Document.java
@@ -28,15 +28,13 @@
import java.util.function.Function;
import java.util.stream.Stream;
-/**
- * Document interface.
- */
+/** Document interface. */
public interface Document {
/**
* Puts the value related to the key.
*
- * @param key element key
+ * @param key element key
* @param value element value
* @return Void
*/
@@ -53,7 +51,7 @@ public interface Document {
/**
* Gets the stream of child documents.
*
- * @param key element key
+ * @param key element key
* @param constructor constructor of child class
* @return child documents
*/
diff --git a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/Car.java b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/Car.java
index 6b7bbcf5246e..93fbbb9c1eae 100644
--- a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/Car.java
+++ b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/Car.java
@@ -27,13 +27,10 @@
import com.iluwatar.abstractdocument.AbstractDocument;
import java.util.Map;
-/**
- * Car entity.
- */
+/** Car entity. */
public class Car extends AbstractDocument implements HasModel, HasPrice, HasParts {
public Car(Map properties) {
super(properties);
}
-
}
diff --git a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasModel.java b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasModel.java
index 008f5a257bb6..6f517588e5a0 100644
--- a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasModel.java
+++ b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasModel.java
@@ -28,13 +28,10 @@
import com.iluwatar.abstractdocument.domain.enums.Property;
import java.util.Optional;
-/**
- * HasModel trait for static access to 'model' property.
- */
+/** HasModel trait for static access to 'model' property. */
public interface HasModel extends Document {
default Optional getModel() {
return Optional.ofNullable((String) get(Property.MODEL.toString()));
}
-
}
diff --git a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasParts.java b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasParts.java
index 5dee245d1560..8bffa753e6ef 100644
--- a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasParts.java
+++ b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasParts.java
@@ -28,13 +28,10 @@
import com.iluwatar.abstractdocument.domain.enums.Property;
import java.util.stream.Stream;
-/**
- * HasParts trait for static access to 'parts' property.
- */
+/** HasParts trait for static access to 'parts' property. */
public interface HasParts extends Document {
default Stream getParts() {
return children(Property.PARTS.toString(), Part::new);
}
-
}
diff --git a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasPrice.java b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasPrice.java
index db985dfba333..ce876e5faf54 100644
--- a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasPrice.java
+++ b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasPrice.java
@@ -28,13 +28,10 @@
import com.iluwatar.abstractdocument.domain.enums.Property;
import java.util.Optional;
-/**
- * HasPrice trait for static access to 'price' property.
- */
+/** HasPrice trait for static access to 'price' property. */
public interface HasPrice extends Document {
default Optional getPrice() {
return Optional.ofNullable((Number) get(Property.PRICE.toString()));
}
-
}
diff --git a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasType.java b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasType.java
index bd83adecb058..5e0f49df7b7b 100644
--- a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasType.java
+++ b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/HasType.java
@@ -28,13 +28,10 @@
import com.iluwatar.abstractdocument.domain.enums.Property;
import java.util.Optional;
-/**
- * HasType trait for static access to 'type' property.
- */
+/** HasType trait for static access to 'type' property. */
public interface HasType extends Document {
default Optional getType() {
return Optional.ofNullable((String) get(Property.TYPE.toString()));
}
-
}
diff --git a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/Part.java b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/Part.java
index 9aa46be15e41..6eec08b0d2a4 100644
--- a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/Part.java
+++ b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/Part.java
@@ -27,13 +27,10 @@
import com.iluwatar.abstractdocument.AbstractDocument;
import java.util.Map;
-/**
- * Part entity.
- */
+/** Part entity. */
public class Part extends AbstractDocument implements HasType, HasModel, HasPrice {
public Part(Map properties) {
super(properties);
}
-
}
diff --git a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/enums/Property.java b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/enums/Property.java
index 3aa97ba84f65..3e0d6d10ab1f 100644
--- a/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/enums/Property.java
+++ b/abstract-document/src/main/java/com/iluwatar/abstractdocument/domain/enums/Property.java
@@ -24,10 +24,10 @@
*/
package com.iluwatar.abstractdocument.domain.enums;
-/**
- * Enum To Describe Property type.
- */
+/** Enum To Describe Property type. */
public enum Property {
-
- PARTS, TYPE, PRICE, MODEL
+ PARTS,
+ TYPE,
+ PRICE,
+ MODEL
}
diff --git a/abstract-document/src/test/java/com/iluwatar/abstractdocument/AbstractDocumentTest.java b/abstract-document/src/test/java/com/iluwatar/abstractdocument/AbstractDocumentTest.java
index 249f01f64a1e..a098517c3a69 100644
--- a/abstract-document/src/test/java/com/iluwatar/abstractdocument/AbstractDocumentTest.java
+++ b/abstract-document/src/test/java/com/iluwatar/abstractdocument/AbstractDocumentTest.java
@@ -24,16 +24,14 @@
*/
package com.iluwatar.abstractdocument;
-import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
import java.util.HashMap;
import java.util.List;
import java.util.Map;
+import org.junit.jupiter.api.Test;
-import static org.junit.jupiter.api.Assertions.*;
-
-/**
- * AbstractDocument test class
- */
+/** AbstractDocument test class */
class AbstractDocumentTest {
private static final String KEY = "key";
@@ -80,4 +78,53 @@ void shouldIncludePropsInToString() {
assertTrue(document.toString().contains(VALUE));
}
+ @Test
+ void shouldHandleExceptionDuringConstruction() {
+ Map invalidProperties =
+ null; // Invalid properties, causing NullPointerException
+
+ // Throw null pointer exception
+ assertThrows(
+ NullPointerException.class,
+ () -> {
+ // Attempt to construct a document with invalid properties
+ new DocumentImplementation(invalidProperties);
+ });
+ }
+
+ @Test
+ void shouldPutAndGetNestedDocument() {
+ // Creating a nested document
+ DocumentImplementation nestedDocument = new DocumentImplementation(new HashMap<>());
+ nestedDocument.put("nestedKey", "nestedValue");
+
+ document.put("nested", nestedDocument);
+
+ // Retrieving the nested document
+ DocumentImplementation retrievedNestedDocument =
+ (DocumentImplementation) document.get("nested");
+
+ assertNotNull(retrievedNestedDocument);
+ assertEquals("nestedValue", retrievedNestedDocument.get("nestedKey"));
+ }
+
+ @Test
+ void shouldUpdateExistingValue() {
+ // Arrange
+ final String key = "key";
+ final String originalValue = "originalValue";
+ final String updatedValue = "updatedValue";
+
+ // Initializing the value
+ document.put(key, originalValue);
+
+ // Verifying that the initial value is retrieved correctly
+ assertEquals(originalValue, document.get(key));
+
+ // Updating the value
+ document.put(key, updatedValue);
+
+ // Verifying that the updated value is retrieved correctly
+ assertEquals(updatedValue, document.get(key));
+ }
}
diff --git a/abstract-document/src/test/java/com/iluwatar/abstractdocument/AppTest.java b/abstract-document/src/test/java/com/iluwatar/abstractdocument/AppTest.java
index 09af6d7b5260..16dcba0db37f 100644
--- a/abstract-document/src/test/java/com/iluwatar/abstractdocument/AppTest.java
+++ b/abstract-document/src/test/java/com/iluwatar/abstractdocument/AppTest.java
@@ -24,25 +24,21 @@
*/
package com.iluwatar.abstractdocument;
-import org.junit.jupiter.api.Test;
-
import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
-/**
- * Simple App test
- */
+import org.junit.jupiter.api.Test;
+
+/** Simple App test */
class AppTest {
/**
* Issue: Add at least one assertion to this test case.
*
- * Solution: Inserted assertion to check whether the execution of the main method in {@link App}
- * throws an exception.
+ *
Solution: Inserted assertion to check whether the execution of the main method in {@link
+ * App} throws an exception.
*/
-
@Test
void shouldExecuteAppWithoutException() {
assertDoesNotThrow(() -> App.main(null));
}
-
}
diff --git a/abstract-document/src/test/java/com/iluwatar/abstractdocument/DomainTest.java b/abstract-document/src/test/java/com/iluwatar/abstractdocument/DomainTest.java
index 4b52fa7a6ac4..fc29dea45c43 100644
--- a/abstract-document/src/test/java/com/iluwatar/abstractdocument/DomainTest.java
+++ b/abstract-document/src/test/java/com/iluwatar/abstractdocument/DomainTest.java
@@ -24,18 +24,16 @@
*/
package com.iluwatar.abstractdocument;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
import com.iluwatar.abstractdocument.domain.Car;
import com.iluwatar.abstractdocument.domain.Part;
import com.iluwatar.abstractdocument.domain.enums.Property;
-import org.junit.jupiter.api.Test;
import java.util.List;
import java.util.Map;
+import org.junit.jupiter.api.Test;
-import static org.junit.jupiter.api.Assertions.assertEquals;
-
-/**
- * Test for Part and Car
- */
+/** Test for Part and Car */
class DomainTest {
private static final String TEST_PART_TYPE = "test-part-type";
@@ -47,11 +45,11 @@ class DomainTest {
@Test
void shouldConstructPart() {
- var partProperties = Map.of(
- Property.TYPE.toString(), TEST_PART_TYPE,
- Property.MODEL.toString(), TEST_PART_MODEL,
- Property.PRICE.toString(), (Object) TEST_PART_PRICE
- );
+ var partProperties =
+ Map.of(
+ Property.TYPE.toString(), TEST_PART_TYPE,
+ Property.MODEL.toString(), TEST_PART_MODEL,
+ Property.PRICE.toString(), (Object) TEST_PART_PRICE);
var part = new Part(partProperties);
assertEquals(TEST_PART_TYPE, part.getType().orElseThrow());
assertEquals(TEST_PART_MODEL, part.getModel().orElseThrow());
@@ -60,15 +58,14 @@ void shouldConstructPart() {
@Test
void shouldConstructCar() {
- var carProperties = Map.of(
- Property.MODEL.toString(), TEST_CAR_MODEL,
- Property.PRICE.toString(), TEST_CAR_PRICE,
- Property.PARTS.toString(), List.of(Map.of(), Map.of())
- );
+ var carProperties =
+ Map.of(
+ Property.MODEL.toString(), TEST_CAR_MODEL,
+ Property.PRICE.toString(), TEST_CAR_PRICE,
+ Property.PARTS.toString(), List.of(Map.of(), Map.of()));
var car = new Car(carProperties);
assertEquals(TEST_CAR_MODEL, car.getModel().orElseThrow());
assertEquals(TEST_CAR_PRICE, car.getPrice().orElseThrow());
assertEquals(2, car.getParts().count());
}
-
}
diff --git a/abstract-factory/README.md b/abstract-factory/README.md
index 4d5ff98a2165..ee9823a39a5f 100644
--- a/abstract-factory/README.md
+++ b/abstract-factory/README.md
@@ -1,26 +1,32 @@
---
-title: Abstract Factory
+title: "Abstract Factory Pattern in Java: Mastering Object Creation Elegantly"
+shortTitle: Abstract Factory
+description: "Learn the Abstract Factory pattern in Java with real-world examples, class diagrams, and tutorials. Understand its intent, applicability, benefits, and known uses to enhance your design pattern knowledge."
category: Creational
language: en
tag:
- - Abstraction
- - Decoupling
- - Gang of Four
+ - Abstraction
+ - Decoupling
+ - Gang of Four
+ - Instantiation
+ - Polymorphism
---
## Also known as
-Kit
+* Kit
-## Intent
+## Intent of Abstract Factory Design Pattern
-The Abstract Factory design pattern provides a way to create families of related objects without specifying their concrete classes. This allows for code that is independent of the specific classes of objects it uses, promoting flexibility and maintainability.
+The Abstract Factory pattern in Java provides an interface for creating families of related or dependent objects without specifying their concrete classes, enhancing modularity and flexibility in software design.
-## Explanation
+## Detailed Explanation of Abstract Factory Pattern with Real-World Examples
Real-world example
-> To create a kingdom we need objects with a common theme. The elven kingdom needs an elven king, elven castle, and elven army whereas the orcish kingdom needs an orcish king, orcish castle, and orcish army. There is a dependency between the objects in the kingdom.
+> Imagine a furniture company that uses the Abstract Factory pattern in Java to produce various styles of furniture: modern, Victorian, and rustic. Each style includes products like chairs, tables, and sofas. To ensure consistency within each style, the company uses an Abstract Factory pattern.
+>
+> In this scenario, the Abstract Factory is an interface for creating families of related furniture objects (chairs, tables, sofas). Each concrete factory (ModernFurnitureFactory, VictorianFurnitureFactory, RusticFurnitureFactory) implements the Abstract Factory interface and creates a set of products that match the specific style. This way, clients can create a whole set of modern or Victorian furniture without worrying about the details of their instantiation. This maintains a consistent style and allows easy swapping of one style of furniture for another.
In plain words
@@ -30,115 +36,90 @@ Wikipedia says
> The abstract factory pattern provides a way to encapsulate a group of individual factories that have a common theme without specifying their concrete classes
-**Programmatic Example**
+Class diagram
+
+
+
+## Programmatic Example of Abstract Factory in Java
+
+To create a kingdom using the Abstract Factory pattern in Java, we need objects with a common theme. The elven kingdom needs an elven king, elven castle, and elven army whereas the orcish kingdom needs an orcish king, orcish castle, and orcish army. There is a dependency between the objects in the kingdom.
Translating the kingdom example above. First of all, we have some interfaces and implementation for the objects in the kingdom.
```java
public interface Castle {
- String getDescription();
+ String getDescription();
}
public interface King {
- String getDescription();
+ String getDescription();
}
public interface Army {
- String getDescription();
+ String getDescription();
}
// Elven implementations ->
public class ElfCastle implements Castle {
- static final String DESCRIPTION = "This is the elven castle!";
- @Override
- public String getDescription() {
- return DESCRIPTION;
- }
+ static final String DESCRIPTION = "This is the elven castle!";
+
+ @Override
+ public String getDescription() {
+ return DESCRIPTION;
+ }
}
+
public class ElfKing implements King {
- static final String DESCRIPTION = "This is the elven king!";
- @Override
- public String getDescription() {
- return DESCRIPTION;
- }
+ static final String DESCRIPTION = "This is the elven king!";
+
+ @Override
+ public String getDescription() {
+ return DESCRIPTION;
+ }
}
+
public class ElfArmy implements Army {
- static final String DESCRIPTION = "This is the elven Army!";
- @Override
- public String getDescription() {
- return DESCRIPTION;
- }
+ static final String DESCRIPTION = "This is the elven Army!";
+
+ @Override
+ public String getDescription() {
+ return DESCRIPTION;
+ }
}
// Orcish implementations similarly -> ...
-
```
Then we have the abstraction and implementations for the kingdom factory.
```java
public interface KingdomFactory {
- Castle createCastle();
- King createKing();
- Army createArmy();
-}
+ Castle createCastle();
-public class ElfKingdomFactory implements KingdomFactory {
+ King createKing();
- @Override
- public Castle createCastle() {
- return new ElfCastle();
- }
-
- @Override
- public King createKing() {
- return new ElfKing();
- }
-
- @Override
- public Army createArmy() {
- return new ElfArmy();
- }
+ Army createArmy();
}
-public class OrcKingdomFactory implements KingdomFactory {
-
- @Override
- public Castle createCastle() {
- return new OrcCastle();
- }
-
- @Override
- public King createKing() {
- return new OrcKing();
- }
-
- @Override
- public Army createArmy() {
- return new OrcArmy();
- }
-}
-```
+public class ElfKingdomFactory implements KingdomFactory {
-Now we have the abstract factory that lets us make a family of related objects i.e. elven kingdom factory creates elven castle, king and army, etc.
+ @Override
+ public Castle createCastle() {
+ return new ElfCastle();
+ }
-```java
-var factory = new ElfKingdomFactory();
-var castle = factory.createCastle();
-var king = factory.createKing();
-var army = factory.createArmy();
-
-castle.getDescription();
-king.getDescription();
-army.getDescription();
-```
+ @Override
+ public King createKing() {
+ return new ElfKing();
+ }
-Program output:
+ @Override
+ public Army createArmy() {
+ return new ElfArmy();
+ }
+}
-```java
-This is the elven castle!
-This is the elven king!
-This is the elven Army!
+// Orcish implementations similarly -> ...
```
Now, we can design a factory for our different kingdom factories. In this example, we created `FactoryMaker`, responsible for returning an instance of either `ElfKingdomFactory` or `OrcKingdomFactory`. The client can use `FactoryMaker` to create the desired concrete factory which, in turn, will produce different concrete objects (derived from `Army`, `King`, `Castle`). In this example, we also used an enum to parameterize which type of kingdom factory the client will ask for.
@@ -157,51 +138,58 @@ public static class FactoryMaker {
};
}
}
+```
- public static void main(String[] args) {
- var app = new App();
-
- LOGGER.info("Elf Kingdom");
- app.createKingdom(FactoryMaker.makeFactory(KingdomType.ELF));
- LOGGER.info(app.getArmy().getDescription());
- LOGGER.info(app.getCastle().getDescription());
- LOGGER.info(app.getKing().getDescription());
+Here is the main function of our example application:
- LOGGER.info("Orc Kingdom");
- app.createKingdom(FactoryMaker.makeFactory(KingdomType.ORC));
- --similar use of the orc factory
- }
+```java
+LOGGER.info("elf kingdom");
+createKingdom(Kingdom.FactoryMaker.KingdomType.ELF);
+LOGGER.info(kingdom.getArmy().getDescription());
+LOGGER.info(kingdom.getCastle().getDescription());
+LOGGER.info(kingdom.getKing().getDescription());
+
+LOGGER.info("orc kingdom");
+createKingdom(Kingdom.FactoryMaker.KingdomType.ORC);
+LOGGER.info(kingdom.getArmy().getDescription());
+LOGGER.info(kingdom.getCastle().getDescription());
+LOGGER.info(kingdom.getKing().getDescription());
```
-## Class diagram
-
-
+The program output:
+```
+07:35:46.340 [main] INFO com.iluwatar.abstractfactory.App -- elf kingdom
+07:35:46.343 [main] INFO com.iluwatar.abstractfactory.App -- This is the elven army!
+07:35:46.343 [main] INFO com.iluwatar.abstractfactory.App -- This is the elven castle!
+07:35:46.343 [main] INFO com.iluwatar.abstractfactory.App -- This is the elven king!
+07:35:46.343 [main] INFO com.iluwatar.abstractfactory.App -- orc kingdom
+07:35:46.343 [main] INFO com.iluwatar.abstractfactory.App -- This is the orc army!
+07:35:46.343 [main] INFO com.iluwatar.abstractfactory.App -- This is the orc castle!
+07:35:46.343 [main] INFO com.iluwatar.abstractfactory.App -- This is the orc king!
+```
-## Applicability
+## When to Use the Abstract Factory Pattern in Java
-Use the Abstract Factory pattern when
+Use the Abstract Factory pattern in Java when:
-* The system should be independent of how its products are created, composed, and represented
-* The system should be configured with one of the multiple families of products
-* The family of related product objects is designed to be used together, and you need to enforce this constraint
-* You want to provide a class library of products, and you want to reveal just their interfaces, not their implementations
-* The lifetime of the dependency is conceptually shorter than the lifetime of the consumer.
-* You need a run-time value to construct a particular dependency
-* You want to decide which product to call from a family at runtime.
-* You need to supply one or more parameters only known at run-time before you can resolve a dependency.
-* When you need consistency among products
-* You don’t want to change existing code when adding new products or families of products to the program.
+* The system should be independent of how its products are created, composed, and represented.
+* You need to configure the system with one of multiple families of products.
+* A family of related product objects must be used together, enforcing consistency.
+* You want to provide a class library of products, exposing only their interfaces, not their implementations.
+* The lifetime of dependencies is shorter than the consumer's lifetime.
+* Dependencies need to be constructed using runtime values or parameters.
+* You need to choose which product to use from a family at runtime.
+* Adding new products or families should not require changes to existing code.
-Example use cases
+## Abstract Factory Pattern Java Tutorials
-* Selecting to call to the appropriate implementation of FileSystemAcmeService or DatabaseAcmeService or NetworkAcmeService at runtime.
-* Unit test case writing becomes much easier
-* UI tools for different OS
+* [Abstract Factory Design Pattern in Java (DigitalOcean)](https://www.digitalocean.com/community/tutorials/abstract-factory-design-pattern-in-java)
+* [Abstract Factory(Refactoring Guru)](https://refactoring.guru/design-patterns/abstract-factory)
-## Consequences
+## Benefits and Trade-offs of Abstract Factory Pattern
-Benefits
+Benefits:
* Flexibility: Easily switch between product families without code modifications.
@@ -211,31 +199,29 @@ Benefits
* Maintainability: Changes to individual product families are localized, simplifying updates.
-Trade-offs
+Trade-offs:
* Complexity: Defining abstract interfaces and concrete factories adds initial overhead.
* Indirectness: Client code interacts with products indirectly through factories, potentially reducing transparency.
-## Tutorials
-
-* [Abstract Factory Pattern Tutorial](https://www.journaldev.com/1418/abstract-factory-design-pattern-in-java)
-* [Refactoring Guru - Abstract Factory](https://refactoring.guru/design-patterns/abstract-factory)
-
-## Known uses
+## Real-World Applications of Abstract Factory Pattern in Java
+* Java Swing's `LookAndFeel` classes for providing different look-and-feel options.
+* Various implementations in the Java Abstract Window Toolkit (AWT) for creating different GUI components.
* [javax.xml.parsers.DocumentBuilderFactory](http://docs.oracle.com/javase/8/docs/api/javax/xml/parsers/DocumentBuilderFactory.html)
* [javax.xml.transform.TransformerFactory](http://docs.oracle.com/javase/8/docs/api/javax/xml/transform/TransformerFactory.html#newInstance--)
* [javax.xml.xpath.XPathFactory](http://docs.oracle.com/javase/8/docs/api/javax/xml/xpath/XPathFactory.html#newInstance--)
-## Related patterns
+## Related Java Design Patterns
-* [Factory Method](https://java-design-patterns.com/patterns/factory-method/)
-* [Factory Kit](https://java-design-patterns.com/patterns/factory-kit/)
+* [Factory Method](https://java-design-patterns.com/patterns/factory-method/): Abstract Factory uses Factory Methods to create products.
+* [Singleton](https://java-design-patterns.com/patterns/singleton/): Abstract Factory classes are often implemented as Singletons.
+* [Factory Kit](https://java-design-patterns.com/patterns/factory-kit/): Similar to Abstract Factory but focuses on configuring and managing a set of related objects in a flexible way.
-## Credits
+## References and Credits
-* [Design Patterns: Elements of Reusable Object-Oriented Software](https://www.amazon.com/gp/product/0201633612/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=0201633612&linkCode=as2&tag=javadesignpat-20&linkId=675d49790ce11db99d90bde47f1aeb59)
-* [Head First Design Patterns: A Brain-Friendly Guide](https://www.amazon.com/gp/product/0596007124/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=0596007124&linkCode=as2&tag=javadesignpat-20&linkId=6b8b6eea86021af6c8e3cd3fc382cb5b)
+* [Design Patterns: Elements of Reusable Object-Oriented Software](https://amzn.to/3w0pvKI)
+* [Design Patterns in Java](https://amzn.to/3Syw0vC)
+* [Head First Design Patterns: Building Extensible and Maintainable Object-Oriented Software](https://amzn.to/49NGldq)
* [Java Design Patterns: A Hands-On Experience with Real-World Examples](https://amzn.to/3HWNf4U)
-* [Design Patterns in Java](https://amzn.to/3Syw0vC)
\ No newline at end of file
diff --git a/abstract-factory/pom.xml b/abstract-factory/pom.xml
index 99a92423beae..60fbf72eff54 100644
--- a/abstract-factory/pom.xml
+++ b/abstract-factory/pom.xml
@@ -34,6 +34,14 @@
abstract-factory
+
+ org.slf4j
+ slf4j-api
+
+
+ ch.qos.logback
+ logback-classic
+ org.junit.jupiterjunit-jupiter-engine
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/App.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/App.java
index e360822ca147..798cbe4fd118 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/App.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/App.java
@@ -74,6 +74,7 @@ public void run() {
/**
* Creates kingdom.
+ *
* @param kingdomType type of Kingdom
*/
public void createKingdom(final Kingdom.FactoryMaker.KingdomType kingdomType) {
@@ -82,4 +83,4 @@ public void createKingdom(final Kingdom.FactoryMaker.KingdomType kingdomType) {
kingdom.setCastle(kingdomFactory.createCastle());
kingdom.setArmy(kingdomFactory.createArmy());
}
-}
\ No newline at end of file
+}
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Army.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Army.java
index 3efec4c87eb1..78c75323f1c0 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Army.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Army.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * Army interface.
- */
+/** Army interface. */
public interface Army {
String getDescription();
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Castle.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Castle.java
index 8fca068199cb..ee1e16f3cd3f 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Castle.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Castle.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * Castle interface.
- */
+/** Castle interface. */
public interface Castle {
String getDescription();
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfArmy.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfArmy.java
index 055d2cc75b0c..d7e46c1456f0 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfArmy.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfArmy.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * ElfArmy.
- */
+/** ElfArmy. */
public class ElfArmy implements Army {
static final String DESCRIPTION = "This is the elven army!";
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfCastle.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfCastle.java
index 5b0c26c4290d..136afb11fd23 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfCastle.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfCastle.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * ElfCastle.
- */
+/** ElfCastle. */
public class ElfCastle implements Castle {
static final String DESCRIPTION = "This is the elven castle!";
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfKing.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfKing.java
index 0696e1d096f9..9b0d3a6f1a77 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfKing.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfKing.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * ElfKing.
- */
+/** ElfKing. */
public class ElfKing implements King {
static final String DESCRIPTION = "This is the elven king!";
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfKingdomFactory.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfKingdomFactory.java
index f45d2ee036c1..b09a2f47c252 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfKingdomFactory.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/ElfKingdomFactory.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * ElfKingdomFactory concrete factory.
- */
+/** ElfKingdomFactory concrete factory. */
public class ElfKingdomFactory implements KingdomFactory {
@Override
@@ -43,5 +41,4 @@ public King createKing() {
public Army createArmy() {
return new ElfArmy();
}
-
}
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/King.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/King.java
index 01af71a6a293..9f65ed434577 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/King.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/King.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * King interface.
- */
+/** King interface. */
public interface King {
String getDescription();
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Kingdom.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Kingdom.java
index db1c65ca46de..d1f85a6a4812 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Kingdom.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/Kingdom.java
@@ -27,9 +27,7 @@
import lombok.Getter;
import lombok.Setter;
-/**
- * Helper class to manufacture {@link KingdomFactory} beans.
- */
+/** Helper class to manufacture {@link KingdomFactory} beans. */
@Getter
@Setter
public class Kingdom {
@@ -38,21 +36,16 @@ public class Kingdom {
private Castle castle;
private Army army;
- /**
- * The factory of kingdom factories.
- */
+ /** The factory of kingdom factories. */
public static class FactoryMaker {
- /**
- * Enumeration for the different types of Kingdoms.
- */
+ /** Enumeration for the different types of Kingdoms. */
public enum KingdomType {
- ELF, ORC
+ ELF,
+ ORC
}
- /**
- * The factory method to create KingdomFactory concrete objects.
- */
+ /** The factory method to create KingdomFactory concrete objects. */
public static KingdomFactory makeFactory(KingdomType type) {
return switch (type) {
case ELF -> new ElfKingdomFactory();
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/KingdomFactory.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/KingdomFactory.java
index fdfe19dc08d2..199c6697dcaa 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/KingdomFactory.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/KingdomFactory.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * KingdomFactory factory interface.
- */
+/** KingdomFactory factory interface. */
public interface KingdomFactory {
Castle createCastle();
@@ -34,5 +32,4 @@ public interface KingdomFactory {
King createKing();
Army createArmy();
-
}
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcArmy.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcArmy.java
index d687c32e8c27..31ed6896d921 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcArmy.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcArmy.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * OrcArmy.
- */
+/** OrcArmy. */
public class OrcArmy implements Army {
static final String DESCRIPTION = "This is the orc army!";
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcCastle.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcCastle.java
index f842bb3c62d0..bdae5709a97c 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcCastle.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcCastle.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * OrcCastle.
- */
+/** OrcCastle. */
public class OrcCastle implements Castle {
static final String DESCRIPTION = "This is the orc castle!";
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcKing.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcKing.java
index e25d93bfba40..7f106d45a01d 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcKing.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcKing.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * OrcKing.
- */
+/** OrcKing. */
public class OrcKing implements King {
static final String DESCRIPTION = "This is the orc king!";
diff --git a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcKingdomFactory.java b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcKingdomFactory.java
index c80728a87fdc..82d258570460 100644
--- a/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcKingdomFactory.java
+++ b/abstract-factory/src/main/java/com/iluwatar/abstractfactory/OrcKingdomFactory.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.abstractfactory;
-/**
- * OrcKingdomFactory concrete factory.
- */
+/** OrcKingdomFactory concrete factory. */
public class OrcKingdomFactory implements KingdomFactory {
@Override
diff --git a/abstract-factory/src/test/java/com/iluwatar/abstractfactory/AbstractFactoryTest.java b/abstract-factory/src/test/java/com/iluwatar/abstractfactory/AbstractFactoryTest.java
index 0f7708e07a12..b5dde940c464 100644
--- a/abstract-factory/src/test/java/com/iluwatar/abstractfactory/AbstractFactoryTest.java
+++ b/abstract-factory/src/test/java/com/iluwatar/abstractfactory/AbstractFactoryTest.java
@@ -24,14 +24,12 @@
*/
package com.iluwatar.abstractfactory;
-import org.junit.jupiter.api.Test;
-
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
-/**
- * Tests for abstract factory.
- */
+import org.junit.jupiter.api.Test;
+
+/** Tests for abstract factory. */
class AbstractFactoryTest {
private final App app = new App();
diff --git a/abstract-factory/src/test/java/com/iluwatar/abstractfactory/AppTest.java b/abstract-factory/src/test/java/com/iluwatar/abstractfactory/AppTest.java
index 736a7f8b740f..9f53691a594d 100644
--- a/abstract-factory/src/test/java/com/iluwatar/abstractfactory/AppTest.java
+++ b/abstract-factory/src/test/java/com/iluwatar/abstractfactory/AppTest.java
@@ -24,18 +24,16 @@
*/
package com.iluwatar.abstractfactory;
-import org.junit.jupiter.api.Test;
-
import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
-/**
- * Check whether the execution of the main method in {@link App} throws an exception.
- */
+import org.junit.jupiter.api.Test;
+
+/** Check whether the execution of the main method in {@link App} throws an exception. */
class AppTest {
-
+
@Test
void shouldExecuteApplicationWithoutException() {
- assertDoesNotThrow(() -> App.main(new String[]{}));
+ assertDoesNotThrow(() -> App.main(new String[] {}));
}
}
diff --git a/active-object/README.md b/active-object/README.md
index 26e3e816af7f..a804ce9e632b 100644
--- a/active-object/README.md
+++ b/active-object/README.md
@@ -1,163 +1,222 @@
---
-title: Active Object
+title: "Active Object Pattern in Java: Achieving Efficient Asynchronous Processing"
+shortTitle: Active Object
+description: "Learn about the Active Object design pattern in Java. This guide covers asynchronous behavior, concurrency, and practical examples to enhance your Java applications' performance."
category: Concurrency
language: en
tag:
- - Performance
+ - Asynchronous
+ - Decoupling
+ - Messaging
+ - Synchronization
+ - Thread management
---
+## Intent of Active Object Design Pattern
-## Intent
+The Active Object pattern provides a reliable method for asynchronous processing in Java, ensuring responsive applications and efficient thread management. It achieves this by encapsulating tasks within objects that have their own thread and message queue. This separation keeps the main thread responsive and avoids issues like direct thread manipulation or shared state access.
-The Active Object design pattern provides a safe and reliable way to implement asynchronous behavior in concurrent systems. It achieves this by encapsulating tasks within objects that have their own thread and message queue. This separation keeps the main thread responsive and avoids issues like direct thread manipulation or shared state access.
+## Detailed Explanation of Active Object Pattern with Real-World Examples
-## Explanation
+Real-world example
-The class that implements the active object pattern will contain a self-synchronization mechanism without using 'synchronized' methods.
+> Imagine a busy restaurant where customers place orders with waiters. Instead of the waiters going to the kitchen to prepare the food themselves, they write the orders on slips and hand them to a dispatcher. The dispatcher manages a pool of chefs who prepare the meals asynchronously. Once a chef is free, they pick up the next order from the queue, prepare the dish, and notify the waiter when it's ready for serving.
+>
+> In this analogy, the waiters represent the client threads, the dispatcher represents the scheduler, and the chefs represent the method execution in separate threads. This setup allows the waiters to continue taking orders without being blocked by the food preparation process, much like the Active Object pattern decouples method invocation from execution to enhance concurrency.
-Real-world example
+In plain words
+
+> The Active Object pattern decouples method execution from method invocation to improve concurrency and responsiveness in multithreaded applications.
+
+Wikipedia says
+
+> The active object design pattern decouples method execution from method invocation for objects that each reside in their own thread of control.[1] The goal is to introduce concurrency, by using asynchronous method invocation and a scheduler for handling requests.
+>
+> The pattern consists of six elements:
+>
+> * A proxy, which provides an interface towards clients with publicly accessible methods.
+> * An interface which defines the method request on an active object.
+> * A list of pending requests from clients.
+> * A scheduler, which decides which request to execute next.
+> * The implementation of the active object method.
+> * A callback or variable for the client to receive the result.
->The Orcs are known for their wildness and untameable soul. It seems like they have their own thread of control based on previous behavior.
+Sequence diagram
-To implement a creature that has its own thread of control mechanism and expose its API only and not the execution itself, we can use the Active Object pattern.
+
-**Programmatic Example**
+## Programmatic Example of Active Object in Java
+
+This section explains how the Active Object design pattern works in Java, highlighting its use in asynchronous task management and concurrency control.
+
+The Orcs are known for their wildness and untameable soul. It seems like they have their own thread of control based on previous behavior. To implement a creature that has its own thread of control mechanism and expose its API only and not the execution itself, we can use the Active Object pattern.
```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());
+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;
- }
+ );
+ 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;
+ }
}
```
-We can see that any class that will extend the ActiveCreature class will have its own thread of control to invoke and execute methods.
+We can see that any class that will extend the `ActiveCreature` class will have its own thread of control to invoke and execute methods.
-For example, the Orc class:
+For example, the `Orc` class:
```java
public class Orc extends ActiveCreature {
- public Orc(String name) {
- super(name);
- }
-
+ public Orc(String name) {
+ super(name);
+ }
}
```
-Now, we can create multiple creatures such as Orcs, tell them to eat and roam, and they will execute it on their own thread of control:
+Now, we can create multiple creatures such as orcs, tell them to eat and roam, and they will execute it on their own thread of control:
```java
- public static void main(String[] args) {
- var app = new App();
- app.run();
- }
-
- @Override
- public void run() {
- ActiveCreature creature;
- try {
- for (int i = 0;i < creatures;i++) {
- creature = new Orc(Orc.class.getSimpleName().toString() + i);
- creature.eat();
- creature.roam();
- }
- Thread.sleep(1000);
- } catch (InterruptedException e) {
- logger.error(e.getMessage());
+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);
+ }
+ }
}
- Runtime.getRuntime().exit(1);
- }
+}
```
-## Class diagram
+Program output:
+
+```
+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.
+```
-
+## When to Use the Active Object Pattern in Java
-## Applicability
+Use the Active Object pattern in Java when:
-* When you need to perform long-running operations without blocking the main thread.
+* when you need to handle asynchronous tasks without blocking the main thread, ensuring better performance and responsiveness.
* When you need to interact with external resources asynchronously.
* When you want to improve the responsiveness of your application.
* When you need to manage concurrent tasks in a modular and maintainable way.
-## Tutorials
+## Active Object Pattern Java Tutorials
+
+* [Android and Java Concurrency: The Active Object Pattern(Douglas Schmidt)](https://www.youtube.com/watch?v=Cd8t2u5Qmvc)
+
+## Real-World Applications of Active Object Pattern in Java
+
+* Real-time trading systems where transaction requests are handled asynchronously.
+* GUIs where long-running tasks are executed in the background without freezing the user interface.
+* Game programming to handle concurrent updates to game state or AI computations.
-* [Android and Java Concurrency: The Active Object Pattern](https://www.youtube.com/watch?v=Cd8t2u5Qmvc)
+## Benefits and Trade-offs of Active Object Pattern
-## Consequences
+Discover the benefits and trade-offs of using the Active Object pattern in Java, including improved thread safety and potential overhead concerns.
-Benefits
+Benefits:
* Improves responsiveness of the main thread.
* Encapsulates concurrency concerns within objects.
* Promotes better code organization and maintainability.
* Provides thread safety and avoids shared state access problems.
-Trade-offs
+Trade-offs:
* Introduces additional overhead due to message passing and thread management.
* May not be suitable for all types of concurrency problems.
-## Related patterns
+## Related Java Design Patterns
-* Observer
-* Reactor
-* Producer-consumer
-* Thread pool
+* [Command](https://java-design-patterns.com/patterns/command/): Encapsulates a request as an object, similarly to how the Active Object pattern encapsulates method calls.
+* [Promise](https://java-design-patterns.com/patterns/promise/): Provides a means to retrieve the result of an asynchronous method call, often used in conjunction with Active Object.
+* [Proxy](https://java-design-patterns.com/patterns/proxy/): The Active Object pattern can use a proxy to handle method invocations asynchronously.
-## Credits
+## References and Credits
* [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/active-object/etc/active-object-sequence-diagram.png b/active-object/etc/active-object-sequence-diagram.png
new file mode 100644
index 000000000000..b725d9b07b6d
Binary files /dev/null and b/active-object/etc/active-object-sequence-diagram.png differ
diff --git a/active-object/pom.xml b/active-object/pom.xml
index 08a09e6642e8..aa26dbbe2e48 100644
--- a/active-object/pom.xml
+++ b/active-object/pom.xml
@@ -34,6 +34,14 @@
active-object
+
+ org.slf4j
+ slf4j-api
+
+
+ ch.qos.logback
+ logback-classic
+ org.junit.jupiterjunit-jupiter-engine
diff --git a/active-object/src/main/java/com/iluwatar/activeobject/ActiveCreature.java b/active-object/src/main/java/com/iluwatar/activeobject/ActiveCreature.java
index d1c5fa69264d..5a440020c0ac 100644
--- a/active-object/src/main/java/com/iluwatar/activeobject/ActiveCreature.java
+++ b/active-object/src/main/java/com/iluwatar/activeobject/ActiveCreature.java
@@ -29,87 +29,87 @@
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
-/**
- * ActiveCreature class is the base of the active object example.
- * @author Noam Greenshtain
- *
- */
+/** ActiveCreature class is the base of the active object example. */
public abstract class ActiveCreature {
-
+
private static final Logger logger = LoggerFactory.getLogger(ActiveCreature.class.getName());
private BlockingQueue requests;
-
+
private String name;
-
+
private Thread thread; // Thread of execution.
-
+
private int status; // status of the thread of execution.
- /**
- * Constructor and initialization.
- */
+ /** Constructor and initialization. */
protected ActiveCreature(String name) {
this.name = name;
this.status = 0;
this.requests = new LinkedBlockingQueue<>();
- thread = new Thread(() -> {
- boolean infinite = true;
- while (infinite) {
- try {
- requests.take().run();
- } catch (InterruptedException e) {
- if (this.status != 0) {
- logger.error("Thread was interrupted. --> {}", e.getMessage());
- }
- infinite = false;
- Thread.currentThread().interrupt();
- }
- }
- });
+ thread =
+ new Thread(
+ () -> {
+ boolean infinite = true;
+ while (infinite) {
+ try {
+ requests.take().run();
+ } catch (InterruptedException e) {
+ if (this.status != 0) {
+ logger.error("Thread was interrupted. --> {}", e.getMessage());
+ }
+ infinite = false;
+ Thread.currentThread().interrupt();
+ }
+ }
+ });
thread.start();
}
/**
* Eats the porridge.
+ *
* @throws InterruptedException due to firing a new Runnable.
*/
public void eat() throws InterruptedException {
- requests.put(() -> {
- logger.info("{} is eating!", name());
- logger.info("{} has finished eating!", name());
- });
+ requests.put(
+ () -> {
+ logger.info("{} is eating!", name());
+ logger.info("{} has finished eating!", name());
+ });
}
/**
* Roam the wastelands.
+ *
* @throws InterruptedException due to firing a new Runnable.
*/
public void roam() throws InterruptedException {
- requests.put(() ->
- logger.info("{} has started to roam in the wastelands.", name())
- );
+ requests.put(() -> logger.info("{} has started to roam in the wastelands.", name()));
}
-
+
/**
* Returns the name of the creature.
+ *
* @return the name of the creature.
*/
public String name() {
return this.name;
}
-
+
/**
* Kills the thread of execution.
+ *
* @param status of the thread of execution. 0 == OK, the rest is logging an error.
*/
public void kill(int status) {
this.status = status;
this.thread.interrupt();
}
-
+
/**
* Returns the status of the thread of execution.
+ *
* @return the status of the thread of execution.
*/
public int getStatus() {
diff --git a/active-object/src/main/java/com/iluwatar/activeobject/App.java b/active-object/src/main/java/com/iluwatar/activeobject/App.java
index b88b4c5590a0..ca3a5526ebb8 100644
--- a/active-object/src/main/java/com/iluwatar/activeobject/App.java
+++ b/active-object/src/main/java/com/iluwatar/activeobject/App.java
@@ -30,17 +30,17 @@
import org.slf4j.LoggerFactory;
/**
- * The Active Object pattern helps to solve synchronization difficulties without using
- * 'synchronized' methods. The active object will contain a thread-safe data structure
- * (such as BlockingQueue) and use to synchronize method calls by moving the logic of the method
- * into an invocator(usually a Runnable) and store it in the DSA.
- *
+ * The Active Object pattern helps to solve synchronization difficulties without using
+ * 'synchronized' methods. The active object will contain a thread-safe data structure (such as
+ * BlockingQueue) and use to synchronize method calls by moving the logic of the method into an
+ * invocator(usually a Runnable) and store it in the DSA.
+ *
*
In this example, we fire 20 threads to modify a value in the target class.
*/
public class App implements Runnable {
-
+
private static final Logger logger = LoggerFactory.getLogger(App.class.getName());
-
+
private static final int NUM_CREATURES = 3;
/**
@@ -48,11 +48,11 @@ public class App implements Runnable {
*
* @param args command line arguments.
*/
- public static void main(String[] args) {
+ public static void main(String[] args) {
var app = new App();
app.run();
}
-
+
@Override
public void run() {
List creatures = new ArrayList<>();
diff --git a/active-object/src/main/java/com/iluwatar/activeobject/Orc.java b/active-object/src/main/java/com/iluwatar/activeobject/Orc.java
index 07f30aad0788..30adde034de5 100644
--- a/active-object/src/main/java/com/iluwatar/activeobject/Orc.java
+++ b/active-object/src/main/java/com/iluwatar/activeobject/Orc.java
@@ -24,15 +24,10 @@
*/
package com.iluwatar.activeobject;
-/**
- * An implementation of the ActiveCreature class.
- * @author Noam Greenshtain
- *
- */
+/** An implementation of the ActiveCreature class. */
public class Orc extends ActiveCreature {
public Orc(String name) {
super(name);
}
-
}
diff --git a/active-object/src/test/java/com/iluwatar/activeobject/ActiveCreatureTest.java b/active-object/src/test/java/com/iluwatar/activeobject/ActiveCreatureTest.java
index 5441ed6b0d9b..be79e2fb5527 100644
--- a/active-object/src/test/java/com/iluwatar/activeobject/ActiveCreatureTest.java
+++ b/active-object/src/test/java/com/iluwatar/activeobject/ActiveCreatureTest.java
@@ -27,17 +27,16 @@
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;
+
class ActiveCreatureTest {
-
- @Test
- void executionTest() throws InterruptedException {
- ActiveCreature orc = new Orc("orc1");
- assertEquals("orc1",orc.name());
- assertEquals(0,orc.getStatus());
- orc.eat();
- orc.roam();
- orc.kill(0);
- }
-
+ @Test
+ void executionTest() throws InterruptedException {
+ ActiveCreature orc = new Orc("orc1");
+ assertEquals("orc1", orc.name());
+ assertEquals(0, orc.getStatus());
+ orc.eat();
+ orc.roam();
+ orc.kill(0);
+ }
}
diff --git a/active-object/src/test/java/com/iluwatar/activeobject/AppTest.java b/active-object/src/test/java/com/iluwatar/activeobject/AppTest.java
index 8ef2f142cf46..559e2a1f58f1 100644
--- a/active-object/src/test/java/com/iluwatar/activeobject/AppTest.java
+++ b/active-object/src/test/java/com/iluwatar/activeobject/AppTest.java
@@ -28,11 +28,10 @@
import org.junit.jupiter.api.Test;
-
class AppTest {
- @Test
- void shouldExecuteApplicationWithoutException() {
- assertDoesNotThrow(() -> App.main(new String[]{}));
- }
+ @Test
+ void shouldExecuteApplicationWithoutException() {
+ assertDoesNotThrow(() -> App.main(new String[] {}));
+ }
}
diff --git a/acyclic-visitor/README.md b/acyclic-visitor/README.md
index 57adf4673b18..fb57d5681fd4 100644
--- a/acyclic-visitor/README.md
+++ b/acyclic-visitor/README.md
@@ -1,22 +1,25 @@
---
-title: Acyclic Visitor
+title: "Acyclic Visitor Pattern in Java: Streamlining Object Interactions"
+shortTitle: Acyclic Visitor
+description: "Learn about the Acyclic Visitor pattern in Java. This guide explains how it decouples operations from object hierarchies, providing examples and real-world applications."
category: Behavioral
language: en
tag:
- Decoupling
- Extensibility
+ - Interface
+ - Object composition
---
-## Intent
+## Intent of Acyclic Visitor Design Pattern
-The Acyclic Visitor pattern decouples operations from an object hierarchy, allowing you to add new operations without modifying the object structure directly.
+The Acyclic Visitor pattern in Java decouples operations from an object hierarchy, providing a flexible design for various applications.
-## Explanation
+## Detailed Explanation of Acyclic Visitor Pattern with Real-World Examples
-Real world example
+Real-world example
-> We have a hierarchy of modem classes. The modems in this hierarchy need to be visited by an external algorithm based
-> on filtering criteria (is it Unix or DOS compatible modem).
+> An analogous real-world example of the Acyclic Visitor pattern in Java is a museum guide system, demonstrating the practical application of this design pattern. Imagine a museum with various exhibits like paintings, sculptures, and historical artifacts. The museum has different types of guides (audio guide, human guide, virtual reality guide) that provide information about each exhibit. Instead of modifying the exhibits every time a new guide type is introduced, each guide implements an interface to visit different exhibit types. This way, the museum can add new types of guides without altering the existing exhibits, ensuring that the system remains extensible and maintainable without forming any dependency cycles.
In plain words
@@ -24,108 +27,123 @@ In plain words
[WikiWikiWeb](https://wiki.c2.com/?AcyclicVisitor) says
-> The Acyclic Visitor pattern allows new functions to be added to existing class hierarchies without affecting those
-> hierarchies, and without creating the dependency cycles that are inherent to the GangOfFour VisitorPattern.
+> The Acyclic Visitor pattern allows new functions to be added to existing class hierarchies without affecting those hierarchies, and without creating the dependency cycles that are inherent to the GangOfFour VisitorPattern.
-**Programmatic Example**
+Sequence diagram
+
+
+
+
+## Programmatic Example of Acyclic Visitor in Java
+
+In this Java example, we have a hierarchy of modem classes illustrating the Acyclic Visitor pattern. The modems in this hierarchy need to be visited by an external algorithm based on filtering criteria (is it Unix or DOS compatible modem).
Here's the `Modem` hierarchy.
```java
public abstract class Modem {
- public abstract void accept(ModemVisitor modemVisitor);
+ public abstract void accept(ModemVisitor modemVisitor);
}
public class Zoom extends Modem {
- ...
- @Override
- public void accept(ModemVisitor modemVisitor) {
- if (modemVisitor instanceof ZoomVisitor) {
- ((ZoomVisitor) modemVisitor).visit(this);
- } else {
- LOGGER.info("Only ZoomVisitor is allowed to visit Zoom modem");
+
+ // Other properties and methods...
+
+ @Override
+ public void accept(ModemVisitor modemVisitor) {
+ if (modemVisitor instanceof ZoomVisitor) {
+ ((ZoomVisitor) modemVisitor).visit(this);
+ } else {
+ LOGGER.info("Only ZoomVisitor is allowed to visit Zoom modem");
+ }
}
- }
}
public class Hayes extends Modem {
- ...
- @Override
- public void accept(ModemVisitor modemVisitor) {
- if (modemVisitor instanceof HayesVisitor) {
- ((HayesVisitor) modemVisitor).visit(this);
- } else {
- LOGGER.info("Only HayesVisitor is allowed to visit Hayes modem");
+
+ // Other properties and methods...
+
+ @Override
+ public void accept(ModemVisitor modemVisitor) {
+ if (modemVisitor instanceof HayesVisitor) {
+ ((HayesVisitor) modemVisitor).visit(this);
+ } else {
+ LOGGER.info("Only HayesVisitor is allowed to visit Hayes modem");
+ }
}
- }
}
```
-Next we introduce the `ModemVisitor` hierarchy.
+Next, we introduce the `ModemVisitor` hierarchy.
```java
public interface ModemVisitor {
}
public interface HayesVisitor extends ModemVisitor {
- void visit(Hayes hayes);
+ void visit(Hayes hayes);
}
public interface ZoomVisitor extends ModemVisitor {
- void visit(Zoom zoom);
+ void visit(Zoom zoom);
}
public interface AllModemVisitor extends ZoomVisitor, HayesVisitor {
}
public class ConfigureForDosVisitor implements AllModemVisitor {
- ...
- @Override
- public void visit(Hayes hayes) {
- LOGGER.info(hayes + " used with Dos configurator.");
- }
- @Override
- public void visit(Zoom zoom) {
- LOGGER.info(zoom + " used with Dos configurator.");
- }
+
+ // Other properties and methods...
+
+ @Override
+ public void visit(Hayes hayes) {
+ LOGGER.info(hayes + " used with Dos configurator.");
+ }
+
+ @Override
+ public void visit(Zoom zoom) {
+ LOGGER.info(zoom + " used with Dos configurator.");
+ }
}
public class ConfigureForUnixVisitor implements ZoomVisitor {
- ...
- @Override
- public void visit(Zoom zoom) {
- LOGGER.info(zoom + " used with Unix configurator.");
- }
+
+ // Other properties and methods...
+
+ @Override
+ public void visit(Zoom zoom) {
+ LOGGER.info(zoom + " used with Unix configurator.");
+ }
}
```
Finally, here are the visitors in action.
```java
+public static void main(String[] args) {
var conUnix = new ConfigureForUnixVisitor();
var conDos = new ConfigureForDosVisitor();
+
var zoom = new Zoom();
var hayes = new Hayes();
- hayes.accept(conDos);
- zoom.accept(conDos);
- hayes.accept(conUnix);
- zoom.accept(conUnix);
+
+ hayes.accept(conDos); // Hayes modem with Dos configurator
+ zoom.accept(conDos); // Zoom modem with Dos configurator
+ hayes.accept(conUnix); // Hayes modem with Unix configurator
+ zoom.accept(conUnix); // Zoom modem with Unix configurator
+}
```
Program output:
```
- // Hayes modem used with Dos configurator.
- // Zoom modem used with Dos configurator.
- // Only HayesVisitor is allowed to visit Hayes modem
- // Zoom modem used with Unix configurator.
+09:15:11.125 [main] INFO com.iluwatar.acyclicvisitor.ConfigureForDosVisitor -- Hayes modem used with Dos configurator.
+09:15:11.127 [main] INFO com.iluwatar.acyclicvisitor.ConfigureForDosVisitor -- Zoom modem used with Dos configurator.
+09:15:11.127 [main] INFO com.iluwatar.acyclicvisitor.Hayes -- Only HayesVisitor is allowed to visit Hayes modem
+09:15:11.127 [main] INFO com.iluwatar.acyclicvisitor.ConfigureForUnixVisitor -- Zoom modem used with Unix configurator.
```
-## Class diagram
-
-
-
-## Applicability
+## When to Use the Acyclic Visitor Pattern in Java
This pattern can be used:
@@ -135,30 +153,34 @@ This pattern can be used:
* When the visited class hierarchy will be frequently extended with new derivatives of the Element class.
* When the recompilation, relinking, retesting or redistribution of the derivatives of Element is very expensive.
-## Tutorials
+## Acyclic Visitor Pattern Java Tutorials
-* [Acyclic Visitor Pattern Example](https://codecrafter.blogspot.com/2012/12/the-acyclic-visitor-pattern.html)
+* [The Acyclic Visitor Pattern (Code Crafter)](https://codecrafter.blogspot.com/2012/12/the-acyclic-visitor-pattern.html)
-## Consequences
+## Benefits and Trade-offs of Acyclic Visitor Pattern
Benefits:
-* No dependency cycles between class hierarchies.
-* No need to recompile all the visitors if a new one is added.
-* Does not cause compilation failure in existing visitors if class hierarchy has a new member.
+* Extensible: New operations can be added easily without changing the object structure.
+* Decoupled: Reduces coupling between the objects and the operations on them.
+* No dependency cycles: Ensures acyclic dependencies, improving maintainability and reducing complexity.
Trade-offs:
-* Violates [Liskov's Substitution Principle](https://java-design-patterns.com/principles/#liskov-substitution-principle) by showing that it can accept all visitors but actually only being interested in particular visitors.
-* Parallel hierarchy of visitors has to be created for all members in visitable class hierarchy.
+* Increased complexity: Can introduce additional complexity with the need for multiple visitor interfaces.
+* Maintenance overhead: Modifying the object hierarchy requires updating all visitors.
-## Related patterns
+## Related Java Design Patterns
-* [Visitor Pattern](https://java-design-patterns.com/patterns/visitor/)
+* [Composite](https://java-design-patterns.com/patterns/composite/): Often used in conjunction with Acyclic Visitor to allow treating individual objects and compositions uniformly.
+* [Decorator](https://java-design-patterns.com/patterns/decorator/): Can be used alongside to add responsibilities to objects dynamically.
+* [Visitor](https://java-design-patterns.com/patterns/visitor/): The Acyclic Visitor pattern is a variation of the Visitor pattern that avoids cyclic dependencies.
-## Credits
+## References and Credits
-* [Acyclic Visitor by Robert C. Martin](http://condor.depaul.edu/dmumaugh/OOT/Design-Principles/acv.pdf)
-* [Acyclic Visitor in WikiWikiWeb](https://wiki.c2.com/?AcyclicVisitor)
-* [Design Patterns: Elements of Reusable Object-Oriented Software](https://www.amazon.com/gp/product/0201633612/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=0201633612&linkCode=as2&tag=javadesignpat-20&linkId=675d49790ce11db99d90bde47f1aeb59)
-* [Head First Design Patterns: A Brain-Friendly Guide](https://www.amazon.com/gp/product/0596007124/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=0596007124&linkCode=as2&tag=javadesignpat-20&linkId=6b8b6eea86021af6c8e3cd3fc382cb5b)
+* [Design Patterns: Elements of Reusable Object-Oriented Software](https://amzn.to/3w0pvKI)
+* [Head First Design Patterns: Building Extensible and Maintainable Object-Oriented Software](https://amzn.to/49NGldq)
+* [Java Design Patterns: A Hands-On Experience with Real-World Examples](https://amzn.to/3yhh525)
+* [Patterns in Java: A Catalog of Reusable Design Patterns Illustrated with UML](https://amzn.to/4bOtzwF)
+* [Acyclic Visitor (Robert C. Martin)](http://condor.depaul.edu/dmumaugh/OOT/Design-Principles/acv.pdf)
+* [Acyclic Visitor (WikiWikiWeb)](https://wiki.c2.com/?AcyclicVisitor)
diff --git a/acyclic-visitor/etc/acyclic-visitor-sequence-diagram.png b/acyclic-visitor/etc/acyclic-visitor-sequence-diagram.png
new file mode 100644
index 000000000000..a3c2ba56b89f
Binary files /dev/null and b/acyclic-visitor/etc/acyclic-visitor-sequence-diagram.png differ
diff --git a/acyclic-visitor/pom.xml b/acyclic-visitor/pom.xml
index 52604048e127..b4f5646b71c0 100644
--- a/acyclic-visitor/pom.xml
+++ b/acyclic-visitor/pom.xml
@@ -34,6 +34,14 @@
acyclic-visitor
+
+ org.slf4j
+ slf4j-api
+
+
+ ch.qos.logback
+ logback-classic
+ org.junit.jupiterjunit-jupiter-engine
diff --git a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/AllModemVisitor.java b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/AllModemVisitor.java
index 38da4923a467..a3b1679a2d9f 100644
--- a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/AllModemVisitor.java
+++ b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/AllModemVisitor.java
@@ -28,6 +28,4 @@
* All ModemVisitor interface extends all visitor interfaces. This interface provides ease of use
* when a visitor needs to visit all modem types.
*/
-public interface AllModemVisitor extends ZoomVisitor, HayesVisitor {
-
-}
+public interface AllModemVisitor extends ZoomVisitor, HayesVisitor {}
diff --git a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/App.java b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/App.java
index 64d4d039aba3..3b7c6cd61e4b 100644
--- a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/App.java
+++ b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/App.java
@@ -37,9 +37,7 @@
*/
public class App {
- /**
- * Program's entry point.
- */
+ /** Program's entry point. */
public static void main(String[] args) {
var conUnix = new ConfigureForUnixVisitor();
var conDos = new ConfigureForDosVisitor();
@@ -50,6 +48,6 @@ public static void main(String[] args) {
hayes.accept(conDos); // Hayes modem with Dos configurator
zoom.accept(conDos); // Zoom modem with Dos configurator
hayes.accept(conUnix); // Hayes modem with Unix configurator
- zoom.accept(conUnix); // Zoom modem with Unix configurator
+ zoom.accept(conUnix); // Zoom modem with Unix configurator
}
}
diff --git a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ConfigureForDosVisitor.java b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ConfigureForDosVisitor.java
index 9f9f29187839..267a8d66ac45 100644
--- a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ConfigureForDosVisitor.java
+++ b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ConfigureForDosVisitor.java
@@ -27,8 +27,7 @@
import lombok.extern.slf4j.Slf4j;
/**
- * ConfigureForDosVisitor class implements both zoom's and hayes' visit method for Dos
- * manufacturer.
+ * ConfigureForDosVisitor class implements both zoom's and hayes' visit method for Dos manufacturer.
*/
@Slf4j
public class ConfigureForDosVisitor implements AllModemVisitor {
diff --git a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ConfigureForUnixVisitor.java b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ConfigureForUnixVisitor.java
index 097f19c0dbbd..d9fd14f69435 100644
--- a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ConfigureForUnixVisitor.java
+++ b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ConfigureForUnixVisitor.java
@@ -37,4 +37,4 @@ public class ConfigureForUnixVisitor implements ZoomVisitor {
public void visit(Zoom zoom) {
LOGGER.info(zoom + " used with Unix configurator.");
}
-}
\ No newline at end of file
+}
diff --git a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Hayes.java b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Hayes.java
index 384df8a4d9c9..e0b2fcc2b530 100644
--- a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Hayes.java
+++ b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Hayes.java
@@ -26,15 +26,11 @@
import lombok.extern.slf4j.Slf4j;
-/**
- * Hayes class implements its accept method.
- */
+/** Hayes class implements its accept method. */
@Slf4j
public class Hayes implements Modem {
- /**
- * Accepts all visitors but honors only HayesVisitor.
- */
+ /** Accepts all visitors but honors only HayesVisitor. */
@Override
public void accept(ModemVisitor modemVisitor) {
if (modemVisitor instanceof HayesVisitor) {
@@ -42,12 +38,9 @@ public void accept(ModemVisitor modemVisitor) {
} else {
LOGGER.info("Only HayesVisitor is allowed to visit Hayes modem");
}
-
}
- /**
- * Hayes' modem's toString method.
- */
+ /** Hayes' modem's toString method. */
@Override
public String toString() {
return "Hayes modem";
diff --git a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/HayesVisitor.java b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/HayesVisitor.java
index a33c87cfa645..aad9b970994f 100644
--- a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/HayesVisitor.java
+++ b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/HayesVisitor.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.acyclicvisitor;
-/**
- * HayesVisitor interface.
- */
+/** HayesVisitor interface. */
public interface HayesVisitor extends ModemVisitor {
void visit(Hayes hayes);
}
diff --git a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Modem.java b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Modem.java
index fd15ee422468..8552574453e5 100644
--- a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Modem.java
+++ b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Modem.java
@@ -24,10 +24,7 @@
*/
package com.iluwatar.acyclicvisitor;
-/**
- * //Modem abstract class.
- * converted to an interface
- */
+/** //Modem abstract class. converted to an interface */
public interface Modem {
void accept(ModemVisitor modemVisitor);
}
diff --git a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Zoom.java b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Zoom.java
index e9f02e1ad6fd..59b50a54a12f 100644
--- a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Zoom.java
+++ b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/Zoom.java
@@ -26,15 +26,11 @@
import lombok.extern.slf4j.Slf4j;
-/**
- * Zoom class implements its accept method.
- */
+/** Zoom class implements its accept method. */
@Slf4j
public class Zoom implements Modem {
- /**
- * Accepts all visitors but honors only ZoomVisitor.
- */
+ /** Accepts all visitors but honors only ZoomVisitor. */
@Override
public void accept(ModemVisitor modemVisitor) {
if (modemVisitor instanceof ZoomVisitor) {
@@ -44,9 +40,7 @@ public void accept(ModemVisitor modemVisitor) {
}
}
- /**
- * Zoom modem's toString method.
- */
+ /** Zoom modem's toString method. */
@Override
public String toString() {
return "Zoom modem";
diff --git a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ZoomVisitor.java b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ZoomVisitor.java
index 639af1c65777..5388ded6f735 100644
--- a/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ZoomVisitor.java
+++ b/acyclic-visitor/src/main/java/com/iluwatar/acyclicvisitor/ZoomVisitor.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.acyclicvisitor;
-/**
- * ZoomVisitor interface.
- */
+/** ZoomVisitor interface. */
public interface ZoomVisitor extends ModemVisitor {
void visit(Zoom zoom);
}
diff --git a/acyclic-visitor/src/test/java/com/iluwatar/acyclicvisitor/AppTest.java b/acyclic-visitor/src/test/java/com/iluwatar/acyclicvisitor/AppTest.java
index 9cc242d8f7fc..7a21498a63ea 100644
--- a/acyclic-visitor/src/test/java/com/iluwatar/acyclicvisitor/AppTest.java
+++ b/acyclic-visitor/src/test/java/com/iluwatar/acyclicvisitor/AppTest.java
@@ -24,25 +24,22 @@
*/
package com.iluwatar.acyclicvisitor;
-import org.junit.jupiter.api.Test;
-
import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
-/**
- * Tests that the Acyclic Visitor example runs without errors.
- */
+import org.junit.jupiter.api.Test;
+
+/** Tests that the Acyclic Visitor example runs without errors. */
class AppTest {
/**
* Issue: Add at least one assertion to this test case.
*
- * Solution: Inserted assertion to check whether the execution of the main method in {@link App}
- * throws an exception.
+ *
The Adapter ({@link FishingBoatAdapter}) converts the interface of the adaptee class ({@link
* FishingBoat}) into a suitable one expected by the client ({@link RowingBoat}).
*
- *
The story of this implementation is this. Pirates are coming! we need a {@link
- * RowingBoat} to flee! We have a {@link FishingBoat} and our captain. We have no time to make up a
- * new ship! we need to reuse this {@link FishingBoat}. The captain needs a rowing boat which he can
- * operate. The spec is in {@link RowingBoat}. We will use the Adapter pattern to reuse {@link
- * FishingBoat}.
+ *
The story of this implementation is this.
+ * Pirates are coming! we need a {@link RowingBoat} to flee! We have a {@link FishingBoat} and our
+ * captain. We have no time to make up a new ship! we need to reuse this {@link FishingBoat}. The
+ * captain needs a rowing boat which he can operate. The spec is in {@link RowingBoat}. We will use
+ * the Adapter pattern to reuse {@link FishingBoat}.
*/
public final class App {
- private App() {
- }
+ private App() {}
/**
* Program entry point.
diff --git a/adapter/src/main/java/com/iluwatar/adapter/Captain.java b/adapter/src/main/java/com/iluwatar/adapter/Captain.java
index 3d6d7746d00a..3b771e9d833e 100644
--- a/adapter/src/main/java/com/iluwatar/adapter/Captain.java
+++ b/adapter/src/main/java/com/iluwatar/adapter/Captain.java
@@ -29,7 +29,8 @@
import lombok.Setter;
/**
- * The Captain uses {@link RowingBoat} to sail. This is the client in the pattern.
+ * The Captain uses {@link RowingBoat} to sail.
+ * This is the client in the pattern.
*/
@Setter
@NoArgsConstructor
@@ -41,5 +42,4 @@ public final class Captain {
void row() {
rowingBoat.row();
}
-
}
diff --git a/adapter/src/main/java/com/iluwatar/adapter/FishingBoat.java b/adapter/src/main/java/com/iluwatar/adapter/FishingBoat.java
index e692d859873c..dd39f88f1ce0 100644
--- a/adapter/src/main/java/com/iluwatar/adapter/FishingBoat.java
+++ b/adapter/src/main/java/com/iluwatar/adapter/FishingBoat.java
@@ -36,5 +36,4 @@ final class FishingBoat {
void sail() {
LOGGER.info("The fishing boat is sailing");
}
-
}
diff --git a/adapter/src/main/java/com/iluwatar/adapter/RowingBoat.java b/adapter/src/main/java/com/iluwatar/adapter/RowingBoat.java
index c8714ef91040..55eeeaf4bd42 100644
--- a/adapter/src/main/java/com/iluwatar/adapter/RowingBoat.java
+++ b/adapter/src/main/java/com/iluwatar/adapter/RowingBoat.java
@@ -25,10 +25,10 @@
package com.iluwatar.adapter;
/**
- * The interface expected by the client. A rowing boat is rowed to move.
+ * The interface expected by the client.
+ * A rowing boat is rowed to move.
*/
public interface RowingBoat {
void row();
-
}
diff --git a/adapter/src/test/java/com/iluwatar/adapter/AdapterPatternTest.java b/adapter/src/test/java/com/iluwatar/adapter/AdapterPatternTest.java
index 10024ff0dc46..bc4984da3d6f 100644
--- a/adapter/src/test/java/com/iluwatar/adapter/AdapterPatternTest.java
+++ b/adapter/src/test/java/com/iluwatar/adapter/AdapterPatternTest.java
@@ -24,17 +24,15 @@
*/
package com.iluwatar.adapter;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-import java.util.HashMap;
-import java.util.Map;
-
import static org.mockito.Mockito.spy;
import static org.mockito.Mockito.verify;
-/**
- * Tests for the adapter pattern.
- */
+import java.util.HashMap;
+import java.util.Map;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/** Tests for the adapter pattern. */
class AdapterPatternTest {
private Map beans;
@@ -43,9 +41,7 @@ class AdapterPatternTest {
private static final String ROWING_BEAN = "captain";
- /**
- * This method runs before the test execution and sets the bean objects in the beans Map.
- */
+ /** This method runs before the test execution and sets the bean objects in the beans Map. */
@BeforeEach
void setup() {
beans = new HashMap<>();
diff --git a/adapter/src/test/java/com/iluwatar/adapter/AppTest.java b/adapter/src/test/java/com/iluwatar/adapter/AppTest.java
index be51d2687548..a2cc4c22bcaa 100644
--- a/adapter/src/test/java/com/iluwatar/adapter/AppTest.java
+++ b/adapter/src/test/java/com/iluwatar/adapter/AppTest.java
@@ -24,23 +24,17 @@
*/
package com.iluwatar.adapter;
-import org.junit.jupiter.api.Test;
-
import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
-/**
- * Tests that Adapter example runs without errors.
- */
-class AppTest {
+import org.junit.jupiter.api.Test;
- /**
- * Check whether the execution of the main method in {@link App}
- * throws an exception.
- */
+/** Tests that Adapter example runs without errors. */
+class AppTest {
+ /** Check whether the execution of the main method in {@link App} throws an exception. */
@Test
void shouldExecuteApplicationWithoutException() {
- assertDoesNotThrow(() -> App.main(new String[]{}));
+ assertDoesNotThrow(() -> App.main(new String[] {}));
}
}
diff --git a/aggregator-microservices/README.md b/aggregator-microservices/README.md
deleted file mode 100644
index 732129e17916..000000000000
--- a/aggregator-microservices/README.md
+++ /dev/null
@@ -1,131 +0,0 @@
----
-title: Aggregator Microservices
-category: Architectural
-language: en
-tag:
-- API design
-- Cloud distributed
-- Decoupling
-- Microservices
----
-
-## Intent
-
-Streamline client's interactions with system's microservices by providing a single aggregation point that consolidates data and responses from multiple services. This simplifies the client's communication with the system, improving efficiency and reducing complexity.
-
-## Explanation
-
-Real world example
-
-> Our web marketplace needs information about products and their current inventory. It makes a call to an aggregator service, which, in turn, calls the product information and product inventory microservices, returning the combined information.
-
-In plain words
-
-> Aggregator Microservice collects pieces of data from various microservices and returns an aggregate for processing.
-
-Stack Overflow says
-
-> Aggregator Microservice invokes multiple services to achieve the functionality required by the application.
-
-**Programmatic Example**
-
-Let's start from the data model. Here's our `Product`.
-
-```java
-public class Product {
- private String title;
- private int productInventories;
- // Getters and setters omitted for brevity ->
- ...
-}
-```
-
-Next we can introduce our `Aggregator` microservice. It contains clients `ProductInformationClient` and
-`ProductInventoryClient` for calling respective microservices.
-
-```java
-@RestController
-public class Aggregator {
-
- @Resource
- private ProductInformationClient informationClient;
-
- @Resource
- private ProductInventoryClient inventoryClient;
-
- @RequestMapping(path = "/product", method = RequestMethod.GET)
- public Product getProduct() {
-
- var product = new Product();
- var productTitle = informationClient.getProductTitle();
- var productInventory = inventoryClient.getProductInventories();
-
- //Fallback to error message
- product.setTitle(requireNonNullElse(productTitle, "Error: Fetching Product Title Failed"));
-
- //Fallback to default error inventory
- product.setProductInventories(requireNonNullElse(productInventory, -1));
-
- return product;
- }
-}
-```
-
-Here's the essence of information microservice implementation. Inventory microservice is similar, it just returns
-inventory counts.
-
-```java
-@RestController
-public class InformationController {
- @RequestMapping(value = "/information", method = RequestMethod.GET)
- public String getProductTitle() {
- return "The Product Title.";
- }
-}
-```
-
-Now calling our `Aggregator` REST API returns the product information.
-
-```bash
-curl http://localhost:50004/product
-{"title":"The Product Title.","productInventories":5}
-```
-
-## Class diagram
-
-
-
-## Applicability
-
-The Aggregator Microservices Design Pattern is particularly useful in scenarios where a client requires a composite response that is assembled from data provided by multiple microservices. Common use cases include e-commerce applications where product details, inventory, and reviews might be provided by separate services, or in dashboard applications where aggregated data from various services is displayed in a unified view.
-
-## Consequences
-
-Benefits:
-
-* Simplified Client: Clients interact with just one service rather than managing calls to multiple microservices, which simplifies client-side logic.
-* Reduced Latency: By aggregating responses, the number of network calls is reduced, which can improve the application's overall latency.
-* Decoupling: Clients are decoupled from the individual microservices, allowing for more flexibility in changing the microservices landscape without impacting clients.
-* Centralized Logic: Aggregation allows for centralized transformation and logic application on the data collected from various services, which can be more efficient than handling it in the client or spreading it across multiple services.
-
-Trade-offs:
-
-* Single Point of Failure: The aggregator service can become a bottleneck or a single point of failure if not designed with high availability and scalability in mind.
-* Complexity: Implementing an aggregator can introduce complexity, especially in terms of data aggregation logic and error handling when dealing with multiple services.
-
-## Related Patterns
-
-* [API Gateway](https://java-design-patterns.com/patterns/api-gateway/): The Aggregator Microservices pattern is often used in conjunction with an API Gateway, which provides a single entry point for clients to access multiple microservices.
-* [Composite](https://java-design-patterns.com/patterns/composite/): The Aggregator Microservices pattern can be seen as a form of the Composite pattern, where the composite is the aggregated response from multiple microservices.
-* [Facade](https://java-design-patterns.com/patterns/facade/): The Aggregator Microservices pattern can be seen as a form of the Facade pattern, where the facade is the aggregator service that provides a simplified interface to the client.
-
-## Credits
-
-* [Microservice Design Patterns](http://web.archive.org/web/20190705163602/http://blog.arungupta.me/microservice-design-patterns/)
-* [Microservices Patterns: With examples in Java](https://www.amazon.com/gp/product/1617294543/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=1617294543&linkId=8b4e570267bc5fb8b8189917b461dc60)
-* [Architectural Patterns: Uncover essential patterns in the most indispensable realm of enterprise architecture](https://www.amazon.com/gp/product/B077T7V8RC/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=B077T7V8RC&linkId=c34d204bfe1b277914b420189f09c1a4)
-* [Building Microservices: Designing Fine-Grained Systems](https://amzn.to/43aGpSR)
-* [Microservices Patterns: With examples in Java](https://amzn.to/4a5LHkP)
-* [Microservice Architecture: Aligning Principles, Practices, and Culture](https://amzn.to/3T9jZNi)
-* [Production-Ready Microservices: Building Standardized Systems Across an Engineering Organization](https://amzn.to/4a0Vk4c)
-* [Designing Distributed Systems: Patterns and Paradigms for Scalable, Reliable Services](https://amzn.to/3T9g9Uj)
diff --git a/ambassador/README.md b/ambassador/README.md
index b2902d7ddd42..fa08223feb75 100644
--- a/ambassador/README.md
+++ b/ambassador/README.md
@@ -1,45 +1,49 @@
---
-title: Ambassador
-category: Structural
+title: "Ambassador Pattern in Java: Simplifying Remote Resource Management"
+shortTitle: Ambassador
+description: "Explore the Ambassador Pattern in Java, its benefits, use cases, and practical examples. Learn how to decouple and offload common functionalities to improve system performance and maintainability."
+category: Integration
language: en
tag:
+ - API design
- Decoupling
- - Cloud distributed
+ - Fault tolerance
+ - Proxy
+ - Resilience
+ - Scalability
---
-## Intent
+## Intent of Ambassador Design Pattern
-Provide a helper service instance on a client and offload common functionality away from a shared resource.
+The Ambassador Pattern in Java helps offload common functionalities such as monitoring, logging, and routing from a shared resource to a helper service instance, enhancing performance and maintainability in distributed systems.
-## Also known as
+## Detailed Explanation of Ambassador Pattern with Real-World Examples
-* Sidecar
+Real-world example
-## Explanation
-
-Real world example
-
-> A remote service has many clients accessing a function it provides. The service is a legacy application and is
-> impossible to update. Large numbers of requests from users are causing connectivity issues. New rules for request
-> frequency should be implemented along with latency checks and client-side logging.
+> Imagine a busy hotel where guests frequently request restaurant reservations, event tickets, or transportation arrangements. Instead of each guest individually contacting these services, the hotel provides a concierge. The concierge handles these tasks on behalf of the guests, ensuring that reservations are made smoothly, tickets are booked on time, and transportation is scheduled efficiently.
+>
+> In this analogy, the guests are the client services, the external providers (restaurants, ticket vendors, transportation) are the remote services, and the concierge represents the ambassador service. This setup allows the guests to focus on enjoying their stay while the concierge manages the complexities of external interactions, providing a seamless and enhanced experience.
In plain words
-> With the Ambassador pattern, we can implement less-frequent polling from clients along with latency checks and
-> logging.
+> With the Ambassador pattern, we can implement less-frequent polling from clients along with latency checks and logging.
Microsoft documentation states
-> An ambassador service can be thought of as an out-of-process proxy which is co-located with the client. This pattern
-> can be useful for offloading common client connectivity tasks such as monitoring, logging, routing,
-> security (such as TLS), and resiliency patterns in a language agnostic way. It is often used with legacy applications,
-> or other applications that are difficult to modify, in order to extend their networking capabilities. It can also
-> enable a specialized team to implement those features.
+> An ambassador service can be thought of as an out-of-process proxy which is co-located with the client. This pattern can be useful for offloading common client connectivity tasks such as monitoring, logging, routing, security (such as TLS), and resiliency patterns in a language agnostic way. It is often used with legacy applications, or other applications that are difficult to modify, in order to extend their networking capabilities. It can also enable a specialized team to implement those features.
+
+Sequence diagram
+
+
-**Programmatic Example**
+## Programmatic Example of Ambassador Pattern in Java
-With the above introduction in mind we will imitate the functionality in this example. We have an interface implemented
-by the remote service as well as the ambassador service:
+In this example of the Ambassador Pattern in Java, we demonstrate how to implement latency checks, logging, and retry mechanisms to improve system reliability.
+
+A remote service has many clients accessing a function it provides. The service is a legacy application and is impossible to update. Large numbers of requests from users are causing connectivity issues. New rules for request frequency should be implemented along with latency checks and client-side logging.
+
+With the above introduction in mind we will imitate the functionality in this example. We have an interface implemented by the remote service as well as the ambassador service.
```java
interface RemoteServiceInterface {
@@ -50,6 +54,7 @@ interface RemoteServiceInterface {
A remote services represented as a singleton.
```java
+
@Slf4j
public class RemoteService implements RemoteServiceInterface {
private static RemoteService service = null;
@@ -61,7 +66,8 @@ public class RemoteService implements RemoteServiceInterface {
return service;
}
- private RemoteService() {}
+ private RemoteService() {
+ }
@Override
public long doRemoteFunction(int value) {
@@ -78,69 +84,71 @@ public class RemoteService implements RemoteServiceInterface {
}
```
-A service ambassador adding additional features such as logging, latency checks
+A service ambassador adds additional features such as logging and latency checks.
```java
+
@Slf4j
public class ServiceAmbassador implements RemoteServiceInterface {
- private static final int RETRIES = 3;
- private static final int DELAY_MS = 3000;
-
- ServiceAmbassador() {
- }
-
- @Override
- public long doRemoteFunction(int value) {
- return safeCall(value);
- }
-
- private long checkLatency(int value) {
- var startTime = System.currentTimeMillis();
- var result = RemoteService.getRemoteService().doRemoteFunction(value);
- var timeTaken = System.currentTimeMillis() - startTime;
-
- LOGGER.info("Time taken (ms): " + timeTaken);
- return result;
- }
-
- private long safeCall(int value) {
- var retries = 0;
- var result = (long) FAILURE;
-
- for (int i = 0; i < RETRIES; i++) {
- if (retries >= RETRIES) {
- return FAILURE;
- }
-
- if ((result = checkLatency(value)) == FAILURE) {
- LOGGER.info("Failed to reach remote: (" + (i + 1) + ")");
- retries++;
- try {
- sleep(DELAY_MS);
- } catch (InterruptedException e) {
- LOGGER.error("Thread sleep state interrupted", e);
+ private static final int RETRIES = 3;
+ private static final int DELAY_MS = 3000;
+
+ ServiceAmbassador() {
+ }
+
+ @Override
+ public long doRemoteFunction(int value) {
+ return safeCall(value);
+ }
+
+ private long checkLatency(int value) {
+ var startTime = System.currentTimeMillis();
+ var result = RemoteService.getRemoteService().doRemoteFunction(value);
+ var timeTaken = System.currentTimeMillis() - startTime;
+
+ LOGGER.info("Time taken (ms): " + timeTaken);
+ return result;
+ }
+
+ private long safeCall(int value) {
+ var retries = 0;
+ var result = (long) FAILURE;
+
+ for (int i = 0; i < RETRIES; i++) {
+ if (retries >= RETRIES) {
+ return FAILURE;
+ }
+
+ if ((result = checkLatency(value)) == FAILURE) {
+ LOGGER.info("Failed to reach remote: (" + (i + 1) + ")");
+ retries++;
+ try {
+ sleep(DELAY_MS);
+ } catch (InterruptedException e) {
+ LOGGER.error("Thread sleep state interrupted", e);
+ }
+ } else {
+ break;
+ }
}
- } else {
- break;
- }
+ return result;
}
- return result;
- }
}
```
-A client has a local service ambassador used to interact with the remote service:
+A client has a local service ambassador used to interact with the remote service.
```java
+
@Slf4j
public class Client {
- private final ServiceAmbassador serviceAmbassador = new ServiceAmbassador();
+ private final ServiceAmbassador serviceAmbassador = new ServiceAmbassador();
- long useService(int value) {
- var result = serviceAmbassador.doRemoteFunction(value);
- LOGGER.info("Service result: " + result);
- return result;
- }
+ long useService(int value) {
+ var result = serviceAmbassador.doRemoteFunction(value);
+ LOGGER.info("Service result: " + result);
+ return result;
+ }
}
```
@@ -148,36 +156,32 @@ Here are two clients using the service.
```java
public class App {
- public static void main(String[] args) {
- var host1 = new Client();
- var host2 = new Client();
- host1.useService(12);
- host2.useService(73);
- }
+ public static void main(String[] args) {
+ var host1 = new Client();
+ var host2 = new Client();
+ host1.useService(12);
+ host2.useService(73);
+ }
}
```
Here's the output for running the example:
```java
-Time taken (ms): 111
-Service result: 120
-Time taken (ms): 931
-Failed to reach remote: (1)
-Time taken (ms): 665
-Failed to reach remote: (2)
-Time taken (ms): 538
-Failed to reach remote: (3)
-Service result: -1
+Time taken(ms):111
+Service result:120
+Time taken(ms):931
+Failed to reach remote:(1)
+Time taken(ms):665
+Failed to reach remote:(2)
+Time taken(ms):538
+Failed to reach remote:(3)
+Service result:-1
```
-## Class diagram
-
-
+## When to Use the Ambassador Pattern in Java
-## Applicability
-
-* Cloud Native and Microservices Architectures: Especially useful in distributed systems where it's crucial to monitor, log, and secure inter-service communication.
+* The Ambassador Pattern is particularly beneficial for Cloud Native and Microservices Architectures in Java. It helps in monitoring, logging, and securing inter-service communication, making it ideal for distributed systems.
* Legacy System Integration: Facilitates communication with newer services by handling necessary but non-core functionalities.
* Performance Enhancement: Can be used to cache results or compress data to improve communication efficiency.
@@ -189,7 +193,7 @@ Typical use cases include:
* Offload remote service tasks
* Facilitate network connection
-## Consequences
+## Benefits and Trade-offs of Ambassador Pattern
Benefits:
@@ -204,7 +208,7 @@ Trade-offs:
* Potential Performance Overhead: The additional network hop can introduce latency and overhead, particularly if not optimized.
* Deployment Overhead: Requires additional resources and management for deploying and scaling ambassador services.
-## Known uses
+## Real-World Applications of Ambassador Pattern in Java
* Service Mesh Implementations: In a service mesh architecture, like Istio or Linkerd, the Ambassador pattern is often employed as a sidecar proxy that handles inter-service communications. This includes tasks such as service discovery, routing, load balancing, telemetry (metrics and tracing), and security (authentication and authorization).
* API Gateways: API gateways can use the Ambassador pattern to encapsulate common functionalities like rate limiting, caching, request shaping, and authentication. This allows backend services to focus on their core business logic without being burdened by these cross-cutting concerns.
@@ -216,17 +220,17 @@ Trade-offs:
* Network Optimization: For services deployed across different geographical locations or cloud regions, Ambassadors can optimize communication by compressing data, batching requests, or even implementing smart routing to reduce latency and costs.
* [Kubernetes-native API gateway for microservices](https://github.com/datawire/ambassador)
-## Related patterns
+## Related Java Design Patterns
+* [Circuit Breaker](https://java-design-patterns.com/patterns/circuit-breaker/): Often used in conjunction to manage fault tolerance by stopping calls to an unresponsive service.
+* [Decorator](https://java-design-patterns.com/patterns/decorator/): The decorator pattern is used to add functionality to an object dynamically, while the ambassador pattern is used to offload functionality to a separate object.
* [Proxy](https://java-design-patterns.com/patterns/proxy/): Shares similarities with the proxy pattern, but the ambassador pattern specifically focuses on offloading ancillary functionalities.
* Sidecar: A similar pattern used in the context of containerized applications, where a sidecar container provides additional functionality to the main application container.
-* [Decorator](https://java-design-patterns.com/patterns/decorator/): The decorator pattern is used to add functionality to an object dynamically, while the ambassador pattern is used to offload functionality to a separate object.
-## Credits
+## References and Credits
-* [Ambassador pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/ambassador)
-* [Designing Distributed Systems: Patterns and Paradigms for Scalable, Reliable Services](https://www.amazon.com/s?k=designing+distributed+systems&sprefix=designing+distri%2Caps%2C156&linkCode=ll2&tag=javadesignpat-20&linkId=a12581e625462f9038557b01794e5341&language=en_US&ref_=as_li_ss_tl)
+* [Building Microservices: Designing Fine-Grained Systems](https://amzn.to/43aGpSR)
* [Cloud Native Patterns: Designing Change-tolerant Software](https://amzn.to/3wUAl4O)
* [Designing Distributed Systems: Patterns and Paradigms for Scalable, Reliable Services](https://amzn.to/3T9g9Uj)
-* [Microservices Patterns: With examples in Java](https://www.amazon.com/gp/product/1617294543/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=1617294543&linkId=8b4e570267bc5fb8b8189917b461dc60)
-* [Building Microservices: Designing Fine-Grained Systems](https://amzn.to/43aGpSR)
+* [Microservices Patterns: With examples in Java](https://amzn.to/3UyWD5O)
+* [Ambassador pattern (Microsoft)](https://docs.microsoft.com/en-us/azure/architecture/patterns/ambassador)
diff --git a/ambassador/etc/ambassador-sequence-diagram.png b/ambassador/etc/ambassador-sequence-diagram.png
new file mode 100644
index 000000000000..71e6a947c5dd
Binary files /dev/null and b/ambassador/etc/ambassador-sequence-diagram.png differ
diff --git a/ambassador/pom.xml b/ambassador/pom.xml
index a6d702426080..15e4a07f0dc3 100644
--- a/ambassador/pom.xml
+++ b/ambassador/pom.xml
@@ -34,6 +34,14 @@
4.0.0ambassador
+
+ org.slf4j
+ slf4j-api
+
+
+ ch.qos.logback
+ logback-classic
+ org.junit.jupiterjunit-jupiter-engine
diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/App.java b/ambassador/src/main/java/com/iluwatar/ambassador/App.java
index ff025d9b2bf6..8de149fe0813 100644
--- a/ambassador/src/main/java/com/iluwatar/ambassador/App.java
+++ b/ambassador/src/main/java/com/iluwatar/ambassador/App.java
@@ -28,8 +28,8 @@
* The ambassador pattern creates a helper service that sends network requests on behalf of a
* client. It is often used in cloud-based applications to offload features of a remote service.
*
- *
An ambassador service can be thought of as an out-of-process proxy that is co-located with
- * the client. Similar to the proxy design pattern, the ambassador service provides an interface for
+ *
An ambassador service can be thought of as an out-of-process proxy that is co-located with the
+ * client. Similar to the proxy design pattern, the ambassador service provides an interface for
* another remote service. In addition to the interface, the ambassador provides extra functionality
* and features, specifically offloaded common connectivity tasks. This usually consists of
* monitoring, logging, routing, security etc. This is extremely useful in legacy applications where
@@ -37,14 +37,11 @@
* capabilities.
*
*
In this example, we will the ({@link ServiceAmbassador}) class represents the ambassador while
- * the
- * ({@link RemoteService}) class represents a remote application.
+ * the ({@link RemoteService}) class represents a remote application.
*/
public class App {
- /**
- * Entry point.
- */
+ /** Entry point. */
public static void main(String[] args) {
var host1 = new Client();
var host2 = new Client();
diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/Client.java b/ambassador/src/main/java/com/iluwatar/ambassador/Client.java
index d0f81c1dd121..0baabf4ffc06 100644
--- a/ambassador/src/main/java/com/iluwatar/ambassador/Client.java
+++ b/ambassador/src/main/java/com/iluwatar/ambassador/Client.java
@@ -26,9 +26,7 @@
import lombok.extern.slf4j.Slf4j;
-/**
- * A simple Client.
- */
+/** A simple Client. */
@Slf4j
public class Client {
diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/RemoteService.java b/ambassador/src/main/java/com/iluwatar/ambassador/RemoteService.java
index eba634494fc7..d99348040cfe 100644
--- a/ambassador/src/main/java/com/iluwatar/ambassador/RemoteService.java
+++ b/ambassador/src/main/java/com/iluwatar/ambassador/RemoteService.java
@@ -29,9 +29,7 @@
import com.iluwatar.ambassador.util.RandomProvider;
import lombok.extern.slf4j.Slf4j;
-/**
- * A remote legacy application represented by a Singleton implementation.
- */
+/** A remote legacy application represented by a Singleton implementation. */
@Slf4j
public class RemoteService implements RemoteServiceInterface {
private static final int THRESHOLD = 200;
@@ -49,9 +47,7 @@ private RemoteService() {
this(Math::random);
}
- /**
- * This constructor is used for testing purposes only.
- */
+ /** This constructor is used for testing purposes only. */
RemoteService(RandomProvider randomProvider) {
this.randomProvider = randomProvider;
}
@@ -75,7 +71,8 @@ public long doRemoteFunction(int value) {
LOGGER.error("Thread sleep state interrupted", e);
Thread.currentThread().interrupt();
}
- return waitTime <= THRESHOLD ? value * 10
+ return waitTime <= THRESHOLD
+ ? value * 10
: RemoteServiceStatus.FAILURE.getRemoteServiceStatusValue();
}
}
diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceInterface.java b/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceInterface.java
index 104d81ec2eff..aa6012bae33f 100644
--- a/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceInterface.java
+++ b/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceInterface.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.ambassador;
-/**
- * Interface shared by ({@link RemoteService}) and ({@link ServiceAmbassador}).
- */
+/** Interface shared by ({@link RemoteService}) and ({@link ServiceAmbassador}). */
interface RemoteServiceInterface {
long doRemoteFunction(int value);
diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceStatus.java b/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceStatus.java
index 8f1a0a1a4907..8549ed7247f3 100644
--- a/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceStatus.java
+++ b/ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceStatus.java
@@ -29,17 +29,14 @@
/**
* Holds information regarding the status of the Remote Service.
*
- *
This Enum replaces the integer value previously
- * stored in {@link RemoteServiceInterface} as SonarCloud was identifying
- * it as an issue. All test cases have been checked after changes,
- * without failures.
+ *
This Enum replaces the integer value previously stored in {@link RemoteServiceInterface} as
+ * SonarCloud was identifying it as an issue. All test cases have been checked after changes,
+ * without failures.
*/
-
public enum RemoteServiceStatus {
FAILURE(-1);
- @Getter
- private final long remoteServiceStatusValue;
+ @Getter private final long remoteServiceStatusValue;
RemoteServiceStatus(long remoteServiceStatusValue) {
this.remoteServiceStatusValue = remoteServiceStatusValue;
diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/ServiceAmbassador.java b/ambassador/src/main/java/com/iluwatar/ambassador/ServiceAmbassador.java
index f3f30a09dc9b..4d310169770b 100644
--- a/ambassador/src/main/java/com/iluwatar/ambassador/ServiceAmbassador.java
+++ b/ambassador/src/main/java/com/iluwatar/ambassador/ServiceAmbassador.java
@@ -40,8 +40,7 @@ public class ServiceAmbassador implements RemoteServiceInterface {
private static final int RETRIES = 3;
private static final int DELAY_MS = 3000;
- ServiceAmbassador() {
- }
+ ServiceAmbassador() {}
@Override
public long doRemoteFunction(int value) {
diff --git a/ambassador/src/main/java/com/iluwatar/ambassador/util/RandomProvider.java b/ambassador/src/main/java/com/iluwatar/ambassador/util/RandomProvider.java
index e8243cdcc7cf..4eba2fada7fa 100644
--- a/ambassador/src/main/java/com/iluwatar/ambassador/util/RandomProvider.java
+++ b/ambassador/src/main/java/com/iluwatar/ambassador/util/RandomProvider.java
@@ -24,9 +24,7 @@
*/
package com.iluwatar.ambassador.util;
-/**
- * An interface for randomness. Useful for testing purposes.
- */
+/** An interface for randomness. Useful for testing purposes. */
public interface RandomProvider {
double random();
}
diff --git a/ambassador/src/test/java/com/iluwatar/ambassador/AppTest.java b/ambassador/src/test/java/com/iluwatar/ambassador/AppTest.java
index cea0eeac7bb9..ddb2d6eff411 100644
--- a/ambassador/src/test/java/com/iluwatar/ambassador/AppTest.java
+++ b/ambassador/src/test/java/com/iluwatar/ambassador/AppTest.java
@@ -24,25 +24,22 @@
*/
package com.iluwatar.ambassador;
-import org.junit.jupiter.api.Test;
-
import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
-/**
- * Application test
- */
+import org.junit.jupiter.api.Test;
+
+/** Application test */
class AppTest {
/**
* Issue: Add at least one assertion to this test case.
*
- * Solution: Inserted assertion to check whether the execution of the main method in {@link App}
- * throws an exception.
+ *
Solution: Inserted assertion to check whether the execution of the main method in {@link
+ * App} throws an exception.
*/
-
@Test
void shouldExecuteApplicationWithoutException() {
- assertDoesNotThrow(() -> App.main(new String[]{}));
+ assertDoesNotThrow(() -> App.main(new String[] {}));
}
}
diff --git a/ambassador/src/test/java/com/iluwatar/ambassador/ClientTest.java b/ambassador/src/test/java/com/iluwatar/ambassador/ClientTest.java
index ff7f027f64f1..24603efff9d4 100644
--- a/ambassador/src/test/java/com/iluwatar/ambassador/ClientTest.java
+++ b/ambassador/src/test/java/com/iluwatar/ambassador/ClientTest.java
@@ -24,13 +24,11 @@
*/
package com.iluwatar.ambassador;
-import org.junit.jupiter.api.Test;
-
import static org.junit.jupiter.api.Assertions.assertTrue;
-/**
- * Test for {@link Client}
- */
+import org.junit.jupiter.api.Test;
+
+/** Test for {@link Client} */
class ClientTest {
@Test
@@ -38,6 +36,7 @@ void test() {
Client client = new Client();
var result = client.useService(10);
- assertTrue(result == 100 || result == RemoteServiceStatus.FAILURE.getRemoteServiceStatusValue());
+ assertTrue(
+ result == 100 || result == RemoteServiceStatus.FAILURE.getRemoteServiceStatusValue());
}
}
diff --git a/ambassador/src/test/java/com/iluwatar/ambassador/RemoteServiceTest.java b/ambassador/src/test/java/com/iluwatar/ambassador/RemoteServiceTest.java
index 5fed19a169b1..81e4f744128f 100644
--- a/ambassador/src/test/java/com/iluwatar/ambassador/RemoteServiceTest.java
+++ b/ambassador/src/test/java/com/iluwatar/ambassador/RemoteServiceTest.java
@@ -29,9 +29,7 @@
import com.iluwatar.ambassador.util.RandomProvider;
import org.junit.jupiter.api.Test;
-/**
- * Test for {@link RemoteService}
- */
+/** Test for {@link RemoteService} */
class RemoteServiceTest {
@Test
diff --git a/ambassador/src/test/java/com/iluwatar/ambassador/ServiceAmbassadorTest.java b/ambassador/src/test/java/com/iluwatar/ambassador/ServiceAmbassadorTest.java
index 50c354c1485a..0543b2e7e370 100644
--- a/ambassador/src/test/java/com/iluwatar/ambassador/ServiceAmbassadorTest.java
+++ b/ambassador/src/test/java/com/iluwatar/ambassador/ServiceAmbassadorTest.java
@@ -24,18 +24,17 @@
*/
package com.iluwatar.ambassador;
-import org.junit.jupiter.api.Test;
-
import static org.junit.jupiter.api.Assertions.assertTrue;
-/**
- * Test for {@link ServiceAmbassador}
- */
+import org.junit.jupiter.api.Test;
+
+/** Test for {@link ServiceAmbassador} */
class ServiceAmbassadorTest {
@Test
void test() {
long result = new ServiceAmbassador().doRemoteFunction(10);
- assertTrue(result == 100 || result == RemoteServiceStatus.FAILURE.getRemoteServiceStatusValue());
+ assertTrue(
+ result == 100 || result == RemoteServiceStatus.FAILURE.getRemoteServiceStatusValue());
}
}
diff --git a/anti-corruption-layer/README.md b/anti-corruption-layer/README.md
index bcffc3595237..9b6042850eba 100644
--- a/anti-corruption-layer/README.md
+++ b/anti-corruption-layer/README.md
@@ -1,11 +1,19 @@
---
-title: Anti-corruption layer
+title: "Anti-Corruption Layer Pattern in Java: Ensuring System Integrity Amidst Legacy Systems"
+shortTitle: Anti-Corruption Layer
+description: "Learn how the Anti-Corruption Layer design pattern helps in decoupling subsystems, preventing data corruption, and facilitating seamless integration in Java applications."
category: Integration
language: en
tag:
- Architecture
- Decoupling
+ - Integration
- Isolation
+ - Layered architecture
+ - Migration
+ - Modernization
+ - Refactoring
+ - Wrapping
---
## Also known as
@@ -14,37 +22,43 @@ tag:
* Interface layer
* Translation layer
-## Intent
+## Intent of Anti-Corruption Layer Design Pattern
-Implement a façade or adapter layer between different subsystems that don't share the same semantics. It translates between different data formats and systems, ensuring that the integration between systems does not lead to corruption of business logic or data integrity.
+The Anti-Corruption Layer (ACL) is a crucial design pattern in Java development, particularly for system integration and maintaining data integrity. Implement a façade or adapter layer between different subsystems that don't share the same semantics. It translates between different data formats and systems, ensuring that the integration between systems does not lead to corruption of business logic or data integrity.
-## Explanation
+## Detailed Explanation of Anti-Corruption Layer Pattern with Real-World Examples
-### Context and problem
+Real-world example
-Most applications rely on other systems for some data or functionality. For example, when a legacy application is migrated to a modern system, it may still need existing legacy resources. New features must be able to call the legacy system. This is especially true of gradual migrations, where different features of a larger application are moved to a modern system over time.
+> This example demonstrates how the Anti-Corruption Layer ensures seamless integration between legacy systems and modern platforms, crucial for maintaining business logic integrity during system migration.
+>
+> Imagine a large retail company transitioning its inventory management system from an old legacy software to a new modern platform. The legacy system has been in use for decades and contains complex business rules and data formats that are incompatible with the new system. Instead of directly connecting the new system to the legacy one, the company implements an Anti-Corruption Layer (ACL).
+>
+> The ACL acts as a mediator, translating and adapting data between the two systems. When the new system requests inventory data, the ACL translates the request into a format the legacy system understands, retrieves the data, and then translates it back into a format suitable for the new system. This approach ensures that the new system remains unaffected by the intricacies of the legacy system, preventing corruption of data and business logic while facilitating a smooth transition.
-Often these legacy systems suffer from quality issues such as convoluted data schemas or obsolete APIs. The features and technologies used in legacy systems can vary widely from more modern systems. To interoperate with the legacy system, the new application may need to support outdated infrastructure, protocols, data models, APIs, or other features that you wouldn't otherwise put into a modern application.
+In plain words
-Maintaining access between new and legacy systems can force the new system to adhere to at least some of the legacy system's APIs or other semantics. When these legacy features have quality issues, supporting them "corrupts" what might otherwise be a cleanly designed modern application. Similar issues can arise with any external system that your development team doesn't control, not just legacy systems.
+> The Anti-Corruption Layer design pattern protects a system from the complexities and changes of external systems by providing an intermediary translation layer.
-### Solution
+[Microsoft's documentation](https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer) says
-Isolate the different subsystems by placing an anti-corruption layer between them. This layer translates communications between the two systems, allowing one system to remain unchanged while the other can avoid compromising its design and technological approach.
+> Implement a façade or adapter layer between different subsystems that don't share the same semantics. This layer translates requests that one subsystem makes to the other subsystem. Use this pattern to ensure that an application's design is not limited by dependencies on outside subsystems. This pattern was first described by Eric Evans in Domain-Driven Design.
-### Programmatic example
+Sequence diagram
-#### Introduction
+
-The example shows why the anti-corruption layer is needed.
+## Programmatic Example of Anti-Corruption Layer Pattern in Java
+
+The ACL design pattern in Java provides an intermediary layer that translates data formats, ensuring that integration between different systems does not lead to data corruption.
Here are 2 shop-ordering systems: `Legacy` and `Modern`.
-The aforementioned systems have different domain models and have to operate simultaneously. Since they work independently the orders can come either from the `Legacy` or `Modern` system. Therefore, the system that receives the legacyOrder needs to check if the legacyOrder is valid and not present in the other system. Then it can place the legacyOrder in its own system.
+The aforementioned systems have different domain models and have to operate simultaneously. Since they work independently the orders can come either from the `Legacy` or `Modern` system. Therefore, the system that receives the legacyOrder needs to check if the legacyOrder is valid and not present in the other system. Then it can place the legacyOrder in its own system.
But for that, the system needs to know the domain model of the other system and to avoid that, the anti-corruption layer(ACL) is introduced. The ACL is a layer that translates the domain model of the `Legacy` system to the domain model of the `Modern` system and vice versa. Also, it hides all other operations with the other system, uncoupling the systems.
-#### Domain model of the `Legacy` system
+Domain model of the `Legacy` system:
```java
public class LegacyOrder {
@@ -56,7 +70,7 @@ public class LegacyOrder {
}
```
-#### Domain model of the `Modern` system
+Domain model of the `Modern` system:
```java
public class ModernOrder {
@@ -67,9 +81,11 @@ public class ModernOrder {
private String extra;
}
+
public class Customer {
private String address;
}
+
public class Shipment {
private String item;
private String qty;
@@ -77,7 +93,7 @@ public class Shipment {
}
```
-#### Anti-corruption layer
+Anti-corruption layer:
```java
public class AntiCorruptionLayer {
@@ -99,9 +115,7 @@ public class AntiCorruptionLayer {
}
```
-#### The connection
-
-Wherever the `Legacy` or `Modern` system needs to communicate with the counterpart the ACL needs to be used to avoid corrupting the current domain model. The example below shows how the `Legacy` system places an order with a validation from the `Modern` system.
+The connection between the systems. Wherever the `Legacy` or `Modern` system needs to communicate with the counterpart the ACL needs to be used to avoid corrupting the current domain model. The example below shows how the `Legacy` system places an order with a validation from the `Modern` system.
```java
public class LegacyShop {
@@ -112,7 +126,7 @@ public class LegacyShop {
String id = legacyOrder.getId();
- Optional orderInModernSystem = acl.findOrderInModernSystem(id);
+ Optional orderInModernSystem = acl.findOrderInModernSystem(id);
if (orderInModernSystem.isPresent()) {
// order is already in the modern system
@@ -123,7 +137,7 @@ public class LegacyShop {
}
```
-## Applicability
+## When to Use the Anti-Corruption Layer Pattern in Java
Use this pattern when:
@@ -133,18 +147,18 @@ Use this pattern when:
* In scenarios where different subsystems within a larger system use different data formats or structures
* When there is a need to ensure loose coupling between different subsystems or external services to facilitate easier maintenance and scalability
-## Tutorials
+## Anti-Corruption Layer Pattern Java Tutorials
-* [Microsoft - Anti-Corruption Layer](https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer)
-* [Amazon - Anti-Corruption Layer](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/acl.html)
+* [Anti-Corruption Layer (Microsoft)](https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer)
+* [Anti-Corruption Layer Pattern (Amazon)](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/acl.html)
-## Known Uses
+## Real-World Applications of Anti-Corruption Layer Pattern in Java
* Microservices architectures where individual services must communicate without being tightly coupled to each other’s data schemas
* Enterprise systems integration, especially when integrating modern systems with legacy systems
* In bounded contexts within Domain-Driven Design (DDD) to maintain the integrity of a domain model when interacting with external systems or subsystems
-## Consequences
+## Benefits and Trade-offs of Anti-Corruption Layer Pattern
Benefits:
@@ -158,13 +172,14 @@ Trade-offs:
* Requires extra effort in design and implementation to ensure the layer is effective without becoming a bottleneck
* Can lead to duplication of models if not carefully managed
-## Related Patterns
+## Related Java Design Patterns
-* [Facade](https://java-design-patterns.com/patterns/facade/): The Anti-Corruption Layer can be seen as a specialized form of the Facade pattern that is used to isolate different subsystems
* [Adapter](https://java-design-patterns.com/patterns/adapter/): The Anti-Corruption Layer can be implemented using the Adapter pattern to translate between different data formats or structures
+* [Facade](https://java-design-patterns.com/patterns/facade/): The Anti-Corruption Layer can be seen as a specialized form of the Facade pattern that is used to isolate different subsystems
* [Gateway](https://java-design-patterns.com/patterns/gateway/): The Anti-Corruption Layer can be used as a Gateway to external systems to provide a unified interface
-## Credits
+## References and Credits
* [Domain-Driven Design: Tackling Complexity in the Heart of Software](https://amzn.to/3vptcJz)
* [Implementing Domain-Driven Design](https://amzn.to/3ISOSRA)
+* [Patterns of Enterprise Application Architecture](https://amzn.to/3WfKBPR)
diff --git a/anti-corruption-layer/etc/anti-corruption-layer-sequence-diagram.png b/anti-corruption-layer/etc/anti-corruption-layer-sequence-diagram.png
new file mode 100644
index 000000000000..835ff4e84a0f
Binary files /dev/null and b/anti-corruption-layer/etc/anti-corruption-layer-sequence-diagram.png differ
diff --git a/anti-corruption-layer/etc/anti-corruption-layer.urm.png b/anti-corruption-layer/etc/anti-corruption-layer.urm.png
new file mode 100644
index 000000000000..96e432121e7e
Binary files /dev/null and b/anti-corruption-layer/etc/anti-corruption-layer.urm.png differ
diff --git a/anti-corruption-layer/pom.xml b/anti-corruption-layer/pom.xml
index 711e006b7076..2fddfd3ecc46 100644
--- a/anti-corruption-layer/pom.xml
+++ b/anti-corruption-layer/pom.xml
@@ -45,8 +45,8 @@
test
Often these legacy systems suffer from quality issues such as convoluted data schemas
- * or obsolete APIs.
- * The features and technologies used in legacy systems can vary widely from more modern systems.
- * To interoperate with the legacy system,
- * the new application may need to support outdated infrastructure, protocols, data models, APIs,
- * or other features that you wouldn't otherwise put into a modern application.
+ *
Often these legacy systems suffer from quality issues such as convoluted data schemas or
+ * obsolete APIs. The features and technologies used in legacy systems can vary widely from more
+ * modern systems. To interoperate with the legacy system, the new application may need to support
+ * outdated infrastructure, protocols, data models, APIs, or other features that you wouldn't
+ * otherwise put into a modern application.
*
- *
Maintaining access between new and legacy systems can force the new system to adhere to
- * at least some of the legacy system's APIs or other semantics.
- * When these legacy features have quality issues, supporting them "corrupts" what might
- * otherwise be a cleanly designed modern application.
- * Similar issues can arise with any external system that your development team doesn't control,
- * not just legacy systems.
+ *
Maintaining access between new and legacy systems can force the new system to adhere to at
+ * least some of the legacy system's APIs or other semantics. When these legacy features have
+ * quality issues, supporting them "corrupts" what might otherwise be a cleanly designed modern
+ * application. Similar issues can arise with any external system that your development team doesn't
+ * control, not just legacy systems.
*
*
- * The 2 shops (modern and legacy) should operate independently and in the same time synchronize the data.
- * To avoid corrupting the domain models of the 2 shops, we use an anti-corruption layer
- * that transforms one model to another under the hood.
- *
- */
- @Test
- public void antiCorruptionLayerTest() throws ShopException {
-
- // a new order comes to the legacy shop.
- LegacyOrder legacyOrder = new LegacyOrder("1", "addr1", "item1", 1, 1);
- // place the order in the legacy shop.
- legacyShop.placeOrder(legacyOrder);
- // the order is placed as usual since there is no other orders with the id in the both systems.
- Optional legacyOrderWithIdOne = legacyShop.findOrder("1");
- assertEquals(Optional.of(legacyOrder), legacyOrderWithIdOne);
-
- // a new order (or maybe just the same order) appears in the modern shop.
- ModernOrder modernOrder = new ModernOrder("1", new Customer("addr1"), new Shipment("item1", 1, 1), "");
-
- // the system places it, but it checks if there is an order with the same id in the legacy shop.
- modernShop.placeOrder(modernOrder);
-
- Optional modernOrderWithIdOne = modernShop.findOrder("1");
- // there is no new order placed since there is already an order with the same id in the legacy shop.
- assertTrue(modernOrderWithIdOne.isEmpty());
-
- }
- /**
- * Test the anti-corruption layer.
- * Main intention is to demonstrate how the anti-corruption layer works.
- *
- * This test tests the anti-corruption layer from the rule the orders should be the same in the both systems.
- *
- */
- @Test(expected = ShopException.class)
- public void antiCorruptionLayerWithExTest() throws ShopException {
-
- // a new order comes to the legacy shop.
- LegacyOrder legacyOrder = new LegacyOrder("1", "addr1", "item1", 1, 1);
- // place the order in the legacy shop.
- legacyShop.placeOrder(legacyOrder);
- // the order is placed as usual since there is no other orders with the id in the both systems.
- Optional legacyOrderWithIdOne = legacyShop.findOrder("1");
- assertEquals(Optional.of(legacyOrder), legacyOrderWithIdOne);
-
- // a new order but with the same id and different data appears in the modern shop
- ModernOrder modernOrder = new ModernOrder("1", new Customer("addr1"), new Shipment("item1", 10, 1), "");
-
- // the system rejects the order since there are 2 orders with contradiction there.
- modernShop.placeOrder(modernOrder);
-
-
- }
-}
\ No newline at end of file
+ @Autowired private LegacyShop legacyShop;
+
+ @Autowired private ModernShop modernShop;
+
+ /**
+ * Test the anti-corruption layer. Main intention is to demonstrate how the anti-corruption layer
+ * works. The 2 shops (modern and legacy) should operate independently and in the same time
+ * synchronize the data.
+ */
+ @Test
+ public void antiCorruptionLayerTest() throws ShopException {
+ // a new order comes to the legacy shop.
+ LegacyOrder legacyOrder = new LegacyOrder("1", "addr1", "item1", 1, 1);
+ // place the order in the legacy shop.
+ legacyShop.placeOrder(legacyOrder);
+ // the order is placed as usual since there is no other orders with the id in the both systems.
+ Optional legacyOrderWithIdOne = legacyShop.findOrder("1");
+ assertEquals(Optional.of(legacyOrder), legacyOrderWithIdOne);
+
+ // a new order (or maybe just the same order) appears in the modern shop
+ ModernOrder modernOrder =
+ new ModernOrder("1", new Customer("addr1"), new Shipment("item1", 1, 1), "");
+ // the system places it, but it checks if there is an order with the same id in the legacy shop.
+ modernShop.placeOrder(modernOrder);
+
+ Optional modernOrderWithIdOne = modernShop.findOrder("1");
+ // there is no new order placed since there is already an order with the same id in the legacy
+ // shop.
+ assertTrue(modernOrderWithIdOne.isEmpty());
+ }
+
+ /**
+ * Test the anti-corruption layer when a conflict occurs between systems. This test ensures that
+ * an exception is thrown when conflicting orders are placed.
+ */
+ @Test
+ public void antiCorruptionLayerWithExTest() throws ShopException {
+ // a new order comes to the legacy shop.
+ LegacyOrder legacyOrder = new LegacyOrder("1", "addr1", "item1", 1, 1);
+ // place the order in the legacy shop.
+ legacyShop.placeOrder(legacyOrder);
+ // the order is placed as usual since there is no other orders with the id in the both systems.
+ Optional legacyOrderWithIdOne = legacyShop.findOrder("1");
+ assertEquals(Optional.of(legacyOrder), legacyOrderWithIdOne);
+ // a new order but with the same id and different data appears in the modern shop
+ ModernOrder modernOrder =
+ new ModernOrder("1", new Customer("addr1"), new Shipment("item1", 10, 1), "");
+ // the system rejects the order since there are 2 orders with contradiction there.
+ assertThrows(ShopException.class, () -> modernShop.placeOrder(modernOrder));
+ }
+}
diff --git a/api-gateway/README.md b/api-gateway/README.md
deleted file mode 100644
index 40d5f4dc445e..000000000000
--- a/api-gateway/README.md
+++ /dev/null
@@ -1,201 +0,0 @@
----
-title: API Gateway
-category: Architectural
-language: en
-tag:
- - API design
- - Cloud distributed
- - Decoupling
- - Microservices
----
-
-## Intent
-
-The API Gateway design pattern aims to provide a unified interface to a set of microservices. It acts as a single entry point for clients, routing requests to the appropriate microservices and aggregating results, thereby simplifying the client-side code.
-
-## Also known as
-
-* Backend for Frontends (BFF)
-
-## Explanation
-
-With the Microservices pattern, a client may need data from multiple different microservices. If the
-client called each microservice directly, that could contribute to longer load times, since the
-client would have to make a network request for each microservice called. Moreover, having the
-client call each microservice directly ties the client to that microservice - if the internal
-implementations of the microservices change (for example, if two microservices are combined sometime
-in the future) or if the location (host and port) of a microservice changes, then every client that
-makes use of those microservices must be updated.
-
-The intent of the API Gateway pattern is to alleviate some of these issues. In the API Gateway
-pattern, an additional entity (the API Gateway) is placed between the client and the microservices.
-The job of the API Gateway is to aggregate the calls to the microservices. Rather than the client
-calling each microservice individually, the client calls the API Gateway a single time. The API
-Gateway then calls each of the microservices that the client needs.
-
-Real world example
-
-> We are implementing microservices and API Gateway pattern for an e-commerce site. In this system
-> the API Gateway makes calls to the Image and Price microservices.
-
-In plain words
-
-> For a system implemented using microservices architecture, API Gateway is the single entry point
-> that aggregates the calls to the individual microservices.
-
-Wikipedia says
-
-> API Gateway is a server that acts as an API front-end, receives API requests, enforces throttling
-> and security policies, passes requests to the back-end service and then passes the response back
-> to the requester. A gateway often includes a transformation engine to orchestrate and modify the
-> requests and responses on the fly. A gateway can also provide functionality such as collecting
-> analytics data and providing caching. The gateway can provide functionality to support
-> authentication, authorization, security, audit and regulatory compliance.
-
-**Programmatic Example**
-
-This implementation shows what the API Gateway pattern could look like for an e-commerce site. The
-`ApiGateway` makes calls to the Image and Price microservices using the `ImageClientImpl` and
-`PriceClientImpl` respectively. Customers viewing the site on a desktop device can see both price
-information and an image of a product, so the `ApiGateway` calls both of the microservices and
-aggregates the data in the `DesktopProduct` model. However, mobile users only see price information;
-they do not see a product image. For mobile users, the `ApiGateway` only retrieves price
-information, which it uses to populate the `MobileProduct`.
-
-Here's the Image microservice implementation.
-
-```java
-public interface ImageClient {
- String getImagePath();
-}
-
-public class ImageClientImpl implements ImageClient {
- @Override
- public String getImagePath() {
- var httpClient = HttpClient.newHttpClient();
- var httpGet = HttpRequest.newBuilder()
- .GET()
- .uri(URI.create("http://localhost:50005/image-path"))
- .build();
-
- try {
- var httpResponse = httpClient.send(httpGet, BodyHandlers.ofString());
- return httpResponse.body();
- } catch (IOException | InterruptedException e) {
- e.printStackTrace();
- }
-
- return null;
- }
-}
-```
-
-Here's the Price microservice implementation.
-
-```java
-public interface PriceClient {
- String getPrice();
-}
-
-public class PriceClientImpl implements PriceClient {
-
- @Override
- public String getPrice() {
- var httpClient = HttpClient.newHttpClient();
- var httpGet = HttpRequest.newBuilder()
- .GET()
- .uri(URI.create("http://localhost:50006/price"))
- .build();
-
- try {
- var httpResponse = httpClient.send(httpGet, BodyHandlers.ofString());
- return httpResponse.body();
- } catch (IOException | InterruptedException e) {
- e.printStackTrace();
- }
-
- return null;
- }
-}
-```
-
-Here we can see how API Gateway maps the requests to the microservices.
-
-```java
-public class ApiGateway {
-
- @Resource
- private ImageClient imageClient;
-
- @Resource
- private PriceClient priceClient;
-
- @RequestMapping(path = "/desktop", method = RequestMethod.GET)
- public DesktopProduct getProductDesktop() {
- var desktopProduct = new DesktopProduct();
- desktopProduct.setImagePath(imageClient.getImagePath());
- desktopProduct.setPrice(priceClient.getPrice());
- return desktopProduct;
- }
-
- @RequestMapping(path = "/mobile", method = RequestMethod.GET)
- public MobileProduct getProductMobile() {
- var mobileProduct = new MobileProduct();
- mobileProduct.setPrice(priceClient.getPrice());
- return mobileProduct;
- }
-}
-```
-
-## Class diagram
-
-
-
-## Applicability
-
-* When building a microservices architecture, and there's a need to abstract the complexity of microservices from the client.
-* When multiple microservices need to be consumed in a single request.
-* For authentication, authorization, and security enforcement at a single point.
-* To optimize communication between clients and services, especially in a cloud environment.
-
-## Consequences
-
-Benefits:
-
-* Decouples client from microservices, allowing services to evolve independently.
-* Simplifies client by aggregating requests to multiple services.
-* Centralized location for cross-cutting concerns like security, logging, and rate limiting.
-* Potential for performance optimizations like caching and request compression.
-
-Trade-offs:
-
-* Introduces a single point of failure, although this can be mitigated with high availability setups.
-* Can become a bottleneck if not properly scaled.
-* Adds complexity in terms of deployment and management.
-
-## Known uses
-
-* E-commerce platforms where multiple services (product info, pricing, inventory) are aggregated for a single view.
-* Mobile applications that consume various backend services but require a simplified interface for ease of use.
-* Cloud-native applications that leverage multiple microservices architectures.
-
-## Related patterns
-
-* [Aggregator Microservice](../aggregator-microservices/README.md) - The API Gateway pattern is often used in conjunction with the Aggregator Microservice pattern to provide a unified interface to a set of microservices.
-* [Proxy](../proxy/README.md) - The API Gateway pattern is a specialized form of the Proxy pattern, where the gateway acts as a single entry point for clients, routing requests to the appropriate microservices and aggregating results.
-* [Circuit Breaker](../circuit-breaker/README.md) - API Gateways can use the Circuit Breaker pattern to prevent cascading failures when calling multiple microservices.
-
-## Tutorials
-
-* [Exploring the New Spring Cloud Gateway](https://www.baeldung.com/spring-cloud-gateway)
-* [Spring Cloud - Gateway](https://www.tutorialspoint.com/spring_cloud/spring_cloud_gateway.htm)
-* [Getting Started With Spring Cloud Gateway](https://dzone.com/articles/getting-started-with-spring-cloud-gateway)
-
-## Credits
-
-* [microservices.io - API Gateway](http://microservices.io/patterns/apigateway.html)
-* [NGINX - Building Microservices: Using an API Gateway](https://www.nginx.com/blog/building-microservices-using-an-api-gateway/)
-* [Microservices Patterns: With examples in Java](https://www.amazon.com/gp/product/1617294543/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=1617294543&linkId=ac7b6a57f866ac006a309d9086e8cfbd)
-* [Building Microservices: Designing Fine-Grained Systems](https://www.amazon.com/gp/product/1491950358/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=1491950358&linkId=4c95ca9831e05e3f0dadb08841d77bf1)
-* [Designing Data-Intensive Applications](https://amzn.to/3PfRk7Y)
-* [Cloud Native Patterns: Designing change-tolerant software](https://amzn.to/3uV12WN)
diff --git a/arrange-act-assert/README.md b/arrange-act-assert/README.md
index 9c6d614b9df3..584d8601a23e 100644
--- a/arrange-act-assert/README.md
+++ b/arrange-act-assert/README.md
@@ -1,146 +1,145 @@
---
-title: Arrange/Act/Assert
+title: "Arrange/Act/Assert Pattern in Java: Enhance Testing Clarity and Simplicity"
+shortTitle: Arrange/Act/Assert
+description: "Learn how to use the Arrange/Act/Assert pattern to structure your unit tests in Java. Improve readability and maintainability of your code with clear testing phases."
category: Testing
language: en
tag:
- - Idiom
+ - Code simplification
+ - Isolation
- Testing
---
## Also known as
-Given/When/Then
+* Given/When/Then
-## Intent
+## Intent of Arrange/Act/Assert Design Pattern
-Arrange/Act/Assert (AAA) is a pattern for organizing unit tests.
-It breaks tests down into three clear and distinct steps:
+The Arrange/Act/Assert pattern is essential in unit testing in Java. This testing method structures unit tests clearly by dividing them into three distinct sections: setup (Arrange), execution (Act), and verification (Assert).
-1. Arrange: Perform the setup and initialization required for the test.
-2. Act: Take action(s) required for the test.
-3. Assert: Verify the outcome(s) of the test.
+## Detailed Explanation of Arrange/Act/Assert Pattern with Real-World Examples
-## Explanation
+Real-world example
-This pattern has several significant benefits. It creates a clear separation between a test's
-setup, operations, and results. This structure makes the code easier to read and understand. If
-you place the steps in order and format your code to separate them, you can scan a test and
-quickly comprehend what it does.
+> Imagine you are organizing a small event. To ensure everything runs smoothly, you follow a pattern similar to Arrange/Act/Assert:
+>
+> 1. **Arrange**: You set up the venue, prepare the guest list, arrange seating, and organize the catering.
+> 2. **Act**: You conduct the event according to the plan, welcoming guests, serving food, and following the schedule.
+> 3. **Assert**: After the event, you evaluate its success by checking guest feedback, ensuring all tasks were completed, and reviewing if everything went as planned.
+>
+> This clear separation of preparation, execution, and evaluation helps ensure the event is well-organized and successful, mirroring the structured approach of the Arrange/Act/Assert pattern in software testing.
-It also enforces a certain degree of discipline when you write your tests. You have to think
-clearly about the three steps your test will perform. It makes tests more natural to write at
-the same time since you already have an outline.
+In plain words
-Real world example
+> Arrange/Act/Assert is a testing pattern that organizes tests into three clear steps for easy maintenance.
-> We need to write comprehensive and clear unit test suite for a class.
+WikiWikiWeb says
-In plain words
+> Arrange/Act/Assert is a pattern for arranging and formatting code in UnitTest methods.
-> Arrange/Act/Assert is a testing pattern that organizes tests into three clear steps for easy
-> maintenance.
+Flowchart
-WikiWikiWeb says
+
-> Arrange/Act/Assert is a pattern for arranging and formatting code in UnitTest methods.
+## Programmatic Example of Arrange/Act/Assert Pattern in Java
-**Programmatic Example**
+We need to write comprehensive and clear unit test suite for a class. Using the Arrange/Act/Assert pattern in Java testing ensures clarity.
Let's first introduce our `Cash` class to be unit tested.
```java
public class Cash {
- private int amount;
+ private int amount;
- Cash(int amount) {
- this.amount = amount;
- }
+ Cash(int amount) {
+ this.amount = amount;
+ }
- void plus(int addend) {
- amount += addend;
- }
+ void plus(int addend) {
+ amount += addend;
+ }
- boolean minus(int subtrahend) {
- if (amount >= subtrahend) {
- amount -= subtrahend;
- return true;
- } else {
- return false;
+ boolean minus(int subtrahend) {
+ if (amount >= subtrahend) {
+ amount -= subtrahend;
+ return true;
+ } else {
+ return false;
+ }
}
- }
- int count() {
- return amount;
- }
+ int count() {
+ return amount;
+ }
}
```
-Then we write our unit tests according to Arrange/Act/Assert pattern. Notice the clearly
-separated steps for each unit test.
+Then we write our unit tests according to Arrange/Act/Assert pattern. Notice the clearly separated steps for each unit test.
```java
class CashAAATest {
- @Test
- void testPlus() {
- //Arrange
- var cash = new Cash(3);
- //Act
- cash.plus(4);
- //Assert
- assertEquals(7, cash.count());
- }
-
- @Test
- void testMinus() {
- //Arrange
- var cash = new Cash(8);
- //Act
- var result = cash.minus(5);
- //Assert
- assertTrue(result);
- assertEquals(3, cash.count());
- }
-
- @Test
- void testInsufficientMinus() {
- //Arrange
- var cash = new Cash(1);
- //Act
- var result = cash.minus(6);
- //Assert
- assertFalse(result);
- assertEquals(1, cash.count());
- }
-
- @Test
- void testUpdate() {
- //Arrange
- var cash = new Cash(5);
- //Act
- cash.plus(6);
- var result = cash.minus(3);
- //Assert
- assertTrue(result);
- assertEquals(8, cash.count());
- }
+ @Test
+ void testPlus() {
+ //Arrange
+ var cash = new Cash(3);
+ //Act
+ cash.plus(4);
+ //Assert
+ assertEquals(7, cash.count());
+ }
+
+ @Test
+ void testMinus() {
+ //Arrange
+ var cash = new Cash(8);
+ //Act
+ var result = cash.minus(5);
+ //Assert
+ assertTrue(result);
+ assertEquals(3, cash.count());
+ }
+
+ @Test
+ void testInsufficientMinus() {
+ //Arrange
+ var cash = new Cash(1);
+ //Act
+ var result = cash.minus(6);
+ //Assert
+ assertFalse(result);
+ assertEquals(1, cash.count());
+ }
+
+ @Test
+ void testUpdate() {
+ //Arrange
+ var cash = new Cash(5);
+ //Act
+ cash.plus(6);
+ var result = cash.minus(3);
+ //Assert
+ assertTrue(result);
+ assertEquals(8, cash.count());
+ }
}
```
-## Applicability
+## When to Use the Arrange/Act/Assert Pattern in Java
Use Arrange/Act/Assert pattern when
-* Unit testing, especially within the context of TDD and BDD
+* Unit testing, especially within the context of TDD and BDD
* Anywhere clarity and structure are needed in test cases
-## Known uses
+## Real-World Applications of Arrange/Act/Assert Pattern in Java
-* Widely adopted in software projects using TDD and BDD methodologies.
+* This pattern is particularly useful when practicing TDD and/or BDD methodologies in Java.
* Utilized in various programming languages and testing frameworks, such as JUnit (Java), NUnit (.NET), and xUnit frameworks.
-## Consequences
+## Benefits and Trade-offs of Arrange/Act/Assert Pattern
Benefits:
@@ -153,16 +152,16 @@ Trade-offs:
* May introduce redundancy in tests, as similar arrangements may be repeated across tests.
* Some complex tests might not fit neatly into this structure, requiring additional context or setup outside these three phases.
-## Related patterns
+## Related Java Design Patterns
* [Page Object](https://java-design-patterns.com/patterns/page-object/): A pattern for organizing UI tests that can be used in conjunction with Arrange/Act/Assert.
-## Credits
+## References and Credits
-* [Arrange, Act, Assert: What is AAA Testing?](https://blog.ncrunch.net/post/arrange-act-assert-aaa-testing.aspx)
-* [Bill Wake: 3A – Arrange, Act, Assert](https://xp123.com/articles/3a-arrange-act-assert/)
-* [Martin Fowler: GivenWhenThen](https://martinfowler.com/bliki/GivenWhenThen.html)
-* [xUnit Test Patterns: Refactoring Test Code](https://www.amazon.com/gp/product/0131495054/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=0131495054&linkId=99701e8f4af2f7e8dd50d720c9b63dbf)
-* [Unit Testing Principles, Practices, and Patterns](https://www.amazon.com/gp/product/1617296279/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=1617296279&linkId=74c75cf22a63c3e4758ae08aa0a0cc35)
-* [Test Driven Development: By Example](https://www.amazon.com/gp/product/0321146530/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=0321146530&linkId=5c63a93d8c1175b84ca5087472ef0e05)
* [The Art of Unit Testing: with examples in C#](https://amzn.to/49IbdwO)
+* [Test Driven Development: By Example](https://amzn.to/3wEwKbF)
+* [Unit Testing Principles, Practices, and Patterns: Effective testing styles, patterns, and reliable automation for unit testing, mocking, and integration testing with examples in C#](https://amzn.to/4ayjpiM)
+* [xUnit Test Patterns: Refactoring Test Code](https://amzn.to/4dHGDpm)
+* [Arrange, Act, Assert: What is AAA Testing?](https://blog.ncrunch.net/post/arrange-act-assert-aaa-testing.aspx)
+* [Bill Wake: 3A – Arrange, Act, Assert (NCrunch)](https://xp123.com/articles/3a-arrange-act-assert/)
+* [GivenWhenThen (Martin Fowler)](https://martinfowler.com/bliki/GivenWhenThen.html)
diff --git a/arrange-act-assert/etc/arrange-act-assert-flowchart.png b/arrange-act-assert/etc/arrange-act-assert-flowchart.png
new file mode 100644
index 000000000000..8b7615352523
Binary files /dev/null and b/arrange-act-assert/etc/arrange-act-assert-flowchart.png differ
diff --git a/arrange-act-assert/src/main/java/com/iluwatar/arrangeactassert/Cash.java b/arrange-act-assert/src/main/java/com/iluwatar/arrangeactassert/Cash.java
index c3f5e6fe43e1..0c31b1f89f44 100644
--- a/arrange-act-assert/src/main/java/com/iluwatar/arrangeactassert/Cash.java
+++ b/arrange-act-assert/src/main/java/com/iluwatar/arrangeactassert/Cash.java
@@ -35,12 +35,12 @@ public class Cash {
private int amount;
- //plus
+ // plus
void plus(int addend) {
amount += addend;
}
- //minus
+ // minus
boolean minus(int subtrahend) {
if (amount >= subtrahend) {
amount -= subtrahend;
@@ -50,7 +50,7 @@ boolean minus(int subtrahend) {
}
}
- //count
+ // count
int count() {
return amount;
}
diff --git a/arrange-act-assert/src/test/java/com/iluwatar/arrangeactassert/CashAAATest.java b/arrange-act-assert/src/test/java/com/iluwatar/arrangeactassert/CashAAATest.java
index b771cb6e7dee..ebb261277080 100644
--- a/arrange-act-assert/src/test/java/com/iluwatar/arrangeactassert/CashAAATest.java
+++ b/arrange-act-assert/src/test/java/com/iluwatar/arrangeactassert/CashAAATest.java
@@ -35,8 +35,11 @@
* tests, so they're easier to read, maintain and enhance.
*
*
It breaks tests down into three clear and distinct steps:
+ *
*
1. Arrange: Perform the setup and initialization required for the test.
+ *
*
2. Act: Take action(s) required for the test.
+ *
*
3. Assert: Verify the outcome(s) of the test.
*
*
This pattern has several significant benefits. It creates a clear separation between a test's
@@ -48,53 +51,52 @@
* clearly about the three steps your test will perform. But it makes tests more natural to write at
* the same time since you already have an outline.
*
- *
In ({@link CashAAATest}) we have four test methods. Each of them has only one reason to
- * change and one reason to fail. In a large and complicated code base, tests that honor the single
+ *
In ({@link CashAAATest}) we have four test methods. Each of them has only one reason to change
+ * and one reason to fail. In a large and complicated code base, tests that honor the single
* responsibility principle are much easier to troubleshoot.
*/
-
class CashAAATest {
@Test
void testPlus() {
- //Arrange
+ // Arrange
var cash = new Cash(3);
- //Act
+ // Act
cash.plus(4);
- //Assert
+ // Assert
assertEquals(7, cash.count());
}
@Test
void testMinus() {
- //Arrange
+ // Arrange
var cash = new Cash(8);
- //Act
+ // Act
var result = cash.minus(5);
- //Assert
+ // Assert
assertTrue(result);
assertEquals(3, cash.count());
}
@Test
void testInsufficientMinus() {
- //Arrange
+ // Arrange
var cash = new Cash(1);
- //Act
+ // Act
var result = cash.minus(6);
- //Assert
+ // Assert
assertFalse(result);
assertEquals(1, cash.count());
}
@Test
void testUpdate() {
- //Arrange
+ // Arrange
var cash = new Cash(5);
- //Act
+ // Act
cash.plus(6);
var result = cash.minus(3);
- //Assert
+ // Assert
assertTrue(result);
assertEquals(8, cash.count());
}
diff --git a/arrange-act-assert/src/test/java/com/iluwatar/arrangeactassert/CashAntiAAATest.java b/arrange-act-assert/src/test/java/com/iluwatar/arrangeactassert/CashAntiAAATest.java
index 142fd623abb8..5756822516b8 100644
--- a/arrange-act-assert/src/test/java/com/iluwatar/arrangeactassert/CashAntiAAATest.java
+++ b/arrange-act-assert/src/test/java/com/iluwatar/arrangeactassert/CashAntiAAATest.java
@@ -37,23 +37,22 @@
* single responsibility principle. If this test method failed after a small code change, it might
* take some digging to discover why.
*/
-
class CashAntiAAATest {
@Test
void testCash() {
- //initialize
+ // initialize
var cash = new Cash(3);
- //test plus
+ // test plus
cash.plus(4);
assertEquals(7, cash.count());
- //test minus
+ // test minus
cash = new Cash(8);
assertTrue(cash.minus(5));
assertEquals(3, cash.count());
assertFalse(cash.minus(6));
assertEquals(3, cash.count());
- //test update
+ // test update
cash.plus(5);
assertTrue(cash.minus(5));
assertEquals(3, cash.count());
diff --git a/async-method-invocation/README.md b/async-method-invocation/README.md
index 950b958610e5..519152e1268c 100644
--- a/async-method-invocation/README.md
+++ b/async-method-invocation/README.md
@@ -1,167 +1,171 @@
---
-title: Async Method Invocation
+title: "Async Method Invocation Pattern in Java: Elevate Performance with Asynchronous Programming"
+shortTitle: Async Method Invocation
+description: "Learn about the Async Method Invocation pattern in Java for asynchronous method calls, enhancing concurrency, scalability, and responsiveness in your applications. Explore real-world examples and code implementations."
category: Concurrency
language: en
tag:
- - Asynchronous
- - Reactive
- - Scalability
+ - Asynchronous
+ - Decoupling
+ - Reactive
+ - Scalability
+ - Thread management
---
-## Intent
-
-Asynchronous method invocation is a pattern where the calling thread
-is not blocked while waiting results of tasks. The pattern provides parallel
-processing of multiple independent tasks and retrieving the results via
-callbacks or waiting until everything is done.
-
## Also known as
* Asynchronous Procedure Call
-## Explanation
+## Intent of Async Method Invocation Design Pattern
+
+The Async Method Invocation pattern is designed to enhance concurrency by allowing methods to be called asynchronously. This pattern helps in executing parallel tasks, reducing wait times, and improving system throughput.
-Real world example
+## Detailed Explanation of Async Method Invocation Pattern with Real-World Examples
-> Launching space rockets is an exciting business. The mission command gives an order to launch and
-> after some undetermined time, the rocket either launches successfully or fails miserably.
+Real-world example
+
+> Asynchronous method invocation enables non-blocking operations, allowing multiple processes to run concurrently. This pattern is particularly useful in applications requiring high scalability and performance, such as web servers and microservices.
+>
+> In the context of space rockets, an analogous example of the Async Method Invocation pattern can be seen in the communication between the mission control center and the onboard systems of the rocket. When mission control sends a command to the rocket to adjust its trajectory or perform a system check, they do not wait idly for the rocket to complete the task and report back. Instead, mission control continues to monitor other aspects of the mission and manage different tasks. The rocket executes the command asynchronously and sends a status update or result back to mission control once the operation is complete. This allows mission control to efficiently manage multiple concurrent operations without being blocked by any single task, similar to how asynchronous method invocation works in software systems.
In plain words
-> Asynchronous method invocation starts task processing and returns immediately before the task is
-> ready. The results of the task processing are returned to the caller later.
+> Asynchronous method invocation starts task processing and returns immediately before the task is ready. The results of the task processing are returned to the caller later.
Wikipedia says
-> In multithreaded computer programming, asynchronous method invocation (AMI), also known as
-> asynchronous method calls or the asynchronous pattern is a design pattern in which the call site
-> is not blocked while waiting for the called code to finish. Instead, the calling thread is
-> notified when the reply arrives. Polling for a reply is an undesired option.
+> In multithreaded computer programming, asynchronous method invocation (AMI), also known as asynchronous method calls or the asynchronous pattern is a design pattern in which the call site is not blocked while waiting for the called code to finish. Instead, the calling thread is notified when the reply arrives. Polling for a reply is an undesired option.
+
+Sequence diagram
+
+
-**Programmatic Example**
+## Programmatic Example of Async Method Invocation Pattern in Java
+
+Consider a scenario where multiple tasks need to be executed simultaneously. Using the Async Method Invocation pattern, you can initiate these tasks without waiting for each to complete, thus optimizing resource usage and reducing latency.
In this example, we are launching space rockets and deploying lunar rovers.
-The application demonstrates the async method invocation pattern. The key parts of the pattern are
-`AsyncResult` which is an intermediate container for an asynchronously evaluated value,
-`AsyncCallback` which can be provided to be executed on task completion and `AsyncExecutor` that
-manages the execution of the async tasks.
+The application demonstrates the async method invocation pattern. The key parts of the pattern are`AsyncResult` which is an intermediate container for an asynchronously evaluated value, `AsyncCallback` which can be provided to be executed on task completion and `AsyncExecutor` that manages the execution of the async tasks.
```java
public interface AsyncResult {
- boolean isCompleted();
- T getValue() throws ExecutionException;
- void await() throws InterruptedException;
+ boolean isCompleted();
+
+ T getValue() throws ExecutionException;
+
+ void await() throws InterruptedException;
}
```
```java
public interface AsyncCallback {
void onComplete(T value);
+
void onError(Exception ex);
}
```
```java
public interface AsyncExecutor {
- AsyncResult startProcess(Callable task);
- AsyncResult startProcess(Callable task, AsyncCallback callback);
- T endProcess(AsyncResult asyncResult) throws ExecutionException, InterruptedException;
+ AsyncResult startProcess(Callable task);
+
+ AsyncResult startProcess(Callable task, AsyncCallback callback);
+
+ T endProcess(AsyncResult asyncResult) throws ExecutionException, InterruptedException;
}
```
-`ThreadAsyncExecutor` is an implementation of `AsyncExecutor`. Some of its key parts are highlighted
-next.
+`ThreadAsyncExecutor` is an implementation of `AsyncExecutor`. Some of its key parts are highlighted next.
```java
public class ThreadAsyncExecutor implements AsyncExecutor {
- @Override
- public AsyncResult startProcess(Callable task) {
- return startProcess(task, null);
- }
-
- @Override
- public AsyncResult startProcess(Callable task, AsyncCallback callback) {
- var result = new CompletableResult<>(callback);
- new Thread(
- () -> {
- try {
- result.setValue(task.call());
- } catch (Exception ex) {
- result.setException(ex);
- }
- },
- "executor-" + idx.incrementAndGet())
- .start();
- return result;
- }
-
- @Override
- public T endProcess(AsyncResult asyncResult)
- throws ExecutionException, InterruptedException {
- if (!asyncResult.isCompleted()) {
- asyncResult.await();
+ @Override
+ public AsyncResult startProcess(Callable task) {
+ return startProcess(task, null);
+ }
+
+ @Override
+ public AsyncResult startProcess(Callable task, AsyncCallback callback) {
+ var result = new CompletableResult<>(callback);
+ new Thread(
+ () -> {
+ try {
+ result.setValue(task.call());
+ } catch (Exception ex) {
+ result.setException(ex);
+ }
+ },
+ "executor-" + idx.incrementAndGet())
+ .start();
+ return result;
+ }
+
+ @Override
+ public T endProcess(AsyncResult asyncResult)
+ throws ExecutionException, InterruptedException {
+ if (!asyncResult.isCompleted()) {
+ asyncResult.await();
+ }
+ return asyncResult.getValue();
}
- return asyncResult.getValue();
- }
}
```
Then we are ready to launch some rockets to see how everything works together.
```java
-public static void main(String[] args) throws Exception {
- // construct a new executor that will run async tasks
- var executor = new ThreadAsyncExecutor();
-
- // start few async tasks with varying processing times, two last with callback handlers
- final var asyncResult1 = executor.startProcess(lazyval(10, 500));
- final var asyncResult2 = executor.startProcess(lazyval("test", 300));
- final var asyncResult3 = executor.startProcess(lazyval(50L, 700));
- final var asyncResult4 = executor.startProcess(lazyval(20, 400), callback("Deploying lunar rover"));
- final var asyncResult5 =
- executor.startProcess(lazyval("callback", 600), callback("Deploying lunar rover"));
-
- // emulate processing in the current thread while async tasks are running in their own threads
- Thread.sleep(350); // Oh boy, we are working hard here
- log("Mission command is sipping coffee");
-
- // wait for completion of the tasks
- final var result1 = executor.endProcess(asyncResult1);
- final var result2 = executor.endProcess(asyncResult2);
- final var result3 = executor.endProcess(asyncResult3);
- asyncResult4.await();
- asyncResult5.await();
-
- // log the results of the tasks, callbacks log immediately when complete
- log("Space rocket <" + result1 + "> launch complete");
- log("Space rocket <" + result2 + "> launch complete");
- log("Space rocket <" + result3 + "> launch complete");
+ public static void main(String[] args) throws Exception {
+ // construct a new executor that will run async tasks
+ var executor = new ThreadAsyncExecutor();
+
+ // start few async tasks with varying processing times, two last with callback handlers
+ final var asyncResult1 = executor.startProcess(lazyval(10, 500));
+ final var asyncResult2 = executor.startProcess(lazyval("test", 300));
+ final var asyncResult3 = executor.startProcess(lazyval(50L, 700));
+ final var asyncResult4 = executor.startProcess(lazyval(20, 400),
+ callback("Deploying lunar rover"));
+ final var asyncResult5 =
+ executor.startProcess(lazyval("callback", 600), callback("Deploying lunar rover"));
+
+ // emulate processing in the current thread while async tasks are running in their own threads
+ Thread.sleep(350); // Oh boy, we are working hard here
+ log("Mission command is sipping coffee");
+
+ // wait for completion of the tasks
+ final var result1 = executor.endProcess(asyncResult1);
+ final var result2 = executor.endProcess(asyncResult2);
+ final var result3 = executor.endProcess(asyncResult3);
+ asyncResult4.await();
+ asyncResult5.await();
+
+ // log the results of the tasks, callbacks log immediately when complete
+ log(String.format(ROCKET_LAUNCH_LOG_PATTERN, result1));
+ log(String.format(ROCKET_LAUNCH_LOG_PATTERN, result2));
+ log(String.format(ROCKET_LAUNCH_LOG_PATTERN, result3));
}
```
Here's the program console output.
-```java
-21:47:08.227 [executor-2] INFO com.iluwatar.async.method.invocation.App - Space rocket launched successfully
-21:47:08.269 [main] INFO com.iluwatar.async.method.invocation.App - Mission command is sipping coffee
-21:47:08.318 [executor-4] INFO com.iluwatar.async.method.invocation.App - Space rocket <20> launched successfully
-21:47:08.335 [executor-4] INFO com.iluwatar.async.method.invocation.App - Deploying lunar rover <20>
-21:47:08.414 [executor-1] INFO com.iluwatar.async.method.invocation.App - Space rocket <10> launched successfully
-21:47:08.519 [executor-5] INFO com.iluwatar.async.method.invocation.App - Space rocket launched successfully
-21:47:08.519 [executor-5] INFO com.iluwatar.async.method.invocation.App - Deploying lunar rover
-21:47:08.616 [executor-3] INFO com.iluwatar.async.method.invocation.App - Space rocket <50> launched successfully
-21:47:08.617 [main] INFO com.iluwatar.async.method.invocation.App - Space rocket <10> launch complete
-21:47:08.617 [main] INFO com.iluwatar.async.method.invocation.App - Space rocket launch complete
-21:47:08.618 [main] INFO com.iluwatar.async.method.invocation.App - Space rocket <50> launch complete
+```
+21:47:08.227[executor-2]INFO com.iluwatar.async.method.invocation.App-Space rocket launched successfully
+21:47:08.269[main]INFO com.iluwatar.async.method.invocation.App-Mission command is sipping coffee
+21:47:08.318[executor-4]INFO com.iluwatar.async.method.invocation.App-Space rocket<20>launched successfully
+21:47:08.335[executor-4]INFO com.iluwatar.async.method.invocation.App-Deploying lunar rover<20>
+21:47:08.414[executor-1]INFO com.iluwatar.async.method.invocation.App-Space rocket<10>launched successfully
+21:47:08.519[executor-5]INFO com.iluwatar.async.method.invocation.App-Space rocket launched successfully
+21:47:08.519[executor-5]INFO com.iluwatar.async.method.invocation.App-Deploying lunar rover
+21:47:08.616[executor-3]INFO com.iluwatar.async.method.invocation.App-Space rocket<50>launched successfully
+21:47:08.617[main]INFO com.iluwatar.async.method.invocation.App-Space rocket<10>launch complete
+21:47:08.617[main]INFO com.iluwatar.async.method.invocation.App-Space rocket launch complete
+21:47:08.618[main]INFO com.iluwatar.async.method.invocation.App-Space rocket<50>launch complete
```
-# Class diagram
-
-
+## When to Use the Async Method Invocation Pattern in Java
-## Applicability
+This pattern is ideal for applications needing to manage multiple parallel tasks efficiently. It is commonly used in scenarios such as handling background processes, improving user interface responsiveness, and managing asynchronous data processing.
Use the async method invocation pattern when
@@ -170,7 +174,9 @@ Use the async method invocation pattern when
* In GUI applications to prevent freezing or unresponsiveness during long-running tasks.
* In web applications for non-blocking IO operations.
-## Known Uses
+## Real-World Applications of Async Method Invocation Pattern in Java
+
+Many modern applications leverage the Async Method Invocation pattern, including web servers handling concurrent requests, microservices architectures, and systems requiring intensive background processing.
* Web servers handling HTTP requests asynchronously to improve throughput and reduce latency.
* Desktop and mobile applications using background threads to perform time-consuming operations without blocking the user interface.
@@ -180,7 +186,9 @@ Use the async method invocation pattern when
* [ExecutorService](http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html)
* [Task-based Asynchronous Pattern](https://msdn.microsoft.com/en-us/library/hh873175.aspx)
-## Consequences
+## Benefits and Trade-offs of Async Method Invocation Pattern
+
+While this pattern offers significant performance benefits, it also introduces complexity in error handling and resource management. Proper implementation is essential to avoid potential pitfalls such as race conditions and deadlocks.
Benefits:
@@ -194,13 +202,16 @@ Trade-offs:
* Resource Management: Requires careful management of threads or execution contexts, which can introduce overhead and potential resource exhaustion issues.
* Error Handling: Asynchronous operations can make error handling more complex, as exceptions may occur in different threads or at different times.
-Related Patterns:
+## Related Java Design Patterns
+
+The Async Method Invocation pattern often works well with other design patterns like the Command Pattern for encapsulating requests, the Observer Pattern for event handling, and the Promise Pattern for managing asynchronous results.
* [Command](https://java-design-patterns.com/patterns/command/): Asynchronous method invocation can be used to implement the Command pattern, where commands are executed asynchronously.
* [Observer](https://java-design-patterns.com/patterns/observer/): Asynchronous method invocation can be used to notify observers asynchronously when a subject's state changes.
* [Promise](https://java-design-patterns.com/patterns/promise/): The AsyncResult interface can be considered a form of Promise, representing a value that may not be available yet.
-## Credits
+## References and Credits
* [Design Patterns: Elements of Reusable Object-Oriented Software](https://amzn.to/3Ti1N4f)
+* [Effective Java](https://amzn.to/4cGk2Jz)
* [Java Concurrency in Practice](https://amzn.to/4ab97VU)
diff --git a/async-method-invocation/etc/async-method-invocation-sequence-diagram.png b/async-method-invocation/etc/async-method-invocation-sequence-diagram.png
new file mode 100644
index 000000000000..28420d783379
Binary files /dev/null and b/async-method-invocation/etc/async-method-invocation-sequence-diagram.png differ
diff --git a/async-method-invocation/pom.xml b/async-method-invocation/pom.xml
index 52a03369f47d..d9ddd918c8e9 100644
--- a/async-method-invocation/pom.xml
+++ b/async-method-invocation/pom.xml
@@ -34,6 +34,14 @@
async-method-invocation
+
+ org.slf4j
+ slf4j-api
+
+
+ ch.qos.logback
+ logback-classic
+ org.junit.jupiterjunit-jupiter-engine
diff --git a/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/App.java b/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/App.java
index 01fd8f1c681a..ec3beed3be4d 100644
--- a/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/App.java
+++ b/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/App.java
@@ -30,15 +30,15 @@
/**
* In this example, we are launching space rockets and deploying lunar rovers.
*
- *
The application demonstrates the async method invocation pattern. The key parts of the
- * pattern are AsyncResult which is an intermediate container for an asynchronously
- * evaluated value, AsyncCallback which can be provided to be executed on task
- * completion and AsyncExecutor that manages the execution of the async tasks.
+ *
The application demonstrates the async method invocation pattern. The key parts of the pattern
+ * are AsyncResult which is an intermediate container for an asynchronously evaluated
+ * value, AsyncCallback which can be provided to be executed on task completion and
+ * AsyncExecutor that manages the execution of the async tasks.
*
- *
The main method shows example flow of async invocations. The main thread starts multiple
- * tasks with variable durations and then continues its own work. When the main thread has done it's
- * job it collects the results of the async tasks. Two of the tasks are handled with callbacks,
- * meaning the callbacks are executed immediately when the tasks complete.
+ *
The main method shows example flow of async invocations. The main thread starts multiple tasks
+ * with variable durations and then continues its own work. When the main thread has done it's job
+ * it collects the results of the async tasks. Two of the tasks are handled with callbacks, meaning
+ * the callbacks are executed immediately when the tasks complete.
*
*
Noteworthy difference of thread usage between the async results and callbacks is that the
* async results are collected in the main thread but the callbacks are executed within the worker
@@ -62,10 +62,7 @@ public class App {
private static final String ROCKET_LAUNCH_LOG_PATTERN = "Space rocket <%s> launched successfully";
- /**
- * Program entry point.
- */
-
+ /** Program entry point. */
public static void main(String[] args) throws Exception {
// construct a new executor that will run async tasks
var executor = new ThreadAsyncExecutor();
@@ -74,8 +71,8 @@ public static void main(String[] args) throws Exception {
final var asyncResult1 = executor.startProcess(lazyval(10, 500));
final var asyncResult2 = executor.startProcess(lazyval("test", 300));
final var asyncResult3 = executor.startProcess(lazyval(50L, 700));
- final var asyncResult4 = executor.startProcess(lazyval(20, 400),
- callback("Deploying lunar rover"));
+ final var asyncResult4 =
+ executor.startProcess(lazyval(20, 400), callback("Deploying lunar rover"));
final var asyncResult5 =
executor.startProcess(lazyval("callback", 600), callback("Deploying lunar rover"));
@@ -99,7 +96,7 @@ public static void main(String[] args) throws Exception {
/**
* Creates a callable that lazily evaluates to given value with artificial delay.
*
- * @param value value to evaluate
+ * @param value value to evaluate
* @param delayMillis artificial delay in milliseconds
* @return new callable for lazy evaluation
*/
diff --git a/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/AsyncExecutor.java b/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/AsyncExecutor.java
index fcea6d07190d..3bae90830098 100644
--- a/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/AsyncExecutor.java
+++ b/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/AsyncExecutor.java
@@ -27,9 +27,7 @@
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutionException;
-/**
- * AsyncExecutor interface.
- */
+/** AsyncExecutor interface. */
public interface AsyncExecutor {
/**
@@ -44,7 +42,7 @@ public interface AsyncExecutor {
* Starts processing of an async task. Returns immediately with async result. Executes callback
* when the task is completed.
*
- * @param task task to be executed asynchronously
+ * @param task task to be executed asynchronously
* @param callback callback to be executed on task completion
* @return async result for the task
*/
@@ -56,7 +54,7 @@ public interface AsyncExecutor {
*
* @param asyncResult async result of a task
* @return evaluated value of the completed task
- * @throws ExecutionException if execution has failed, containing the root cause
+ * @throws ExecutionException if execution has failed, containing the root cause
* @throws InterruptedException if the execution is interrupted
*/
T endProcess(AsyncResult asyncResult) throws ExecutionException, InterruptedException;
diff --git a/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/AsyncResult.java b/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/AsyncResult.java
index d71cf0defcd1..3eebdc4e773d 100644
--- a/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/AsyncResult.java
+++ b/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/AsyncResult.java
@@ -44,7 +44,7 @@ public interface AsyncResult {
* Gets the value of completed async task.
*
* @return evaluated value or throws ExecutionException if execution has failed
- * @throws ExecutionException if execution has failed, containing the root cause
+ * @throws ExecutionException if execution has failed, containing the root cause
* @throws IllegalStateException if execution is not completed
*/
T getValue() throws ExecutionException;
diff --git a/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/ThreadAsyncExecutor.java b/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/ThreadAsyncExecutor.java
index f4a50e0d6c30..a1261f34184c 100644
--- a/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/ThreadAsyncExecutor.java
+++ b/async-method-invocation/src/main/java/com/iluwatar/async/method/invocation/ThreadAsyncExecutor.java
@@ -24,19 +24,14 @@
*/
package com.iluwatar.async.method.invocation;
-import java.util.Optional;
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicInteger;
-/**
- * Implementation of async executor that creates a new thread for every task.
- */
+/** Implementation of async executor that creates a new thread for every task. */
public class ThreadAsyncExecutor implements AsyncExecutor {
- /**
- * Index for thread naming.
- */
+ /** Index for thread naming. */
private final AtomicInteger idx = new AtomicInteger(0);
@Override
@@ -47,19 +42,22 @@ public AsyncResult startProcess(Callable task) {
@Override
public AsyncResult startProcess(Callable task, AsyncCallback callback) {
var result = new CompletableResult<>(callback);
- new Thread(() -> {
- try {
- result.setValue(task.call());
- } catch (Exception ex) {
- result.setException(ex);
- }
- }, "executor-" + idx.incrementAndGet()).start();
+ new Thread(
+ () -> {
+ try {
+ result.setValue(task.call());
+ } catch (Exception ex) {
+ result.setException(ex);
+ }
+ },
+ "executor-" + idx.incrementAndGet())
+ .start();
return result;
}
@Override
- public T endProcess(AsyncResult asyncResult) throws ExecutionException,
- InterruptedException {
+ public T endProcess(AsyncResult asyncResult)
+ throws ExecutionException, InterruptedException {
if (!asyncResult.isCompleted()) {
asyncResult.await();
}
diff --git a/async-method-invocation/src/test/java/com/iluwatar/async/method/invocation/AppTest.java b/async-method-invocation/src/test/java/com/iluwatar/async/method/invocation/AppTest.java
index f31c5549bdd1..d58a3f6b5c30 100644
--- a/async-method-invocation/src/test/java/com/iluwatar/async/method/invocation/AppTest.java
+++ b/async-method-invocation/src/test/java/com/iluwatar/async/method/invocation/AppTest.java
@@ -24,26 +24,22 @@
*/
package com.iluwatar.async.method.invocation;
-import org.junit.jupiter.api.Test;
-
import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
-/**
- * Application test
- */
+import org.junit.jupiter.api.Test;
+
+/** Application test */
class AppTest {
/**
* Issue: Add at least one assertion to this test case.
*
- * Solution: Inserted assertion to check whether the execution of the main method in {@link App}
- * throws an exception.
+ *
