From 0b17abdf11aeb50172c5c52c3596a825f9508bc0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= <ilkka.seppala@gofore.com>
Date: Sat, 2 Nov 2019 14:45:50 +0200
Subject: [PATCH] #590 Add explanation for Specification pattern

---
 specification/README.md | 70 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 3 deletions(-)

diff --git a/specification/README.md b/specification/README.md
index 564830653..a72e253d7 100644
--- a/specification/README.md
+++ b/specification/README.md
@@ -7,6 +7,7 @@ categories: Behavioral
 tags:
  - Java
  - Difficulty-Beginner
+ - Searching
 ---
 
 ## Also known as
@@ -16,15 +17,78 @@ Filter, Criteria
 Specification pattern separates the statement of how to match a
 candidate, from the candidate object that it is matched against. As well as its
 usefulness in selection, it is also valuable for validation and for building to
-order
+order.
 
 ![alt text](./etc/specification.png "Specification")
 
 ## Applicability
 Use the Specification pattern when
 
-* you need to select a subset of objects based on some criteria, and to refresh the selection at various times
-* you need to check that only suitable objects are used for a certain role (validation)
+* You need to select a subset of objects based on some criteria, and to refresh the selection at various times.
+* You need to check that only suitable objects are used for a certain role (validation).
+
+## Explanation
+
+Real world example
+
+> There is a pool of different creatures and we often need to select some subset of them. We can write our search specification such as "creatures that can fly" and give it to the party that will perform the filtering.
+
+In Plain Words
+
+> Specification pattern allows us to separate the search criteria from the object that performs the search.
+
+Wikipedia says
+
+> In computer programming, the specification pattern is a particular software design pattern, whereby business rules can be recombined by chaining the business rules together using boolean logic.
+
+**Programmatic Example**
+
+If we look at our creature pool example from above, we have a set of creatures with certain properties.
+
+```java
+public interface Creature {
+  String getName();
+  Size getSize();
+  Movement getMovement();
+  Color getColor();
+}
+```
+
+And dragon implementation looks like this.
+
+```java
+public class Dragon extends AbstractCreature {
+
+  public Dragon() {
+    super("Dragon", Size.LARGE, Movement.FLYING, Color.RED);
+  }
+}
+```
+
+Now that we want to select some subset of them, we use selectors. To select creatures that fly, we should use MovementSelector.
+
+```java
+public class MovementSelector implements Predicate<Creature> {
+
+  private final Movement movement;
+
+  public MovementSelector(Movement m) {
+    this.movement = m;
+  }
+
+  @Override
+  public boolean test(Creature t) {
+    return t.getMovement().equals(movement);
+  }
+}
+```
+
+With these building blocks in place, we can perform a search for red and flying creatures like this.
+
+```java
+    List<Creature> redAndFlyingCreatures = creatures.stream()
+            .filter(new ColorSelector(Color.RED).and(new MovementSelector(Movement.FLYING))).collect(Collectors.toList());
+```
 
 ## Related patterns