docs: update visitor

Author: iluwatar

visitor/README.md

@@ -3,36 +3,38 @@ title: Visitor
 category: Behavioral
 language: en
 tag:
- - Gang of Four
+    - Decoupling
+    - Extensibility
+    - Gang of Four
+    - Object composition
+    - Polymorphism
 ---
 
 ## Intent
 
-Represent an operation to be performed on the elements of an object structure. Visitor lets you 
-define a new operation without changing the classes of the elements on which it operates.
+To represent an operation to be performed on the elements of an object structure. Visitor lets you define a new operation without changing the classes of the elements on which it operates.
 
 ## Explanation
 
 Real-world example
 
-> Consider a tree structure with army units. Commander has two sergeants under it and each sergeant 
-> has three soldiers under them. Given that the hierarchy implements the visitor pattern, we can 
-> easily create new objects that interact with the commander, sergeants, soldiers, or all of them. 
+> An analogous real-world example of the Visitor design pattern can be seen in a museum tour guide system. Imagine a museum where visitors can take guided tours to learn about different types of exhibits, such as paintings, sculptures, and historical artifacts. Each exhibit type requires a different explanation, which is provided by specialized tour guides.
+> 
+> In this scenario, the exhibits are like the elements in the Visitor pattern, and the tour guides are like the visitors. The museum structure remains unchanged, but new guides with new types of tours (operations) can be added without modifying the exhibits themselves. Each guide (visitor) implements a specific way to interact with the exhibits, providing detailed explanations according to their specialization, thereby separating the operations from the objects they operate on. 
 
 In plain words
 
 > Visitor pattern defines operations that can be performed on the nodes of the data structure. 
 
 Wikipedia says
 
-> In object-oriented programming and software engineering, the visitor design pattern is a way of 
-> separating an algorithm from an object structure on which it operates. A practical result of this 
-> separation is the ability to add new operations to existing object structures without modifying 
-> the structures.
+> In object-oriented programming and software engineering, the visitor design pattern is a way of separating an algorithm from an object structure on which it operates. A practical result of this separation is the ability to add new operations to existing object structures without modifying the structures.
 
 **Programmatic Example**
 
-Given the army unit example from above, we first have the Unit and UnitVisitor base types.
+Consider a tree structure with army units. Commander has two sergeants under it and each sergeant has three soldiers under them. Given that the hierarchy implements the visitor pattern, we can easily create new objects that interact with the commander, sergeants, soldiers, or all of them.
+
+Given the army unit example from above, we first have the `Unit` and `UnitVisitor` base types.
 
 ```java
 public abstract class Unit {
@@ -58,7 +60,7 @@ public interface UnitVisitor {
 }
 ```
 
-Then we have the concrete units.
+Then we have the concrete units `Commander`, `Sergeant`, and `Soldier`.
 
 ```java
 public class Commander extends Unit {
@@ -116,7 +118,7 @@ public class Soldier extends Unit {
 }
 ```
 
