#590 add explanation for Observer

observer/README.md

@@ -13,9 +13,149 @@ tags:
 Dependents, Publish-Subscribe
 
 ## Intent
-Define a one-to-many dependency between objects so that when one
-object changes state, all its dependents are notified and updated
-automatically.
+Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified 
+and updated automatically.
+
+## Explanation
+
+Real world example
+
+> In a land far away lives the races of hobbits and orcs. Both of them are mostly outdoors so they closely follow the changes in weather. One could say that they are constantly observing the weather.        
+
+In plain words
+
+> Register as an observer to receive state changes in the object.   
+
+Wikipedia says
+
+> The observer pattern is a software design pattern in which an object, called the subject, maintains a list of its dependents, called observers, and notifies them automatically of any state changes, usually by calling one of their methods.
+
+**Programmatic Example**
+
+Let's first introduce the weather observer interface and our races, orcs and hobbits.
+
+```java
+public interface WeatherObserver {
+
+  void update(WeatherType currentWeather);
+}
+
+public class Orcs implements WeatherObserver {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(Orcs.class);
+
+  @Override
+  public void update(WeatherType currentWeather) {
+    switch (currentWeather) {
+      case COLD:
+        LOGGER.info("The orcs are freezing cold.");
+        break;
+      case RAINY:
+        LOGGER.info("The orcs are dripping wet.");
+        break;
+      case SUNNY:
+        LOGGER.info("The sun hurts the orcs' eyes.");
+        break;
+      case WINDY:
+        LOGGER.info("The orc smell almost vanishes in the wind.");
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+public class Hobbits implements WeatherObserver {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(Hobbits.class);
+
+  @Override
+  public void update(WeatherType currentWeather) {
+    switch (currentWeather) {
+      case COLD:
+        LOGGER.info("The hobbits are shivering in the cold weather.");
+        break;
+      case RAINY:
+        LOGGER.info("The hobbits look for cover from the rain.");
+        break;
+      case SUNNY:
+        LOGGER.info("The happy hobbits bade in the warm sun.");
+        break;
+      case WINDY:
+        LOGGER.info("The hobbits hold their hats tightly in the windy weather.");
+        break;
+      default:
+        break;
+    }
+  }
+}
+```
+
+Then here's the weather that is constantly changing.
+
+```java
+public class Weather {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(Weather.class);
+
+  private WeatherType currentWeather;
+  private List<WeatherObserver> observers;
+
+  public Weather() {
+    observers = new ArrayList<>();
+    currentWeather = WeatherType.SUNNY;
+  }
+
+  public void addObserver(WeatherObserver obs) {
+    observers.add(obs);
+  }
+
+  public void removeObserver(WeatherObserver obs) {
+    observers.remove(obs);
+  }
+
+  /**
+   * Makes time pass for weather.
+   */
+  public void timePasses() {
+    var enumValues = WeatherType.values();
+    currentWeather = enumValues[(currentWeather.ordinal() + 1) % enumValues.length];
+    LOGGER.info("The weather changed to {}.", currentWeather);
+    notifyObservers();
+  }
+
+  private void notifyObservers() {
+    for (var obs : observers) {
+      obs.update(currentWeather);
+    }
+  }
+}
+```
+
+Here's the full example in action.
+
+```java
+    var weather = new Weather();
+    weather.addObserver(new Orcs());
+    weather.addObserver(new Hobbits());
+
+    weather.timePasses();
+    // The weather changed to rainy.
+    // The orcs are dripping wet.
+    // The hobbits look for cover from the rain.
+    weather.timePasses();
+    // The weather changed to windy.
+    // The orc smell almost vanishes in the wind.
+    // The hobbits hold their hats tightly in the windy weather.
+    weather.timePasses();
+    // The weather changed to cold.
+    // The orcs are freezing cold.
+    // The hobbits are shivering in the cold weather.
+    weather.timePasses();
+    // The weather changed to sunny.
+    //The sun hurts the orcs' eyes.
+    // The happy hobbits bade in the warm sun.
+```
 
 ## Class diagram
 ![alt text](./etc/observer.png "Observer")