feature: resolve #1282 for Lockable Object pattern. (#1702)

* Added Lockable-Object pattern. Closes #1282.

* Refactor method name.

* Refactor sonar lint bugs.

* Added tests and enum Constants.

* Increase coverage.

* Changed @Data to Getters and Setters.

* Iluwatar's comment on pull request #1702.

* Fixed codes mells.

* Incremented wait time to 3 seconds.

* Reduced wait time to 2 seconds.

* Cleaned Code Smells.

* Incremented wait time, removed cool down.

* Refactored README.md file.

Co-authored-by: Subhrodip Mohanta <subhrodipmohanta@gmail.com>

lockable-object/src/main/java/com/iluwatar/lockableobject/App.java

@@ -0,0 +1,77 @@
+package com.iluwatar.lockableobject;
+
+import com.iluwatar.lockableobject.domain.Creature;
+import com.iluwatar.lockableobject.domain.Elf;
+import com.iluwatar.lockableobject.domain.Feind;
+import com.iluwatar.lockableobject.domain.Human;
+import com.iluwatar.lockableobject.domain.Orc;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * The Lockable Object pattern is a concurrency pattern. Instead of using the "synchronized" word
+ * upon the methods to be synchronized, the object which implements the Lockable interface handles
+ * the request.
+ *
+ * <p>In this example, we create a new Lockable object with the SwordOfAragorn implementation of it.
+ * Afterwards we create 6 Creatures with the Elf, Orc and Human implementations and assign them each
+ * to a Fiend object and the Sword is the target object. Because there is only one Sword and it uses
+ * the Lockable Object pattern, only one creature can hold the sword at a given time. When the sword
+ * is locked, any other alive Fiends will try to lock, which will result in a race to lock the
+ * sword.
+ *
+ * @author Noam Greenshtain
+ */
+@Slf4j
+public class App implements Runnable {
+
+  private static final int WAIT_TIME = 3;
+  private static final int WORKERS = 2;
+  private static final int MULTIPLICATION_FACTOR = 3;
+
+  /**
+   * main method.
+   *
+   * @param args as arguments for the main method.
+   */
+  public static void main(String[] args) {
+    var app = new App();
+    app.run();
+  }
+
+  @Override
+  public void run() {
+    // The target object for this example.
+    var sword = new SwordOfAragorn();
+    // Creation of creatures.
+    List<Creature> creatures = new ArrayList<>();
+    for (var i = 0; i < WORKERS; i++) {
+      creatures.add(new Elf(String.format("Elf %s", i)));
+      creatures.add(new Orc(String.format("Orc %s", i)));
+      creatures.add(new Human(String.format("Human %s", i)));
+    }
+    int totalFiends = WORKERS * MULTIPLICATION_FACTOR;
+    ExecutorService service = Executors.newFixedThreadPool(totalFiends);
+    // Attach every creature and the sword is a Fiend to fight for the sword.
+    for (var i = 0; i < totalFiends; i = i + MULTIPLICATION_FACTOR) {
+      service.submit(new Feind(creatures.get(i), sword));
+      service.submit(new Feind(creatures.get(i + 1), sword));
+      service.submit(new Feind(creatures.get(i + 2), sword));
+    }
+    // Wait for program to terminate.
+    try {
+      if (!service.awaitTermination(WAIT_TIME, TimeUnit.SECONDS)) {
+        LOGGER.info("The master of the sword is now {}.", sword.getLocker().getName());
+      }
+    } catch (InterruptedException e) {
+      LOGGER.error(e.getMessage());
+      Thread.currentThread().interrupt();
+    } finally {
+      service.shutdown();
+    }
+  }
+}

lockable-object/src/main/java/com/iluwatar/lockableobject/Lockable.java

@@ -0,0 +1,43 @@
+package com.iluwatar.lockableobject;
+
+import com.iluwatar.lockableobject.domain.Creature;
+
+/** This interface describes the methods to be supported by a lockable-object. */
+public interface Lockable {
+
+  /**
+   * Checks if the object is locked.
+   *
+   * @return true if it is locked.
+   */
+  boolean isLocked();
+
+  /**
+   * locks the object with the creature as the locker.
+   *
+   * @param creature as the locker.
+   * @return true if the object was locked successfully.
+   */
+  boolean lock(Creature creature);
+
+  /**
+   * Unlocks the object.
+   *
+   * @param creature as the locker.
+   */
+  void unlock(Creature creature);
+
+  /**
+   * Gets the locker.
+   *
+   * @return the Creature that holds the object. Returns null if no one is locking.
+   */
+  Creature getLocker();
+
+  /**
+   * Returns the name of the object.
+   *
+   * @return the name of the object.
+   */
+  String getName();
+}

lockable-object/src/main/java/com/iluwatar/lockableobject/LockingException.java

