Add explanation for factory kit

factory-kit/README.md

@@ -10,19 +10,115 @@ tags:
 ---
 
 ## Intent
+
 Define a factory of immutable content with separated builder and factory interfaces.
 
+## Explanation
+
+Real-world example
+
+> Imagine a magical weapon factory that can create any type of weapon wished for. When the factory
+> is unboxed, the master recites the weapon types needed to prepare it. After that, any of those
+> weapon types can be summoned in an instant. 
+
+In plain words
+
+> Factory kit is a configurable object builder.
+
+**Programmatic Example**
+
+Let's first define the simple `Weapon` hierarchy.
+
+```java
+public interface Weapon {
+}
+
+public enum WeaponType {
+    SWORD,
+    AXE,
+    BOW,
+    SPEAR
+}
+
+public class Sword implements Weapon {
+    @Override
+    public String toString() {
+        return "Sword";
+    }
+}
+
+// Axe, Bow, and Spear are defined similarly
+```
+
+Next, we define a functional interface that allows adding a builder with a name to the factory.
+
+```java
+public interface Builder {
+  void add(WeaponType name, Supplier<Weapon> supplier);
+}
+```
+
+The meat of the example is the `WeaponFactory` interface that effectively implements the factory
+kit pattern. The method `#factory` is used to configure the factory with the classes it needs to
+be able to construct. The method `#create` is then used to create object instances.
+
+```java
+public interface WeaponFactory {
+
+  static WeaponFactory factory(Consumer<Builder> consumer) {
+      var map = new HashMap<WeaponType, Supplier<Weapon>>();
+      consumer.accept(map::put);
+      return name -> map.get(name).get();
+  }
+    
+  Weapon create(WeaponType name);
+}
+```
+
+Now, we can show how `WeaponFactory` can be used.
+
+```java
+var factory = WeaponFactory.factory(builder -> {
+  builder.add(WeaponType.SWORD, Sword::new);
+  builder.add(WeaponType.AXE, Axe::new);
+  builder.add(WeaponType.SPEAR, Spear::new);
+  builder.add(WeaponType.BOW, Bow::new);
+});
+var list = new ArrayList<Weapon>();
+list.add(factory.create(WeaponType.AXE));
+list.add(factory.create(WeaponType.SPEAR));
+list.add(factory.create(WeaponType.SWORD));
+list.add(factory.create(WeaponType.BOW));
+list.stream().forEach(weapon -> LOGGER.info("{}", weapon.toString()));
+```
+
+Here is the console output when the example is run.
+
+```
+21:15:49.709 [main] INFO com.iluwatar.factorykit.App - Axe
+21:15:49.713 [main] INFO com.iluwatar.factorykit.App - Spear
+21:15:49.713 [main] INFO com.iluwatar.factorykit.App - Sword
+21:15:49.713 [main] INFO com.iluwatar.factorykit.App - Bow
+```
+
 ## Class diagram
+
 ![alt text](./etc/factory-kit.png "Factory Kit")
 
 ## Applicability
+
 Use the Factory Kit pattern when
 
-* a class can't anticipate the class of objects it must create
-* you just want a new instance of a custom builder instead of the global one
-* you explicitly want to define types of objects, that factory can build
-* you want a separated builder and creator interface
+* The factory class can't anticipate the types of objects it must create
+* A new instance of a custom builder is needed instead of a global one
+* The types of objects that the factory can build need to be defined outside the class
+* The builder and creator interfaces need to be separated
+
+## Related patterns
+
+* [Builder](https://java-design-patterns.com/patterns/builder/)
+* [Factory](https://java-design-patterns.com/patterns/factory/)
 
 ## Credits
 
-* [Design Pattern Reloaded by Remi Forax: ](https://www.youtube.com/watch?v=-k2X7guaArU)
+* [Design Pattern Reloaded by Remi Forax](https://www.youtube.com/watch?v=-k2X7guaArU)

factory-kit/src/main/java/com/iluwatar/factorykit/App.java

@@ -23,14 +23,16 @@
 
 package com.iluwatar.factorykit;
 
+import java.util.ArrayList;
+
 import lombok.extern.slf4j.Slf4j;
 
 /**
- * Factory-kit is a creational pattern which defines a factory of immutable content with separated
+ * Factory kit is a creational pattern that defines a factory of immutable content with separated
  * builder and factory interfaces to deal with the problem of creating one of the objects specified
- * directly in the factory-kit instance.
+ * directly in the factory kit instance.
  *
- * <p>In the given example {@link WeaponFactory} represents the factory-kit, that contains four
+ * <p>In the given example {@link WeaponFactory} represents the factory kit, that contains four
  * {@link Builder}s for creating new objects of the classes implementing {@link Weapon} interface.
  *
  * <p>Each of them can be called with {@link WeaponFactory#create(WeaponType)} method, with
@@ -52,7 +54,11 @@ public class App {
       builder.add(WeaponType.SPEAR, Spear::new);
       builder.add(WeaponType.BOW, Bow::new);
     });
-    var axe = factory.create(WeaponType.AXE);
-    LOGGER.info(axe.toString());
+    var list = new ArrayList<Weapon>();
+    list.add(factory.create(WeaponType.AXE));
+    list.add(factory.create(WeaponType.SPEAR));
+    list.add(factory.create(WeaponType.SWORD));
+    list.add(factory.create(WeaponType.BOW));
+    list.stream().forEach(weapon -> LOGGER.info("{}", weapon.toString()));
   }
 }

value-object/README.md

@@ -10,80 +10,19 @@ tags:
 ---
 
 ## Intent
-
 Provide objects which follow value semantics rather than reference semantics.
-This means value objects' equality is not based on identity. Two value objects are
+This means value objects' equality are not based on identity. Two value objects are
 equal when they have the same value, not necessarily being the same object.
 
-## Explanation
-
-Real-world example
-
-> There is a class for hero statistics in a role-playing game. The statistics contain attributes
-> such as strength, intelligence, and luck. The statistics of different heroes should be equal
-> when all the attributes are equal.
-
-In plain words
-
-> Value objects are equal when their attributes have the same value
-
-Wikipedia says
-
-> In computer science, a value object is a small object that represents a simple entity whose 
-> equality is not based on identity: i.e. two value objects are equal when they have the same 
-> value, not necessarily being the same object.
-
-**Programmatic Example**
-
-Here is the `HeroStat` class that is the value object. Notice the use of 
-[Lombok's `@Value`](https://projectlombok.org/features/Value) annotation.
-
-```java
-@Value(staticConstructor = "valueOf")
-class HeroStat {
-
-    int strength;
-    int intelligence;
-    int luck;
-}
-```
-
-The example creates three different `HeroStat`s and compares their equality.
-
-```java
-var statA = HeroStat.valueOf(10, 5, 0);
-var statB = HeroStat.valueOf(10, 5, 0);
-var statC = HeroStat.valueOf(5, 1, 8);
-
-LOGGER.info(statA.toString());
-LOGGER.info(statB.toString());
-LOGGER.info(statC.toString());
-
-LOGGER.info("Is statA and statB equal : {}", statA.equals(statB));
-LOGGER.info("Is statA and statC equal : {}", statA.equals(statC));
-```
-
-Here's the console output.
-
-```
-20:11:12.199 [main] INFO com.iluwatar.value.object.App - HeroStat(strength=10, intelligence=5, luck=0)
-20:11:12.202 [main] INFO com.iluwatar.value.object.App - HeroStat(strength=10, intelligence=5, luck=0)
-20:11:12.202 [main] INFO com.iluwatar.value.object.App - HeroStat(strength=5, intelligence=1, luck=8)
-20:11:12.202 [main] INFO com.iluwatar.value.object.App - Is statA and statB equal : true
-20:11:12.203 [main] INFO com.iluwatar.value.object.App - Is statA and statC equal : false
-```
-
 ## Class diagram
-
 ![alt text](./etc/value-object.png "Value Object")
 
 ## Applicability
-
 Use the Value Object when
 
-* The object's equality needs to be based on the object's value
+* You need to measure the objects' equality based on the objects' value
 
-## Known uses
+## Real world examples
 
 * [java.util.Optional](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html)
 * [java.time.LocalDate](https://docs.oracle.com/javase/8/docs/api/java/time/LocalDate.html)
@@ -92,7 +31,6 @@ Use the Value Object when
 ## Credits
 
 * [Patterns of Enterprise Application Architecture](http://www.martinfowler.com/books/eaa.html)
-* [ValueObject](https://martinfowler.com/bliki/ValueObject.html)
 * [VALJOs - Value Java Objects : Stephen Colebourne's blog](http://blog.joda.org/2014/03/valjos-value-java-objects.html)
 * [Value Object : Wikipedia](https://en.wikipedia.org/wiki/Value_object)
 * [J2EE Design Patterns](https://www.amazon.com/gp/product/0596004273/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=0596004273&linkCode=as2&tag=javadesignpat-20&linkId=f27d2644fbe5026ea448791a8ad09c94)

value-object/src/main/java/com/iluwatar/value/object/App.java

@@ -43,7 +43,7 @@ import lombok.extern.slf4j.Slf4j;
 public class App {
 
   /**
-   * This example creates three HeroStats (value objects) and checks equality between those.
+   * This practice creates three HeroStats(Value object) and checks equality between those.
    */
   public static void main(String[] args) {
     var statA = HeroStat.valueOf(10, 5, 0);
@@ -51,8 +51,6 @@ public class App {
     var statC = HeroStat.valueOf(5, 1, 8);
 
     LOGGER.info(statA.toString());
-    LOGGER.info(statB.toString());
-    LOGGER.info(statC.toString());
 
     LOGGER.info("Is statA and statB equal : {}", statA.equals(statB));
     LOGGER.info("Is statA and statC equal : {}", statA.equals(statC));

value-object/src/main/java/com/iluwatar/value/object/HeroStat.java

@@ -23,7 +23,10 @@
 
 package com.iluwatar.value.object;
 
-import lombok.Value;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import lombok.ToString;
 
 /**
  * HeroStat is a value object.
@@ -32,10 +35,23 @@ import lombok.Value;
  *     http://docs.oracle.com/javase/8/docs/api/java/lang/doc-files/ValueBased.html
  *     </a>
  */
-@Value(staticConstructor = "valueOf")
-class HeroStat {
+@Getter
+@ToString
+@EqualsAndHashCode
+@RequiredArgsConstructor
+public class HeroStat {
+
+  // Stats for a hero
+
+  private final int strength;
+  private final int intelligence;
+  private final int luck;
+
+  // Static factory method to create new instances.
+  public static HeroStat valueOf(int strength, int intelligence, int luck) {
+    return new HeroStat(strength, intelligence, luck);
+  }
+
+  // The clone() method should not be public. Just don't override it.
 
-  int strength;
-  int intelligence;
-  int luck;
 }