-Here are then some concrete visitors.
+Here are the concrete visitors `CommanderVisitor`, `SergeantVisitor`, and `SoldierVisitor`.
 
 ```java
 @Slf4j
@@ -201,31 +203,55 @@ Good to see you commander
 
 ## Class diagram
 
-![alt text](./etc/visitor_1.png "Visitor")
+![Visitor](./etc/visitor_1.png "Visitor")
 
 ## Applicability
 
 Use the Visitor pattern when
 
-* An object structure contains many classes of objects with differing interfaces, and you want to perform operations on these objects that depend on their concrete classes.
-* Many distinct and unrelated operations need to be performed on objects in an object structure, and you want to avoid "polluting" their classes with these operations. Visitor lets you keep related operations together by defining them in one class. When the object structure is shared by many applications, use Visitor to put operations in just those applications that need them.
-* The classes defining the object structure rarely change, but you often want to define new operations over the structure. Changing the object structure classes requires redefining the interface to all visitors, which is potentially costly. If the object structure classes change often, then it's probably better to define the operations in those classes.
+* Use the Visitor pattern when you need to perform an operation on a group of similar kinds of objects, and you want to avoid polluting their classes with this operation.
+* Use it when a class structure is stable, but you need to perform new operations on the structure without changing it.
+* It's beneficial when the set of classes are fixed and only the operations need to be extended.
 
 ## Tutorials
 
-* [Refactoring Guru](https://refactoring.guru/design-patterns/visitor)
-* [Dzone](https://dzone.com/articles/design-patterns-visitor)
-* [Sourcemaking](https://sourcemaking.com/design_patterns/visitor)
+* [Visitor - Refactoring Guru](https://refactoring.guru/design-patterns/visitor)
+* [Visitor Pattern Tutorial with Java Examples - DZone](https://dzone.com/articles/design-patterns-visitor)
+* [Visitor Design Pattern - Sourcemaking](https://sourcemaking.com/design_patterns/visitor)
 
 ## Known uses
 
+* Compiler design, where the Visitor pattern can be used for operations like pretty printing, semantic checks, etc.
+* Abstract Syntax Tree (AST) processing.
+* Document structure processing (e.g., HTML, XML).
 * [Apache Wicket](https://github.com/apache/wicket) component tree, see [MarkupContainer](https://github.com/apache/wicket/blob/b60ec64d0b50a611a9549809c9ab216f0ffa3ae3/wicket-core/src/main/java/org/apache/wicket/MarkupContainer.java)
 * [javax.lang.model.element.AnnotationValue](http://docs.oracle.com/javase/8/docs/api/javax/lang/model/element/AnnotationValue.html) and [AnnotationValueVisitor](http://docs.oracle.com/javase/8/docs/api/javax/lang/model/element/AnnotationValueVisitor.html)
 * [javax.lang.model.element.Element](http://docs.oracle.com/javase/8/docs/api/javax/lang/model/element/Element.html) and [Element Visitor](http://docs.oracle.com/javase/8/docs/api/javax/lang/model/element/ElementVisitor.html)
 * [java.nio.file.FileVisitor](http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileVisitor.html)
 
+## Consequences
+
+Benefits:
+
+* Simplifies adding new operations: Adding a new operation is straightforward because you can add a new visitor without changing existing code.
+* Single Responsibility Principle: The Visitor pattern allows you to move related behavior into one class.
+* Open/Closed Principle: Elements can stay closed to modification while visitors are open to extension.
+
+Trade-offs:
+
+* Adding new element classes: If you need to add new types of elements, you'll need to change both the visitor interface and all of its concrete visitors.
+* Circular dependencies: In complex systems, this pattern can introduce circular dependencies between visitor and element classes.
+* Breaking encapsulation: Visitor pattern requires that the element classes expose enough details to allow the visitor to do its job, potentially breaking encapsulation.
+
+## Related Patterns
+
+* [Composite](https://java-design-patterns.com/patterns/composite/): The Visitor pattern is often used in conjunction with the Composite pattern, where the visitor can perform operations over a composite structure.
+* [Interpreter](https://java-design-patterns.com/patterns/interpreter/): Visitors can be used to implement the non-terminal expressions in the Interpreter pattern.
+* [Strategy](https://java-design-patterns.com/patterns/strategy/): Visitor can be considered a way of making strategies work on objects that they were not designed to operate on.
+
 ## 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)
-* [Refactoring to Patterns](https://www.amazon.com/gp/product/0321213351/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=0321213351&linkCode=as2&tag=javadesignpat-20&linkId=2a76fcb387234bc71b1c61150b3cc3a7)
+* [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)
+* [Refactoring to Patterns](https://amzn.to/3VOO4F5)

visitor/src/test/java/com/iluwatar/visitor/VisitorTest.java

@@ -123,7 +123,7 @@ void testVisitSoldier() {
     }
   }
 
-  private class InMemoryAppender extends AppenderBase<ILoggingEvent> {
+  private static class InMemoryAppender extends AppenderBase<ILoggingEvent> {
     private final List<ILoggingEvent> log = new LinkedList<>();
 
     public InMemoryAppender() {