docs: update parameter object

Author: iluwatar

parameter-object/README.md

@@ -1,136 +1,171 @@
 ---
 title: Parameter Object
-category: Behavioral
+category: Structural
 language: en
 tag:
- - Extensibility
+    - Abstraction
+    - Code simplification
+    - Decoupling
+    - Encapsulation
+    - Object composition
 ---
 
+## Also known as
+
+* Argument Object
+
 ## Intent
 
-The syntax of Java language doesn’t allow you to declare a method with a predefined value
-for a parameter. Probably the best option to achieve default method parameters in Java is
-by using the method overloading. Method overloading allows you to declare several methods
-with the same name but with a different number of parameters. But the main problem with
-method overloading as a solution for default parameter values reveals itself when a method
-accepts multiple parameters. Creating an overloaded method for each possible combination of
-parameters might be cumbersome. To deal with this issue, the Parameter Object pattern is used.
+Simplify method signatures by encapsulating parameters into a single object, promoting cleaner code and better maintainability.
 
 ## Explanation
 
-The Parameter Object is simply a wrapper object for all parameters of a method.
-It is nothing more than just a regular POJO. The advantage of the Parameter Object over a
-regular method parameter list is the fact that class fields can have default values.
-Once the wrapper class is created for the method parameter list, a corresponding builder class
-is also created. Usually it's an inner static class. The final step is to use the builder
-to construct a new parameter object. For those parameters that are skipped,
-their default values are going to be used.
+Real-world example
 
+> Imagine booking a travel package that includes a flight, hotel, and car rental. Instead of asking the customer to provide separate details for each component (flight details, hotel details, and car rental details) every time, a travel agent asks the customer to fill out a single comprehensive form that encapsulates all the necessary information:
+>
+> - Flight details: Departure city, destination city, departure date, return date.
+> - Hotel details: Hotel name, check-in date, check-out date, room type.
+> - Car rental details: Pickup location, drop-off location, rental dates, car type.
+> 
+> In this analogy, the comprehensive form is the parameter object. It groups together all related details (parameters) into a single entity, making the booking process more streamlined and manageable. The travel agent (method) only needs to handle one form (parameter object) instead of juggling multiple pieces of information.
 
-**Programmatic Example**
+In plain words
 
-Here's the simple `SearchService` class where Method Overloading is used to default values here. To use method overloading, either the number of arguments or argument type has to be different.
+> The Parameter Object pattern encapsulates multiple related parameters into a single object to simplify method signatures and enhance code maintainability.
 
-```java
-public class SearchService {
-  //Method Overloading example. SortOrder is defaulted in this method
-  public String search(String type, String sortBy) {
-    return getQuerySummary(type, sortBy, SortOrder.DESC);
-  }
-
-  /* Method Overloading example. SortBy is defaulted in this method. Note that the type has to be 
-  different here to overload the method */
-  public String search(String type, SortOrder sortOrder) {
-    return getQuerySummary(type, "price", sortOrder);
-  }
-
-  private String getQuerySummary(String type, String sortBy, SortOrder sortOrder) {
-    return "Requesting shoes of type \"" + type + "\" sorted by \"" + sortBy + "\" in \""
-        + sortOrder.getValue() + "ending\" order...";
-  }
-}
+wiki.c2.com says
 
-```
+> Replace the LongParameterList with a ParameterObject; an object or structure with data members representing the arguments to be passed in.
 
-Next we present the `SearchService` with `ParameterObject` created with Builder pattern.
+**Programmatic example**
 
