#590 Add explanation for Facade pattern

facade/README.md

@@ -15,7 +15,188 @@ tags:
 Provide a unified interface to a set of interfaces in a subsystem.
 Facade defines a higher-level interface that makes the subsystem easier to use.
 
-![alt text](./etc/facade_1.png "Facade")
+## Explanation
+
+Real world example
+
+> How does a goldmine work? "Well, the miners go down there and dig gold!" you say. That is what you believe because you are using a simple interface that goldmine provides on the outside, internally it has to do a lot of stuff to make it happen. This simple interface to the complex subsystem is a facade.
+
+In plain words
+
+> Facade pattern provides a simplified interface to a complex subsystem.
+
+Wikipedia says
+
+> A facade is an object that provides a simplified interface to a larger body of code, such as a class library.
+
+**Programmatic Example**
+
+Taking our goldmine example from above. Here we have the dwarven mine worker hierarchy
+
+```
+public abstract class DwarvenMineWorker {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(DwarvenMineWorker.class);
+
+  public void goToSleep() {
+    LOGGER.info("{} goes to sleep.", name());
+  }
+
+  public void wakeUp() {
+    LOGGER.info("{} wakes up.", name());
+  }
+
+  public void goHome() {
+    LOGGER.info("{} goes home.", name());
+  }
+
+  public void goToMine() {
+    LOGGER.info("{} goes to the mine.", name());
+  }
+
+  private void action(Action action) {
+    switch (action) {
+      case GO_TO_SLEEP:
+        goToSleep();
+        break;
+      case WAKE_UP:
+        wakeUp();
+        break;
+      case GO_HOME:
+        goHome();
+        break;
+      case GO_TO_MINE:
+        goToMine();
+        break;
+      case WORK:
+        work();
+        break;
+      default:
+        LOGGER.info("Undefined action");
+        break;
+    }
+  }
+
+  public void action(Action... actions) {
+    for (Action action : actions) {
+      action(action);
+    }
+  }
+
+  public abstract void work();
+
+  public abstract String name();
+
+  static enum Action {
+    GO_TO_SLEEP, WAKE_UP, GO_HOME, GO_TO_MINE, WORK
+  }
+}
+
+public class DwarvenTunnelDigger extends DwarvenMineWorker {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(DwarvenTunnelDigger.class);
+
+  @Override
+  public void work() {
+    LOGGER.info("{} creates another promising tunnel.", name());
+  }
+
+  @Override
+  public String name() {
+    return "Dwarven tunnel digger";
+  }
+}
+
+public class DwarvenGoldDigger extends DwarvenMineWorker {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(DwarvenGoldDigger.class);
+
+  @Override
+  public void work() {
+    LOGGER.info("{} digs for gold.", name());
+  }
+
+  @Override
+  public String name() {
+    return "Dwarf gold digger";
+  }
+}
+
+public class DwarvenCartOperator extends DwarvenMineWorker {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(DwarvenCartOperator.class);
+
+  @Override
+  public void work() {
+    LOGGER.info("{} moves gold chunks out of the mine.", name());
+  }
+
+  @Override
+  public String name() {
+    return "Dwarf cart operator";
+  }
+}
+
+```
+
+To operate all these goldmine workers we have the facade
+
+```
+public class DwarvenGoldmineFacade {
+
+  private final List<DwarvenMineWorker> workers;
+
+  public DwarvenGoldmineFacade() {
+    workers = new ArrayList<>();
+    workers.add(new DwarvenGoldDigger());
+    workers.add(new DwarvenCartOperator());
+    workers.add(new DwarvenTunnelDigger());
+  }
+
+  public void startNewDay() {
+    makeActions(workers, DwarvenMineWorker.Action.WAKE_UP, DwarvenMineWorker.Action.GO_TO_MINE);
+  }
+
+  public void digOutGold() {
+    makeActions(workers, DwarvenMineWorker.Action.WORK);
+  }
+
+  public void endDay() {
+    makeActions(workers, DwarvenMineWorker.Action.GO_HOME, DwarvenMineWorker.Action.GO_TO_SLEEP);
+  }
+
+  private static void makeActions(Collection<DwarvenMineWorker> workers,
+      DwarvenMineWorker.Action... actions) {
+    for (DwarvenMineWorker worker : workers) {
+      worker.action(actions);
+    }
+  }
+}
+```
+
+Now to use the facade
+
+```
+DwarvenGoldmineFacade facade = new DwarvenGoldmineFacade();
+facade.startNewDay();
+// Dwarf gold digger wakes up.
+// Dwarf gold digger goes to the mine.
+// Dwarf cart operator wakes up.
+// Dwarf cart operator goes to the mine.
+// Dwarven tunnel digger wakes up.
+// Dwarven tunnel digger goes to the mine.
+facade.digOutGold();
+// Dwarf gold digger digs for gold.
+// Dwarf cart operator moves gold chunks out of the mine.
+// Dwarven tunnel digger creates another promising tunnel.
+facade.endDay();
+// Dwarf gold digger goes home.
+// Dwarf gold digger goes to sleep.
+// Dwarf cart operator goes home.
+// Dwarf cart operator goes to sleep.
+// Dwarven tunnel digger goes home.
+// Dwarven tunnel digger goes to sleep.
+```
 
 ## Applicability
 Use the Facade pattern when

