#496 Pipeline pattern (#967)

* #496 Add pipeline module to parent pom ✨

* #496: Add main application class and test for pipeline

* #496: Checkstyle format and add log messages on pipeline stages 🎨

* #496: Fill readme sections of pipeline ✨

* #496: Javadocs and checkstyle formatting 🎨

* #496: Follow PMD checks and add more explanation as block comment on App.java

* #496: Apply requested PR changes by iluwatar 🎨

pipeline/README.md

@@ -0,0 +1,37 @@
+---
+layout: pattern
+title: Pipeline
+folder: pipeline
+permalink: /patterns/pipeline/
+categories: Behavioral
+tags:
+ - Java
+ - Functional
+ - Difficulty-Intermediate
+---
+
+## Intent
+Allows processing of data in a series of stages by giving in an initial input and passing the processed output to be used by the next stages.
+
+## Applicability
+Use the Pipeline pattern when you want to
+
+* execute individual stages that yields a final value
+* add readability to complex sequence of operations by providing a fluent builder as an interface
+* improve testability of code since stages will most likely be doing a single thing, complying to the [Single Responsibility Principle (SRP)](https://java-design-patterns.com/principles/#single-responsibility-principle)
+
+## Typical Use Case
+
+* implement stages and execute them in an ordered manner
+
+## Real world examples
+
+* [java.util.Stream](https://docs.oracle.com/javase/8/docs/api/java/util/stream/package-summary.html)
+* [Maven Build Lifecycle](http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html)
+* [Functional Java](https://github.com/functionaljava/functionaljava)
+
+## Credits
+
+* [The Pipeline Pattern — for fun and profit](https://medium.com/@aaronweatherall/the-pipeline-pattern-for-fun-and-profit-9b5f43a98130)
+* [The Pipeline design pattern (in Java)](https://medium.com/@deepakbapat/the-pipeline-design-pattern-in-java-831d9ce2fe21)
+* [Pipelines | Microsoft Docs](https://docs.microsoft.com/en-us/previous-versions/msp-n-p/ff963548(v=pandp.10))

pipeline/pom.xml

@@ -0,0 +1,47 @@
+<?xml version="1.0"?>
+<!--
+
+    The MIT License
+    Copyright (c) 2014-2016 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.
+
+-->
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>com.iluwatar</groupId>
+        <artifactId>java-design-patterns</artifactId>
+        <version>1.22.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>pipeline</artifactId>
+    <dependencies>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

pipeline/src/main/java/com.iluwatar.pipeline/App.java

@@ -0,0 +1,66 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 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.pipeline;
+
+/**
+ * The Pipeline pattern uses ordered stages to process a sequence of input values.
+ * Each implemented task is represented by a stage of the pipeline. You can think of
+ * pipelines as similar to assembly lines in a factory, where each item in the assembly
+ * line is constructed in stages. The partially assembled item is passed from one assembly
+ * stage to another. The outputs of the assembly line occur in the same order as that of the
+ * inputs.
+ *
+ * Classes used in this example are suffixed with "Handlers", and synonymously refers to the
+ * "stage".
+ */
+public class App {
+  /**
+   * Specify the initial input type for the first stage handler and the expected output type
+   * of the last stage handler as type parameters for Pipeline. Use the fluent builder by
+   * calling addHandler to add more stage handlers on the pipeline.
+   */
+  public static void main(String[] args) {
+    /*
+      Suppose we wanted to pass through a String to a series of filtering stages and convert it
+      as a char array on the last stage.
+
+      - Stage handler 1 (pipe): Removing the alphabets, accepts a String input and returns the
+      processed String output. This will be used by the next handler as its input.
+
+      - Stage handler 2 (pipe): Removing the digits, accepts a String input and returns the
+      processed String output. This shall also be used by the last handler we have.
+
+      - Stage handler 3 (pipe): Converting the String input to a char array handler. We would
+      be returning a different type in here since that is what's specified by the requirement.
+      This means that at any stages along the pipeline, the handler can return any type of data
+      as long as it fulfills the requirements for the next handler's input.
+
+      Suppose we wanted to add another handler after ConvertToCharArrayHandler. That handler
+      then is expected to receive an input of char[] array since that is the type being returned
+      by the previous handler, ConvertToCharArrayHandler.
+     */
+    new Pipeline<>(new RemoveAlphabetsHandler())
+        .addHandler(new RemoveDigitsHandler())
+        .addHandler(new ConvertToCharArrayHandler());
+  }
+}

pipeline/src/main/java/com.iluwatar.pipeline/ConvertToCharArrayHandler.java

@@ -0,0 +1,45 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 Ilkka Seppälä
+ * <p>
+ * 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:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * <p>
+ * 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.pipeline;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.Arrays;
+
+/**
+ * Stage handler that converts an input String to its char[] array counterpart.
+ */
+class ConvertToCharArrayHandler implements Handler<String, char[]> {
+
+  private final Logger logger = LoggerFactory.getLogger(ConvertToCharArrayHandler.class);
+
+  @Override
+  public char[] process(String input) {
+    char[] characters = input.toCharArray();
+    logger.info(String.format("Current handler: %s, input is %s of type %s, output is %s, of type %s",
+        ConvertToCharArrayHandler.class, input, String.class, Arrays.toString(characters), Character[].class));
+
+    return characters;
+  }
+}

pipeline/src/main/java/com.iluwatar.pipeline/Handler.java

@@ -0,0 +1,32 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 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.pipeline;
+
+/**
+ * Forms a contract to all stage handlers to accept a certain type of input and return a processed output.
+ * @param <I> the input type of the handler
+ * @param <O> the processed output type of the handler
+ */
+interface Handler<I, O> {
+  O process(I input);
+}

pipeline/src/main/java/com.iluwatar.pipeline/Pipeline.java

@@ -0,0 +1,46 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 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.pipeline;
+
+/**
+ * Main Pipeline class that initially sets the current handler. Processed output
+ * of the initial handler is then passed as the input to the next stage handlers.
+ * @param <I> the type of the input for the first stage handler
+ * @param <O> the final stage handler's output type
+ */
+class Pipeline<I, O> {
+
+  private final Handler<I, O> currentHandler;
+
+  Pipeline(Handler<I, O> currentHandler) {
+    this.currentHandler = currentHandler;
+  }
+
+  <K> Pipeline<I, K> addHandler(Handler<O, K> newHandler) {
+    return new Pipeline<>(input -> newHandler.process(currentHandler.process(input)));
+  }
+
+  O execute(I input) {
+    return currentHandler.process(input);
+  }
+}

pipeline/src/main/java/com.iluwatar.pipeline/RemoveAlphabetsHandler.java

@@ -0,0 +1,54 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 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.pipeline;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Stage handler that returns a new instance of String without the alphabet characters of the input string.
+ */
+class RemoveAlphabetsHandler implements Handler<String, String> {
+
+  private final Logger logger = LoggerFactory.getLogger(RemoveAlphabetsHandler.class);
+
+  @Override
+  public String process(String input) {
+    StringBuilder inputWithoutAlphabets = new StringBuilder();
+
+    for (int index = 0; index < input.length(); index++) {
+      char currentCharacter = input.charAt(index);
+      if (Character.isAlphabetic(currentCharacter)) {
+        continue;
+      }
+
+      inputWithoutAlphabets.append(currentCharacter);
+    }
+
+    String inputWithoutAlphabetsStr = inputWithoutAlphabets.toString();
+    logger.info(String.format("Current handler: %s, input is %s of type %s, output is %s, of type %s",
+        RemoveAlphabetsHandler.class, input, String.class, inputWithoutAlphabetsStr, String.class));
+
+    return inputWithoutAlphabetsStr;
+  }
+}

pipeline/src/main/java/com.iluwatar.pipeline/RemoveDigitsHandler.java

@@ -0,0 +1,54 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 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.pipeline;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Stage handler that returns a new instance of String without the digit characters of the input string.
+ */
+class RemoveDigitsHandler implements Handler<String, String> {
+
+  private final Logger logger = LoggerFactory.getLogger(RemoveDigitsHandler.class);
+
+  @Override
+  public String process(String input) {
+    StringBuilder inputWithoutDigits = new StringBuilder();
+
+    for (int index = 0; index < input.length(); index++) {
+      char currentCharacter = input.charAt(index);
+      if (Character.isDigit(currentCharacter)) {
+        continue;
+      }
+
+      inputWithoutDigits.append(currentCharacter);
+    }
+
+    String inputWithoutDigitsStr = inputWithoutDigits.toString();
+    logger.info(String.format("Current handler: %s, input is %s of type %s, output is %s, of type %s",
+        RemoveDigitsHandler.class, input, String.class, inputWithoutDigitsStr, String.class));
+
+    return inputWithoutDigitsStr;
+  }
+}