-```java
-public class SearchService {
+The Parameter Object design pattern is a way to group multiple parameters into a single object. This simplifies method signatures and enhances code maintainability.
 
-  /* Parameter Object example. Default values are abstracted into the Parameter Object 
-  at the time of Object creation */
-  public String search(ParameterObject parameterObject) {
-    return getQuerySummary(parameterObject.getType(), parameterObject.getSortBy(),
-        parameterObject.getSortOrder());
-  }
-  
-  private String getQuerySummary(String type, String sortBy, SortOrder sortOrder) {
-    return "Requesting shoes of type \"" + type + "\" sorted by \"" + sortBy + "\" in \""
-        + sortOrder.getValue() + "ending\" order...";
-  }
-}
+First, let's look at the `ParameterObject` class. This class encapsulates the parameters needed for the search operation. It uses [Builder pattern](https://java-design-patterns.com/patterns/builder/) to allow for easy creation of objects, even when there are many parameters.
 
+```java
 public class ParameterObject {
-  public static final String DEFAULT_SORT_BY = "price";
-  public static final SortOrder DEFAULT_SORT_ORDER = SortOrder.ASC;
 
-  private String type;
-  private String sortBy = DEFAULT_SORT_BY;
-  private SortOrder sortOrder = DEFAULT_SORT_ORDER;
+    private final String type;
+    private final String sortBy;
+    private final SortOrder sortOrder;
 
-  private ParameterObject(Builder builder) {
-    type = builder.type;
-    sortBy = builder.sortBy != null && !builder.sortBy.isBlank() ? builder.sortBy : sortBy;
-    sortOrder = builder.sortOrder != null ? builder.sortOrder : sortOrder;
-  }
+    private ParameterObject(Builder builder) {
+        this.type = builder.type;
+        this.sortBy = builder.sortBy;
+        this.sortOrder = builder.sortOrder;
+    }
 
-  public static Builder newBuilder() {
-    return new Builder();
-  }
+    public static Builder newBuilder() {
+        return new Builder();
+    }
 
-  //Getters and Setters...
+    // getters and Builder class omitted for brevity
+}
+```
 
-  public static final class Builder {
+The `Builder` class inside `ParameterObject` provides a way to construct a `ParameterObject` instance. It has methods for setting each of the parameters, and a `build()` method to create the `ParameterObject`.
 
-    private String type;
-    private String sortBy;
-    private SortOrder sortOrder;
+```java
+public static class Builder {
 
-    private Builder() {
-    }
+    private String type = "all";
+    private String sortBy = "price";
+    private SortOrder sortOrder = SortOrder.ASCENDING;
 
     public Builder withType(String type) {
-      this.type = type;
-      return this;
+        this.type = type;
+        return this;
     }
 
     public Builder sortBy(String sortBy) {
-      this.sortBy = sortBy;
-      return this;
+        this.sortBy = sortBy;
+        return this;
     }
 
     public Builder sortOrder(SortOrder sortOrder) {
-      this.sortOrder = sortOrder;
-      return this;
+        this.sortOrder = sortOrder;
+        return this;
     }
 
     public ParameterObject build() {
-      return new ParameterObject(this);
+        return new ParameterObject(this);
     }
-  }
 }