facade/etc/facade.ucls

@@ -1,88 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<class-diagram version="1.1.8" icons="true" automaticImage="PNG" always-add-relationships="false" generalizations="true" 
-  realizations="true" associations="true" dependencies="false" nesting-relationships="true">  
-  <class id="1" language="java" name="com.iluwatar.facade.DwarvenGoldmineFacade" project="facade" 
-    file="/facade/src/main/java/com/iluwatar/facade/DwarvenGoldmineFacade.java" binary="false" corner="BOTTOM_RIGHT">    
-    <position height="160" width="376" x="50" y="263"/>    
-    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
-      sort-features="false" accessors="true" visibility="true">      
-      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
-      <operations public="true" package="true" protected="true" private="true" static="true"/>    
-    </display>  
-  </class>  
-  <class id="2" language="java" name="com.iluwatar.facade.DwarvenMineWorker" project="facade" 
-    file="/facade/src/main/java/com/iluwatar/facade/DwarvenMineWorker.java" binary="false" corner="BOTTOM_RIGHT">    
-    <position height="231" width="171" x="50" y="463"/>    
-    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
-      sort-features="false" accessors="true" visibility="true">      
-      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
-      <operations public="true" package="true" protected="true" private="true" static="true"/>    
-    </display>  
-  </class>  
-  <class id="3" language="java" name="com.iluwatar.facade.DwarvenCartOperator" project="facade" 
-    file="/facade/src/main/java/com/iluwatar/facade/DwarvenCartOperator.java" binary="false" corner="BOTTOM_RIGHT">    
-    <position height="124" width="181" x="-272" y="734"/>    
-    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
-      sort-features="false" accessors="true" visibility="true">      
-      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
-      <operations public="true" package="true" protected="true" private="true" static="true"/>    
-    </display>  
-  </class>  
-  <class id="4" language="java" name="com.iluwatar.facade.DwarvenGoldDigger" project="facade" 
-    file="/facade/src/main/java/com/iluwatar/facade/DwarvenGoldDigger.java" binary="false" corner="BOTTOM_RIGHT">    
-    <position height="124" width="169" x="-51" y="734"/>    
-    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
-      sort-features="false" accessors="true" visibility="true">      
-      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
-      <operations public="true" package="true" protected="true" private="true" static="true"/>    
-    </display>  
-  </class>  
-  <enumeration id="5" language="java" name="com.iluwatar.facade.DwarvenMineWorker.Action" project="facade" 
-    file="/facade/src/main/java/com/iluwatar/facade/DwarvenMineWorker.java" binary="false" corner="BOTTOM_RIGHT">    
-    <position height="178" width="164" x="158" y="734"/>    
-    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
-      sort-features="false" accessors="true" visibility="true">      
-      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
-      <operations public="true" package="true" protected="true" private="true" static="true"/>    
-    </display>  
-  </enumeration>  
-  <class id="6" language="java" name="com.iluwatar.facade.DwarvenTunnelDigger" project="facade" 
-    file="/facade/src/main/java/com/iluwatar/facade/DwarvenTunnelDigger.java" binary="false" corner="BOTTOM_RIGHT">    
-    <position height="124" width="184" x="362" y="734"/>    
-    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
-      sort-features="false" accessors="true" visibility="true">      
-      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
-      <operations public="true" package="true" protected="true" private="true" static="true"/>    
-    </display>  
-  </class>  
-  <generalization id="7">    
-    <end type="SOURCE" refId="6"/>    
-    <end type="TARGET" refId="2"/>  
-  </generalization>  
-  <generalization id="8">    
-    <end type="SOURCE" refId="4"/>    
-    <end type="TARGET" refId="2"/>  
-  </generalization>  
-  <generalization id="9">    
-    <end type="SOURCE" refId="3"/>    
-    <end type="TARGET" refId="2"/>  
-  </generalization>  
-  <association id="10">    
-    <end type="SOURCE" refId="1" navigable="false">      
-      <attribute id="11" name="workers"/>      
-      <multiplicity id="12" minimum="0" maximum="2147483647"/>    
-    </end>    
-    <end type="TARGET" refId="2" navigable="true"/>    
-    <display labels="true" multiplicity="true"/>  
-  </association>  
-  <nesting id="13">    
-    <end type="SOURCE" refId="2"/>    
-    <end type="TARGET" refId="5"/>  
-  </nesting>  
-  <classifier-display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
-    sort-features="false" accessors="true" visibility="true">    
-    <attributes public="true" package="true" protected="true" private="true" static="true"/>    
-    <operations public="true" package="true" protected="true" private="true" static="true"/>  
-  </classifier-display>  
-  <association-display labels="true" multiplicity="true"/>
-</class-diagram>

