feature: #1261 Added collecting parameter design pattern (#2134)

* #1261 Added base directories, folders, and file for the collecting parameter design pattern. * #1261 Added initial comment * #1261 Added Maven Dependencies * #1261 Added Maven Dependencies * #1261 Finished README.md file * #1261 Added tests * #1261 Code adheres to the standard * #1261 Code adheres to the standard * #1261 Code adheres to the standard * #1261 - Added table to README.md - Explicitly state that result is the collecting parameter - Improved applicability - Separated PrinterItem.java from PrinterQueue.java - Tests work now - Giant comment split * #1261 fixed programmatic example in README.md. * #1261 updated class diagram * #1261 Fixed everything. * #1261 Minor edit to README.md. * #1261 Minor edit to README.md. * #1261 Minor updates. * #1261 Fixed code style. * #1261 Removed getPrinterQueue test * #1261 Removed code smells * #1261 Added UML plugin. * #1261 Dependencies resolved. * #1261 Specified the UML diagram paths. Perhaps this will work. * #1261 pom.xml updated with UML wrapper. Maybe this will create class diagram when built? * #1261 UML added. * #1261 - README.md obeys the YAML requirements - Typo in README.md fixed - UMLWrapper removed from module pom.xml - More comments added Should be able to merge now :)
2026-05-17 22:59:43 +00:00 · 2022-11-20 23:37:33 +11:00
parent ba5aee0a1d
commit fcaf72fdf8
12 changed files with 663 additions and 0 deletions
@@ -0,0 +1,138 @@
+/*
+ * This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt).
+ *
+ * The MIT License
+ * Copyright © 2014-2022 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.collectingparameter;
+
+import java.util.LinkedList;
+import java.util.Queue;
+
+/**
+ * The Collecting Parameter Design Pattern aims to return a result that is the collaborative result of several
+ * methods. This design pattern uses a 'collecting parameter' that is passed to several functions, accumulating results
+ * as it travels from method-to-method. This is different to the Composed Method design pattern, where a single
+ * collection is modified via several methods.
+ *
+ * <p>This example is inspired by Kent Beck's example in his book, 'Smalltalk Best Practice Patterns'. The context for this
+ * situation is that there is a single printer queue {@link PrinterQueue} that holds numerous print jobs
+ * {@link PrinterItem} that must be distributed to various print centers.
+ * Each print center has its own requirements and printing limitations. In this example, the following requirements are:
+ * If an A4 document is coloured, it must also be single-sided. All other non-coloured A4 documents are accepted.
+ * All A3 documents must be non-coloured and single sided. All A2 documents must be a single page, single sided, and
+ * non-coloured.
+ *
+ * <p>A collecting parameter (the result variable) is used to filter the global printer queue so that it meets the
+ * requirements for this centre,
+ **/
+
+public class App {
+  static PrinterQueue printerQueue = PrinterQueue.getInstance();
+
+  /**
+   * Program entry point.
+   *
+   * @param args command line args
+   */
+  public static void main(String[] args) {
+    /*
+      Initialising the printer queue with jobs
+    */
+    printerQueue.addPrinterItem(new PrinterItem(PaperSizes.A4, 5, false, false));
+    printerQueue.addPrinterItem(new PrinterItem(PaperSizes.A3, 2, false, false));
+    printerQueue.addPrinterItem(new PrinterItem(PaperSizes.A2, 5, false, false));
+
+    /*
+      This variable is the collecting parameter, and will store the policy abiding print jobs.
+    */
+    var result = new LinkedList<PrinterItem>();
+
+    /*
+      Adding A4, A3, and A2 papers that obey the policy
+    */
+    addValidA4Papers(result);
+    addValidA3Papers(result);
+    addValidA2Papers(result);
+  }
+
+  /**
+   * Adds A4 document jobs to the collecting parameter according to some policy that can be whatever the client
+   * (the print center) wants.
+   *
+   * @param printerItemsCollection the collecting parameter
+   */
+  public static void addValidA4Papers(Queue<PrinterItem> printerItemsCollection) {
+    /*
+      Iterate through the printer queue, and add A4 papers according to the correct policy to the collecting parameter,
+      which is 'printerItemsCollection' in this case.
+     */
+    for (PrinterItem nextItem : printerQueue.getPrinterQueue()) {
+      if (nextItem.paperSize.equals(PaperSizes.A4)) {
+        var isColouredAndSingleSided = nextItem.isColour && !nextItem.isDoubleSided;
+        if (isColouredAndSingleSided || !nextItem.isColour) {
+          printerItemsCollection.add(nextItem);
+        }
+      }
+    }
+  }
+
+  /**
+   * Adds A3 document jobs to the collecting parameter according to some policy that can be whatever the client
+   * (the print center) wants. The code is similar to the 'addA4Papers' method. The code can be changed to accommodate
+   * the wants of the client.
+   *
+   * @param printerItemsCollection the collecting parameter
+   */
+  public static void addValidA3Papers(Queue<PrinterItem> printerItemsCollection) {
+    for (PrinterItem nextItem : printerQueue.getPrinterQueue()) {
+      if (nextItem.paperSize.equals(PaperSizes.A3)) {
+
+        // Encoding the policy into a Boolean: the A3 paper cannot be coloured and double-sided at the same time
+        var isNotColouredAndSingleSided = !nextItem.isColour && !nextItem.isDoubleSided;
+        if (isNotColouredAndSingleSided) {
+          printerItemsCollection.add(nextItem);
+        }
+      }
+    }
+  }
+
+  /**
+   * Adds A2 document jobs to the collecting parameter according to some policy that can be whatever the client
+   * (the print center) wants. The code is similar to the 'addA4Papers' method. The code can be changed to accommodate
+   * the wants of the client.
+   *
+   * @param printerItemsCollection the collecting parameter
+   */
+  public static void addValidA2Papers(Queue<PrinterItem> printerItemsCollection) {
+    for (PrinterItem nextItem : printerQueue.getPrinterQueue()) {
+      if (nextItem.paperSize.equals(PaperSizes.A2)) {
+
+        // Encoding the policy into a Boolean: the A2 paper must be single page, single-sided, and non-coloured.
+        var isNotColouredSingleSidedAndOnePage = nextItem.pageCount == 1 && !nextItem.isDoubleSided
+                && !nextItem.isColour;
+        if (isNotColouredSingleSidedAndOnePage) {
+          printerItemsCollection.add(nextItem);
+        }
+      }
+    }
+  }
+}
@@ -0,0 +1,7 @@
+package com.iluwatar.collectingparameter;
+
+enum PaperSizes {
+  A2,
+  A3,
+  A4
+}
@@ -0,0 +1,34 @@
+package com.iluwatar.collectingparameter;
+
+import java.util.Objects;
+
+/**
+ * This class represents a Print Item, that should be added to the queue.
+ **/
+public class PrinterItem {
+  PaperSizes paperSize;
+  int pageCount;
+  boolean isDoubleSided;
+  boolean isColour;
+
+  /**
+   * The {@link PrinterItem} constructor.
+   **/
+  public PrinterItem(PaperSizes paperSize, int pageCount, boolean isDoubleSided, boolean isColour) {
+    if (!Objects.isNull(paperSize)) {
+      this.paperSize = paperSize;
+    } else {
+      throw new IllegalArgumentException();
+    }
+
+    if (pageCount > 0) {
+      this.pageCount = pageCount;
+    } else {
+      throw new IllegalArgumentException();
+    }
+
+    this.isColour = isColour;
+    this.isDoubleSided = isDoubleSided;
+
+  }
+}
@@ -0,0 +1,52 @@
+package com.iluwatar.collectingparameter;
+
+import java.util.LinkedList;
+import java.util.Objects;
+import java.util.Queue;
+
+/**
+ * This class represents a singleton Printer Queue. It contains a queue that can be filled up with {@link PrinterItem}.
+ **/
+public class PrinterQueue {
+
+  static PrinterQueue currentInstance = null;
+  private final Queue<PrinterItem> printerItemQueue;
+
+  /**
+   * This class is a singleton. The getInstance method will ensure that only one instance exists at a time.
+   */
+  public static PrinterQueue getInstance() {
+    if (Objects.isNull(currentInstance)) {
+      currentInstance = new PrinterQueue();
+    }
+    return currentInstance;
+  }
+
+  /**
+   * Empty the printer queue.
+   */
+  public void emptyQueue() {
+    currentInstance.getPrinterQueue().clear();
+  }
+
+  /**
+   * Private constructor prevents instantiation, unless using the getInstance() method.
+   */
+  private PrinterQueue() {
+    printerItemQueue = new LinkedList<>();
+  }
+
+  public Queue<PrinterItem> getPrinterQueue() {
+    return currentInstance.printerItemQueue;
+  }
+
+  /**
+   * Adds a single print job to the queue.
+   *
+   * @param printerItem The printing job to be added to the queue
+   */
+  public void addPrinterItem(PrinterItem printerItem) {
+    currentInstance.getPrinterQueue().add(printerItem);
+  }
+
+}