@@ -0,0 +1,14 @@
+package com.iluwatar.lockableobject;
+
+/**
+ * An exception regarding the locking process of a Lockable object.
+ */
+public class LockingException extends RuntimeException {
+
+  private static final long serialVersionUID = 8556381044865867037L;
+
+  public LockingException(String message) {
+    super(message);
+  }
+
+}

lockable-object/src/main/java/com/iluwatar/lockableobject/SwordOfAragorn.java

@@ -0,0 +1,66 @@
+package com.iluwatar.lockableobject;
+
+import com.iluwatar.lockableobject.domain.Creature;
+import lombok.NonNull;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * An implementation of a Lockable object. This is the the Sword of Aragorn and every creature wants
+ * to posses it!
+ */
+@Slf4j
+public class SwordOfAragorn implements Lockable {
+
+  private Creature locker;
+  private final Object synchronizer;
+  private static final String NAME = "The Sword of Aragorn";
+
+  public SwordOfAragorn() {
+    this.locker = null;
+    this.synchronizer = new Object();
+  }
+
+  @Override
+  public boolean isLocked() {
+    return this.locker != null;
+  }
+
+  @Override
+  public boolean lock(@NonNull Creature creature) {
+    synchronized (synchronizer) {
+      LOGGER.info("{} is now trying to acquire {}!", creature.getName(), this.getName());
+      if (!isLocked()) {
+        locker = creature;
+        return true;
+      } else {
+        if (!locker.getName().equals(creature.getName())) {
+          return false;
+        }
+      }
+    }
+    return false;
+  }
+
+  @Override
+  public void unlock(@NonNull Creature creature) {
+    synchronized (synchronizer) {
+      if (locker != null && locker.getName().equals(creature.getName())) {
+        locker = null;
+        LOGGER.info("{} is now free!", this.getName());
+      }
+      if (locker != null) {
+        throw new LockingException("You cannot unlock an object you are not the owner of.");
+      }
+    }
+  }
+
+  @Override
+  public Creature getLocker() {
+    return this.locker;
+  }
+
+  @Override
+  public String getName() {
+    return NAME;
+  }
+}

lockable-object/src/main/java/com/iluwatar/lockableobject/domain/Creature.java

@@ -0,0 +1,89 @@
+package com.iluwatar.lockableobject.domain;
+
+import com.iluwatar.lockableobject.Lockable;
+import java.util.HashSet;
+import java.util.Set;
+import lombok.Getter;
+import lombok.NonNull;
+import lombok.Setter;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * An abstract class of a creature that wanders across the wasteland. It can attack, get hit and
+ * acquire a Lockable object.
+ */
+@Getter
+@Setter
+@Slf4j
+public abstract class Creature {
+
+  private String name;
+  private CreatureType type;
+  private int health;
+  private int damage;
+  Set<Lockable> instruments;
+
+  protected Creature(@NonNull String name) {
+    this.name = name;
+    this.instruments = new HashSet<>();
+  }
+
+  /**
+   * Reaches for the Lockable and tried to hold it.
+   *
+   * @param lockable as the Lockable to lock.
+   * @return true of Lockable was locked by this creature.
+   */
+  public boolean acquire(@NonNull Lockable lockable) {
+    if (lockable.lock(this)) {
+      instruments.add(lockable);
+      return true;
+    }
+    return false;
+  }
+
+  /** Terminates the Creature and unlocks all of the Lockable that it posses. */
+  public synchronized void kill() {
+    LOGGER.info("{} {} has been slayed!", type, name);
+    for (Lockable lockable : instruments) {
+      lockable.unlock(this);
+    }
+    this.instruments.clear();
+  }
+
+  /**
+   * Attacks a foe.
+   *
+   * @param creature as the foe to be attacked.
+   */
+  public synchronized void attack(@NonNull Creature creature) {
+    creature.hit(getDamage());
+  }
+
+  /**
+   * When a creature gets hit it removed the amount of damage from the creature's life.
+   *
+   * @param damage as the damage that was taken.
+   */
+  public synchronized void hit(int damage) {
+    if (damage < 0) {
+      throw new IllegalArgumentException("Damage cannot be a negative number");
+    }
+    if (isAlive()) {
+      setHealth(getHealth() - damage);
+      if (!isAlive()) {
+        kill();
+      }
+    }
+  }
+
+  /**
+   * Checks if the creature is still alive.
+   *
+   * @return true of creature is alive.
+   */
+  public synchronized boolean isAlive() {
+    return getHealth() > 0;
+  }
+
+}

lockable-object/src/main/java/com/iluwatar/lockableobject/domain/CreatureStats.java

@@ -0,0 +1,21 @@
+package com.iluwatar.lockableobject.domain;
+
+/** Attribute constants of each Creature implementation. */
+public enum CreatureStats {
+  ELF_HEALTH(90),
+  ELF_DAMAGE(40),
+  ORC_HEALTH(70),
+  ORC_DAMAGE(50),
+  HUMAN_HEALTH(60),
+  HUMAN_DAMAGE(60);
+
+  int value;
+
+  private CreatureStats(int value) {
+    this.value = value;
+  }
+
+  public int getValue() {
+    return this.value;
+  }
+}

lockable-object/src/main/java/com/iluwatar/lockableobject/domain/CreatureType.java

@@ -0,0 +1,8 @@
+package com.iluwatar.lockableobject.domain;
+
+/** Constants of supported creatures. */
+public enum CreatureType {
+  ORC,
+  HUMAN,
+  ELF
+}

lockable-object/src/main/java/com/iluwatar/lockableobject/domain/Elf.java

@@ -0,0 +1,17 @@
+package com.iluwatar.lockableobject.domain;
+
+/** An Elf implementation of a Creature. */
+public class Elf extends Creature {
+
+  /**
+   * A constructor that initializes the attributes of an elf.
+   *
+   * @param name as the name of the creature.
+   */
+  public Elf(String name) {
+    super(name);
+    setType(CreatureType.ELF);
+    setDamage(CreatureStats.ELF_DAMAGE.getValue());
+    setHealth(CreatureStats.ELF_HEALTH.getValue());
+  }
+}

lockable-object/src/main/java/com/iluwatar/lockableobject/domain/Feind.java

@@ -0,0 +1,71 @@
+package com.iluwatar.lockableobject.domain;
+
+import com.iluwatar.lockableobject.Lockable;
+import java.security.SecureRandom;
+import lombok.NonNull;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/** A Feind is a creature that all it wants is to posses a Lockable object. */
+public class Feind implements Runnable {
+
+  private final Creature creature;
+  private final Lockable target;
+  private final SecureRandom random;
+  private static final Logger LOGGER = LoggerFactory.getLogger(Feind.class.getName());
+
+  /**
+   * public constructor.
+   *
+   * @param feind as the creature to lock to he lockable.
+   * @param target as the target object.
+   */
+  public Feind(@NonNull Creature feind, @NonNull Lockable target) {
+    this.creature = feind;
+    this.target = target;
+    this.random = new SecureRandom();
+  }
+
+  @Override
+  public void run() {
+    if (!creature.acquire(target)) {
+      try {
+        fightForTheSword(creature, target.getLocker(), target);
+      } catch (InterruptedException e) {
+        LOGGER.error(e.getMessage());
+        Thread.currentThread().interrupt();
+      }
+    } else {
+      LOGGER.info("{} has acquired the sword!", target.getLocker().getName());
+    }
+  }
+
+  /**
+   * Keeps on fighting until the Lockable is possessed.
+   *
+   * @param reacher as the source creature.
+   * @param holder as the foe.
+   * @param sword as the Lockable to posses.
+   * @throws InterruptedException in case of interruption.
+   */
+  private void fightForTheSword(Creature reacher, @NonNull Creature holder, Lockable sword)
+      throws InterruptedException {
+    LOGGER.info("A duel between {} and {} has been started!", reacher.getName(), holder.getName());
+    boolean randBool;
+    while (this.target.isLocked() && reacher.isAlive() && holder.isAlive()) {
+      randBool = random.nextBoolean();
+      if (randBool) {
+        reacher.attack(holder);
+      } else {
+        holder.attack(reacher);
+      }
+    }
+    if (reacher.isAlive()) {
+      if (!reacher.acquire(sword)) {
+        fightForTheSword(reacher, sword.getLocker(), sword);
+      } else {
+        LOGGER.info("{} has acquired the sword!", reacher.getName());
+      }
+    }
+  }
+}

lockable-object/src/main/java/com/iluwatar/lockableobject/domain/Human.java

@@ -0,0 +1,17 @@
+package com.iluwatar.lockableobject.domain;
+
+/** A human implementation of a Creature. */
+public class Human extends Creature {
+
+  /**
+   * A constructor that initializes the attributes of an human.
+   *
+   * @param name as the name of the creature.
+   */
+  public Human(String name) {
+    super(name);
+    setType(CreatureType.HUMAN);
+    setDamage(CreatureStats.HUMAN_DAMAGE.getValue());
+    setHealth(CreatureStats.HUMAN_HEALTH.getValue());
+  }
+}

lockable-object/src/main/java/com/iluwatar/lockableobject/domain/Orc.java

@@ -0,0 +1,16 @@
+package com.iluwatar.lockableobject.domain;
+
+/** A Orc implementation of a Creature. */
+public class Orc extends Creature {
+  /**
+   * A constructor that initializes the attributes of an orc.
+   *
+   * @param name as the name of the creature.
+   */
+  public Orc(String name) {
+    super(name);
+    setType(CreatureType.ORC);
+    setDamage(CreatureStats.ORC_DAMAGE.getValue());
+    setHealth(CreatureStats.ORC_HEALTH.getValue());
+  }
+}