From 5aacdecc6c8ce614086b8cefc8f97a45fe76799c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= <ilkka.seppala@gofore.com>
Date: Sat, 18 Jul 2020 11:25:49 +0300
Subject: [PATCH] #590 add explanation for Callback

---
 callback/README.md                            | 61 ++++++++++++++++++-
 .../com/iluwatar/callback/LambdasApp.java     | 48 ---------------
 .../main/java/com/iluwatar/callback/Task.java |  2 +-
 3 files changed, 59 insertions(+), 52 deletions(-)
 delete mode 100644 callback/src/main/java/com/iluwatar/callback/LambdasApp.java

diff --git a/callback/README.md b/callback/README.md
index 6942019f3..78766cc15 100644
--- a/callback/README.md
+++ b/callback/README.md
@@ -9,9 +9,64 @@ tags:
 ---
 
 ## Intent
-Callback is a piece of executable code that is passed as an
-argument to other code, which is expected to call back (execute) the argument
-at some convenient time.
+Callback is a piece of executable code that is passed as an argument to other code, which is expected to call back 
+(execute) the argument at some convenient time.
+
+## Explanation
+
+Real world example
+
+> We need to be notified after executing task has finished. We pass a callback method for the executor and wait for it to call back on us.     
+
+In plain words
+
+> Callback is a method passed to the executor which will be called at defined moment. 
+
+Wikipedia says
+
+> In computer programming, a callback, also known as a "call-after" function, is any executable code that is passed as an argument to other code; that other code is expected to call back (execute) the argument at a given time.
+
+**Programmatic Example**
+
+Callback is a simple interface with single method.
+
+```java
+public interface Callback {
+
+  void call();
+}
+```
+
+Next we define a task that will execute the callback after the task execution has finished.
+
+```java
+public abstract class Task {
+
+  final void executeWith(Callback callback) {
+    execute();
+    Optional.ofNullable(callback).ifPresent(Callback::call);
+  }
+
+  public abstract void execute();
+}
+
+public final class SimpleTask extends Task {
+
+  private static final Logger LOGGER = getLogger(SimpleTask.class);
+
+  @Override
+  public void execute() {
+    LOGGER.info("Perform some important activity and after call the callback method.");
+  }
+}
+```
+
+Finally here's how we execute a task and receive a callback when it's finished.
+
+```java
+    var task = new SimpleTask();
+    task.executeWith(() -> LOGGER.info("I'm done now."));
+```
 
 ## Class diagram
 ![alt text](./etc/callback.png "Callback")
diff --git a/callback/src/main/java/com/iluwatar/callback/LambdasApp.java b/callback/src/main/java/com/iluwatar/callback/LambdasApp.java
deleted file mode 100644
index d433217ba..000000000
--- a/callback/src/main/java/com/iluwatar/callback/LambdasApp.java
+++ /dev/null
@@ -1,48 +0,0 @@
-/*
- * The MIT License
- * Copyright © 2014-2019 Ilkka Seppälä
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
- */
-
-package com.iluwatar.callback;
-
-import static org.slf4j.LoggerFactory.getLogger;
-
-import org.slf4j.Logger;
-
-/**
- * This example generates the exact same output as {@link App} however the callback has been defined
- * as a Lambdas expression.
- */
-public final class LambdasApp {
-
-  private static final Logger LOGGER = getLogger(LambdasApp.class);
-
-  private LambdasApp() {
-  }
-
-  /**
-   * Program entry point.
-   */
-  public static void main(final String[] args) {
-    var task = new SimpleTask();
-    task.executeWith(() -> LOGGER.info("I'm done now."));
-  }
-}
diff --git a/callback/src/main/java/com/iluwatar/callback/Task.java b/callback/src/main/java/com/iluwatar/callback/Task.java
index 5632dbc4f..f3e8e478a 100644
--- a/callback/src/main/java/com/iluwatar/callback/Task.java
+++ b/callback/src/main/java/com/iluwatar/callback/Task.java
@@ -33,7 +33,7 @@ public abstract class Task {
   /**
    * Execute with callback.
    */
-  final void executeWith(final Callback callback) {
+  final void executeWith(Callback callback) {
     execute();
     Optional.ofNullable(callback).ifPresent(Callback::call);
   }