From 8a91cbba89e26bea9470dc3613e1c82c0170b630 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= <ilkka.seppala@gofore.com>
Date: Wed, 13 Mar 2024 20:21:03 +0200
Subject: [PATCH] docs: improve Balking pattern docs

---
 balking/README.md                             | 25 ++++++++++++++++---
 .../com/iluwatar/balking/WashingMachine.java  |  9 +++----
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/balking/README.md b/balking/README.md
index d187b7be8..486439c68 100644
--- a/balking/README.md
+++ b/balking/README.md
@@ -8,8 +8,7 @@ tag:
 
 ## Intent
 
-Balking Pattern is used to prevent an object from executing a certain code if it is in an incomplete 
-or inappropriate state.
+Balking Pattern is used to prevent an object from executing a certain code if it is in an incomplete  or inappropriate state. If the state is not suitable for the action, the method call is ignored (or "balked").
 
 ## Explanation
 
@@ -126,11 +125,31 @@ Use the Balking pattern when
 * You want to invoke an action on an object only when it is in a particular state
 * Objects are generally only in a state that is prone to balking temporarily but for an unknown 
   amount of time
+* In multithreaded applications where certain actions should only proceed when specific conditions are met, and those conditions are expected to change over time due to external factors or concurrent operations.
+
+## Known Uses:
+
+* Resource pooling, where resources are only allocated if they are in a valid state for allocation.
+* Thread management, where threads only proceed with tasks if certain conditions (like task availability or resource locks) are met.
+
+## Consequences:
+
+Benefits:
+
+* Reduces unnecessary lock acquisitions in situations where actions cannot proceed, enhancing performance in concurrent applications.
+* Encourages clear separation of state management and behavior, leading to cleaner code.
+* Simplifies the handling of operations that should only be performed under certain conditions without cluttering the caller code with state checks.
+
+Trade-offs:
+
+* Can introduce complexity by obscuring the conditions under which actions are taken or ignored, potentially making the system harder to debug and understand.
+* May lead to missed opportunities or actions if the state changes are not properly monitored or if the balking condition is too restrictive.
 
 ## Related patterns
 
+* [Double-Checked Locking Pattern](https://java-design-patterns.com/patterns/double-checked-locking/)
 * [Guarded Suspension Pattern](https://java-design-patterns.com/patterns/guarded-suspension/)
-* [Double Checked Locking Pattern](https://java-design-patterns.com/patterns/double-checked-locking/)
+* [State](https://java-design-patterns.com/patterns/state/)
 
 ## Credits
 
diff --git a/balking/src/main/java/com/iluwatar/balking/WashingMachine.java b/balking/src/main/java/com/iluwatar/balking/WashingMachine.java
index 6f2713c5a..794cfbd8a 100644
--- a/balking/src/main/java/com/iluwatar/balking/WashingMachine.java
+++ b/balking/src/main/java/com/iluwatar/balking/WashingMachine.java
@@ -25,6 +25,7 @@
 package com.iluwatar.balking;
 
 import java.util.concurrent.TimeUnit;
+import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;
 
 /**
@@ -34,6 +35,8 @@ import lombok.extern.slf4j.Slf4j;
 public class WashingMachine {
 
   private final DelayProvider delayProvider;
+
+  @Getter
   private WashingMachineState washingMachineState;
 
   /**
@@ -60,10 +63,6 @@ public class WashingMachine {
     this.washingMachineState = WashingMachineState.ENABLED;
   }
 
-  public WashingMachineState getWashingMachineState() {
-    return washingMachineState;
-  }
-
   /**
    * Method responsible for washing if the object is in appropriate state.
    */
@@ -83,7 +82,7 @@ public class WashingMachine {
   }
 
   /**
-   * Method responsible of ending the washing by changing machine state.
+   * Method is responsible for ending the washing by changing machine state.
    */
   public synchronized void endOfWashing() {
     washingMachineState = WashingMachineState.ENABLED;