+```
+
+The `SearchService` class has a `search()` method that takes a `ParameterObject` as a parameter. This method uses the parameters encapsulated in the `ParameterObject` to perform a search operation.
 
+```java
+public class SearchService {
 
+    public String search(ParameterObject parameterObject) {
+        return getQuerySummary(parameterObject.getType(), parameterObject.getSortBy(),
+                parameterObject.getSortOrder());
+    }
+
+    // getQuerySummary method omitted for brevity
+}
+```
+
+Finally, in the `App` class, we create a `ParameterObject` using its builder, and then pass it to the `search()` method of `SearchService`.
+
+```java
+public class App {
+
+    public static void main(String[] args) {
+        ParameterObject params = ParameterObject.newBuilder()
+                .withType("sneakers")
+                .sortBy("brand")
+                .build();
+        LOGGER.info(params.toString());
+        LOGGER.info(new SearchService().search(params));
+    }
+}
 ```
 
+This example demonstrates how the Parameter Object pattern can simplify method signatures and make the code more maintainable. It also shows how the pattern can be combined with the Builder pattern to make object creation more flexible and readable.
+
 ## Class diagram
 
-![alt text](./etc/parameter-object.png "Parameter Object")
+![Parameter Object](./etc/parameter-object.png "Parameter Object")
 
 ## Applicability
 
-This pattern shows us the way to have default parameters for a method in Java as the language doesn't default parameters feature out of the box. 
+* Methods require multiple parameters that logically belong together.
+* There is a need to reduce the complexity of method signatures.
+* The parameters may need to evolve over time, adding more properties without breaking existing method signatures.
+* It’s beneficial to pass data through a method chain.
+
+## Known Uses
+
+* Java Libraries: Many Java frameworks and libraries use this pattern. For example, Java’s java.util.Calendar class has various methods where parameter objects are used to represent date and time components.
+* Enterprise Applications: In large enterprise systems, parameter objects are used to encapsulate configuration data passed to services or API endpoints.
+
+## Consequences
+
+Benefits:
+
+* Encapsulation: Groups related parameters into a single object, promoting encapsulation.
+* Maintainability: Reduces method signature changes when parameters need to be added or modified.
+* Readability: Simplifies method signatures, making the code easier to read and understand.
+* Reusability: Parameter objects can be reused across different methods, reducing redundancy.
+
+Trade-offs:
+
+* Overhead: Introducing parameter objects can add some overhead, especially for simple methods that do not benefit significantly from this abstraction.
+* Complexity: The initial creation of parameter objects might add complexity, especially for beginners.
+
+## Related Patterns
+
+* [Builder](https://java-design-patterns.com/patterns/builder/): Helps in creating complex objects step-by-step, often used in conjunction with parameter objects to manage the construction of these objects.
+* [Composite](https://java-design-patterns.com/patterns/composite/): Sometimes used with parameter objects to handle hierarchical parameter data.
+* [Factory Method](https://java-design-patterns.com/patterns/factory-method/): Can be used to create instances of parameter objects, particularly when different parameter combinations are needed.
 
 ## Credits
 
-- [Does Java have default parameters?](http://dolszewski.com/java/java-default-parameters)
+* [Does Java have default parameters? - Daniel Olszewski](http://dolszewski.com/java/java-default-parameters)
+* [Design Patterns: Elements of Reusable Object-Oriented Software](https://amzn.to/3w0pvKI)
+* [Effective Java](https://amzn.to/4cGk2Jz)
+* [Refactoring: Improving the Design of Existing Code](https://amzn.to/3TVEgaB)

parameter-object/src/main/java/com/iluwatar/parameter/object/ParameterObject.java

@@ -24,9 +24,14 @@
  */
 package com.iluwatar.parameter.object;
 
+import lombok.Getter;
+import lombok.Setter;
+
 /**
  * ParameterObject.
  */
+@Getter
+@Setter
 public class ParameterObject {
 
   /**
@@ -56,30 +61,6 @@ public static Builder newBuilder() {
     return new Builder();
   }
 
-  public String getType() {
-    return type;
-  }
-
-  public void setType(String type) {
-    this.type = type;
-  }
-
-  public String getSortBy() {
-    return sortBy;
-  }
-
-  public void setSortBy(String sortBy) {
-    this.sortBy = sortBy;
-  }
-
-  public SortOrder getSortOrder() {
-    return sortOrder;
-  }
-
-  public void setSortOrder(SortOrder sortOrder) {
-    this.sortOrder = sortOrder;
-  }
-
   @Override
   public String toString() {
     return String.format("ParameterObject[type='%s', sortBy='%s', sortOrder='%s']",

parameter-object/src/main/java/com/iluwatar/parameter/object/SearchService.java

@@ -33,7 +33,7 @@ public class SearchService {
    * Below two methods of name `search` is overloaded so that we can send a default value for
    * one of the criteria and call the final api. A default SortOrder is sent in the first method
    * and a default SortBy is sent in the second method. So two separate method definitions are
-   * needed for having default values for one argument in each case. Hence multiple overloaded
+   * needed for having default values for one argument in each case. Hence, multiple overloaded
    * methods are needed as the number of argument increases.
    */
   public String search(String type, String sortBy) {

parameter-object/src/main/java/com/iluwatar/parameter/object/SortOrder.java

@@ -24,20 +24,19 @@
  */
 package com.iluwatar.parameter.object;
 
+import lombok.Getter;
+
 /**
  * enum for sort order types.
  */
 public enum SortOrder {
   ASC("asc"),
   DESC("desc");
 
+  @Getter
   private String value;
 
   SortOrder(String value) {
     this.value = value;
   }
-
-  public String getValue() {
-    return value;
-  }
 }