facade/etc/facade.urm.puml

@@ -1,60 +0,0 @@
-@startuml
-package com.iluwatar.facade {
-  class App {
-    + App()
-    + main(args : String[]) {static}
-  }
-  class DwarvenCartOperator {
-    - LOGGER : Logger {static}
-    + DwarvenCartOperator()
-    + name() : String
-    + work()
-  }
-  class DwarvenGoldDigger {
-    - LOGGER : Logger {static}
-    + DwarvenGoldDigger()
-    + name() : String
-    + work()
-  }
-  class DwarvenGoldmineFacade {
-    - workers : List<DwarvenMineWorker>
-    + DwarvenGoldmineFacade()
-    + digOutGold()
-    + endDay()
-    - makeActions(workers : Collection<DwarvenMineWorker>, actions : Action[]) {static}
-    + startNewDay()
-  }
-  abstract class DwarvenMineWorker {
-    - LOGGER : Logger {static}
-    + DwarvenMineWorker()
-    - action(action : Action)
-    + action(actions : Action[])
-    + goHome()
-    + goToMine()
-    + goToSleep()
-    + name() : String {abstract}
-    + wakeUp()
-    + work() {abstract}
-  }
-  ~enum Action {
-    + GO_HOME {static}
-    + GO_TO_MINE {static}
-    + GO_TO_SLEEP {static}
-    + WAKE_UP {static}
-    + WORK {static}
-    + valueOf(name : String) : Action {static}
-    + values() : Action[] {static}
-  }
-  class DwarvenTunnelDigger {
-    - LOGGER : Logger {static}
-    + DwarvenTunnelDigger()
-    + name() : String
-    + work()
-  }
-}
-DwarvenGoldmineFacade -->  "-workers" DwarvenMineWorker
-Action ..+ DwarvenMineWorker
-DwarvenCartOperator --|> DwarvenMineWorker 
-DwarvenGoldDigger --|> DwarvenMineWorker 
-DwarvenTunnelDigger --|> DwarvenMineWorker 
-@enduml

pom.xml

@@ -470,6 +470,7 @@
                         <param>bridge</param>
                         <param>composite</param>
                         <param>decorator</param>
+                        <param>facade</param>
                     </skipForProjects>
                 </configuration>
             </plugin>