Browser docs

Collecting Parameter

April 14, 2023 5 min read Idiom
On this page

Name

Collecting Parameter

Intent

To store the collaborative result of numerous methods within a collection.

Explanation

Real-world example

Within a large corporate building, there exists a global printer queue that is a collection of all the printing jobs that are currently pending. Various floors contain different models of printers, each having a different printing policy. We must construct a program that can continually add appropriate printing jobs to a collection, which is called the collecting parameter.

In plain words

Instead of having one giant method that contains numerous policies for collecting information into a variable, we can create numerous smaller functions that each take parameter, and append new information. We can pass the parameter to all of these smaller functions and by the end, we will have what we wanted originally. This time, the code is cleaner and easier to understand. Because the larger function has been broken down, the code is also easier to modify as changes are localised to the smaller functions.

Wikipedia says

In the Collecting Parameter idiom a collection (list, map, etc.) is passed repeatedly as a parameter to a method which adds items to the collection.

Programmatic example

Coding our example from above, we may use the collection result as a collecting parameter. The following restrictions are implemented:

  • If an A4 paper is coloured, it must also be single-sided. All other non-coloured papers are accepted
  • A3 papers must be non-coloured and single-sided
  • A2 papers must be single-page, single-sided, and non-coloured
 1package com.iluwatar.collectingparameter;
 2import java.util.LinkedList;
 3import java.util.Queue;
 4public class App {
 5  static PrinterQueue printerQueue = PrinterQueue.getInstance();
 6
 7  /**
 8   * Program entry point.
 9   *
10   * @param args command line args
11   */
12  public static void main(String[] args) {
13    /*
14      Initialising the printer queue with jobs
15    */
16    printerQueue.addPrinterItem(new PrinterItem(PaperSizes.A4, 5, false, false));
17    printerQueue.addPrinterItem(new PrinterItem(PaperSizes.A3, 2, false, false));
18    printerQueue.addPrinterItem(new PrinterItem(PaperSizes.A2, 5, false, false));
19
20    /*
21      This variable is the collecting parameter.
22    */    
23    var result = new LinkedList<PrinterItem>();
24
25    /* 
26     * Using numerous sub-methods to collaboratively add information to the result collecting parameter
27     */
28    addA4Papers(result);
29    addA3Papers(result);
30    addA2Papers(result);
31  }
32}

We use the addA4Paper, addA3Paper, and addA2Paper methods to populate the result collecting parameter with the appropriate print jobs as per the policy described previously. The three policies are encoded below,

 1public class App {
 2  static PrinterQueue printerQueue = PrinterQueue.getInstance();
 3  /**
 4   * Adds A4 document jobs to the collecting parameter according to some policy that can be whatever the client
 5   * (the print center) wants.
 6   *
 7   * @param printerItemsCollection the collecting parameter
 8   */
 9  public static void addA4Papers(Queue<PrinterItem> printerItemsCollection) {
10    /*
11      Iterate through the printer queue, and add A4 papers according to the correct policy to the collecting parameter,
12      which is 'printerItemsCollection' in this case.
13     */
14    for (PrinterItem nextItem : printerQueue.getPrinterQueue()) {
15      if (nextItem.paperSize.equals(PaperSizes.A4)) {
16        var isColouredAndSingleSided = nextItem.isColour && !nextItem.isDoubleSided;
17        if (isColouredAndSingleSided) {
18          printerItemsCollection.add(nextItem);
19        } else if (!nextItem.isColour) {
20          printerItemsCollection.add(nextItem);
21        }
22      }
23    }
24  }
25
26  /**
27   * Adds A3 document jobs to the collecting parameter according to some policy that can be whatever the client
28   * (the print center) wants. The code is similar to the 'addA4Papers' method. The code can be changed to accommodate
29   * the wants of the client.
30   *
31   * @param printerItemsCollection the collecting parameter
32   */
33  public static void addA3Papers(Queue<PrinterItem> printerItemsCollection) {
34    for (PrinterItem nextItem : printerQueue.getPrinterQueue()) {
35      if (nextItem.paperSize.equals(PaperSizes.A3)) {
36
37        // Encoding the policy into a Boolean: the A3 paper cannot be coloured and double-sided at the same time
38        var isNotColouredAndSingleSided = !nextItem.isColour && !nextItem.isDoubleSided;
39        if (isNotColouredAndSingleSided) {
40          printerItemsCollection.add(nextItem);
41        }
42      }
43    }
44  }
45
46  /**
47   * Adds A2 document jobs to the collecting parameter according to some policy that can be whatever the client
48   * (the print center) wants. The code is similar to the 'addA4Papers' method. The code can be changed to accommodate
49   * the wants of the client.
50   *
51   * @param printerItemsCollection the collecting parameter
52   */
53  public static void addA2Papers(Queue<PrinterItem> printerItemsCollection) {
54    for (PrinterItem nextItem : printerQueue.getPrinterQueue()) {
55      if (nextItem.paperSize.equals(PaperSizes.A2)) {
56
57        // Encoding the policy into a Boolean: the A2 paper must be single page, single-sided, and non-coloured.
58        var isNotColouredSingleSidedAndOnePage = nextItem.pageCount == 1 && !nextItem.isDoubleSided
59                && !nextItem.isColour;
60        if (isNotColouredSingleSidedAndOnePage) {
61          printerItemsCollection.add(nextItem);
62        }
63      }
64    }
65  }
66}

Each method takes a collecting parameter as an argument. It then adds elements, taken from a global variable, to this collecting parameter if each element satisfies a given criteria. These methods can have whatever policy the client desires.

In this programmatic example, three print jobs are added to the queue. Only the first two print jobs should be added to the collecting parameter as per the policy. The elements of the result variable after execution are,

paperSizepageCountisDoubleSidedisColour
A45falsefalse
A32falsefalse

which is what we expected.

Class diagram

alt text

Applicability

Use the Collecting Parameter design pattern when

  • you want to return a collection or object that is the collaborative result of several methods
  • You want to simplify a method that accumulates data as the original method is too complex

Tutorials

Tutorials for this method are found in:

Known uses

Joshua Kerivsky gives a real-world example in his book ‘Refactoring to Patterns’. He gives an example of using the Collecting Parameter Design Pattern to create a toString() method for an XML tree. Without using this design pattern, this would require a bulky function with conditionals and concatenation that would worsen code readability. Such a method can be broken down into smaller methods, each appending their own set of information to the collecting parameter.

See this in Refactoring To Patterns.

Consequences

Pros:

  • Makes code more readable
  • Avoids ’linkages’, where numerous methods reference the same global variable
  • Increases maintainability by decomposing larger functions

Cons:

  • May increase code length
  • Adds ’layers’ of methods

Credits

Following books were used: