Leader Election Pattern (#923)

* Fix issue #761: ThreadSafeDoubleCheckLocking.java: Instantiating by Reflection call will be successful if you do that firstly

* Create leader election module

* Create Interface of Instance and MessageManager

* Create implementations with token ring algorithm

* Change package structure.
Create basic message system.

* Implement heartbeat and heartbeat invoking message system

* Implement election message handler

* Add leader message handler

* Add main entry point

* Add comments

* Update README.md

* Fix checkstyle issue

* Add Unit Tests

* Add Unit Tests

* Add bully leader selection

* Change System.out to log print.
Add MIT license in each file.

* Add More java doc comments

* Add unit test

* Add unit tests

leader-election/README.md

@@ -0,0 +1,31 @@
+---
+layout: pattern
+title: Leader Election
+folder: leader-election
+permalink: /patterns/leader-election/
+categories: Other
+tags:
+ - Java
+ - Difficulty-Beginner
+---
+
+## Intent
+Leader Election pattern is commonly used in cloud system design. It can help to ensure that task instances selec the leader instance correctly and do not conflict with each other, cause contention for shared resources, or inadvertently interfere with the work that other task instances are performing.
+
+## Applicability
+Use this pattern when
+
+* the tasks in a distributed application, such as a cloud-hosted solution, require careful coordination and there is no natural leader.
+
+Do not use this pattern when
+
+* there is a natural leader or dedicated process that can always act as the leader. For example, it may be possible to implement a singleton process that coordinates the task instances. If this process fails or becomes unhealthy, the system can shut it down and restart it.
+* the coordination between tasks can be easily achieved by using a more lightweight mechanism. For example, if several task instances simply require coordinated access to a shared resource, a preferable solution might be to use optimistic or pessimistic locking to control access to that resource.
+
+## Real world examples
+
+* [Raft Leader Election](https://github.com/ronenhamias/raft-leader-election)
+
+## Credits
+
+* [ Cloud Design Patterns: Prescriptive Architecture Guidance for Cloud Applications](https://docs.microsoft.com/en-us/previous-versions/msp-n-p/dn568104(v=pandp.10))

leader-election/pom.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    The MIT License
+    Copyright (c) 2014-2016 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 THFE 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.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <artifactId>java-design-patterns</artifactId>
+        <groupId>com.iluwatar</groupId>
+        <version>1.22.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>leader-election</artifactId>
+    <dependencies>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

leader-election/src/main/java/com/iluwatar/leaderelection/AbstractInstance.java

@@ -0,0 +1,148 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 Ilkka Seppälä
+ * <p>
+ * 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:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * <p>
+ * 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.leaderelection;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.Queue;
+import java.util.concurrent.ConcurrentLinkedQueue;
+
+/**
+ * Abstract class of all the instance implementation classes.
+ */
+public abstract class AbstractInstance implements Instance, Runnable {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(AbstractInstance.class);
+
+  protected static final int HEARTBEAT_INTERVAL = 5000;
+
+  protected MessageManager messageManager;
+  protected Queue<Message> messageQueue;
+  protected final int localId;
+  protected int leaderId;
+  protected boolean alive;
+
+  /**
+   * Constructor of BullyInstance.
+   */
+  public AbstractInstance(MessageManager messageManager, int localId, int leaderId) {
+    this.messageManager = messageManager;
+    this.messageQueue = new ConcurrentLinkedQueue<>();
+    this.localId = localId;
+    this.leaderId = leaderId;
+    this.alive = true;
+  }
+
+  /**
+   * The instance will execute the message in its message queue periodically once it is alive.
+   */
+  @Override
+  public void run() {
+    while (true) {
+      if (!this.messageQueue.isEmpty()) {
+        this.processMessage(this.messageQueue.remove());
+      }
+    }
+  }
+
+  /**
+   * Once messages are sent to the certain instance, it will firstly be added to the queue and wait to be executed.
+   * @param message Message sent by other instances
+   */
+  @Override
+  public void onMessage(Message message) {
+    messageQueue.offer(message);
+  }
+
+  /**
+   * Check if the instance is alive or not.
+   * @return {@code true} if the instance is alive.
+   */
+  @Override
+  public boolean isAlive() {
+    return alive;
+  }
+
+  /**
+   * Set the health status of the certain instance.
+   * @param alive {@code true} for alive.
+   */
+  @Override
+  public void setAlive(boolean alive) {
+    this.alive = alive;
+  }
+
+  /**
+   * Process the message according to its type.
+   * @param message Message polled from queue.
+   */
+  private void processMessage(Message message) {
+    switch (message.getType()) {
+      case ELECTION:
+        LOGGER.info("Instance " + localId + " - Election Message handling...");
+        handleElectionMessage(message);
+        break;
+      case LEADER:
+        LOGGER.info("Instance " + localId + " - Leader Message handling...");
+        handleLeaderMessage(message);
+        break;
+      case HEARTBEAT:
+        LOGGER.info("Instance " + localId + " - Heartbeat Message handling...");
+        handleHeartbeatMessage(message);
+        break;
+      case ELECTION_INVOKE:
+        LOGGER.info("Instance " + localId + " - Election Invoke Message handling...");
+        handleElectionInvokeMessage();
+        break;
+      case LEADER_INVOKE:
+        LOGGER.info("Instance " + localId + " - Leader Invoke Message handling...");
+        handleLeaderInvokeMessage();
+        break;
+      case HEARTBEAT_INVOKE:
+        LOGGER.info("Instance " + localId + " - Heartbeat Invoke Message handling...");
+        handleHeartbeatInvokeMessage();
+        break;
+      default:
+        break;
+    }
+  }
+
+  /**
+   * Abstract methods to handle different types of message. These methods need to be implemented in concrete instance
+   * class to implement corresponding leader-selection pattern.
+   */
+  protected abstract void handleElectionMessage(Message message);
+
+  protected abstract void handleElectionInvokeMessage();
+
+  protected abstract void handleLeaderMessage(Message message);
+
+  protected abstract void handleLeaderInvokeMessage();
+
+  protected abstract void handleHeartbeatMessage(Message message);
+
+  protected abstract void handleHeartbeatInvokeMessage();
+
+}

leader-election/src/main/java/com/iluwatar/leaderelection/AbstractMessageManager.java

@@ -0,0 +1,73 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 Ilkka Seppälä
+ * <p>
+ * 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:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * <p>
+ * 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.leaderelection;
+
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+/**
+ * Abstract class of all the message manager classes.
+ */
+public abstract class AbstractMessageManager implements MessageManager {
+
+  /**
+   * Contain all the instances in the system. Key is its ID, and value is the instance itself.
+   */
+  protected Map<Integer, Instance> instanceMap;
+
+  /**
+   * Construtor of AbstractMessageManager
+   */
+  public AbstractMessageManager(Map<Integer, Instance> instanceMap) {
+    this.instanceMap = instanceMap;
+  }
+
+  /**
+   * Find the next instance with smallest ID.
+   * @return The next instance.
+   */
+  protected Instance findNextInstance(int currentId) {
+    Instance result = null;
+    List<Integer> candidateList = instanceMap.keySet()
+          .stream()
+          .filter((i) -> i > currentId && instanceMap.get(i).isAlive())
+          .sorted()
+          .collect(Collectors.toList());
+    if (candidateList.isEmpty()) {
+      int index = instanceMap.keySet()
+          .stream()
+          .filter((i) -> instanceMap.get(i).isAlive())
+          .sorted()
+          .collect(Collectors.toList())
+          .get(0);
+      result = instanceMap.get(index);
+    } else {
+      int index = candidateList.get(0);
+      result = instanceMap.get(index);
+    }
+    return result;
+  }
+
+}

leader-election/src/main/java/com/iluwatar/leaderelection/Instance.java

@@ -0,0 +1,49 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 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.leaderelection;
+
+/**
+ *  Instance interface
+ */
+public interface Instance {
+
+  /**
+   * Check if the instance is alive or not.
+   * @return {@code true} if the instance is alive.
+   */
+  boolean isAlive();
+
+  /**
+   * Set the health status of the certain instance.
+   * @param alive {@code true} for alive.
+   */
+  void setAlive(boolean alive);
+
+  /**
+   * Consume messages from other instances.
+   * @param message Message sent by other instances
+   */
+  void onMessage(Message message);
+
+}