ARTEMIS-4559 refactor HA docs & code/module naming

This commit does the following: - Updates HA docs including the chapter on network isolation (i.e. split brain). The network isolation chapter is now more about high-level explanation and the HA doc now has all the configuration parameters. - Changes references to "pluggable quorum voting" to "pluggable lock manager." The pluggable functionality really isn't about voting. Conceptually is much more like the functionality you'd get from a distributed lock so this naming is more clear. Both the docs and the code have been changed. - Reorganize lock manager modules as sub-modules. The API and RI modules are renamed, but that should be OK based on the "experimental" tag that's been on this feature up to this point. - Remove the "experimental" tag from the lock manager. These changes will not break folks using the standalone broker. However, they will break folks embedding the broker *if* they are using the artemis-quorum-ri or artemis-quorum-api modules or the o.a.a.a.c.c.h.DistributedPrimitiveManagerConfiguration class. There are no functional changes here. Renaming these modules is more a conceptual change to facilitate better documentation and increased adoption.
apache · Mar 15, 2024 · 5766225 · 5766225
1 parent a3cde08
commit 5766225
Show file tree

Hide file tree

Showing 110 changed files with 973 additions and 900 deletions.
diff --git a/artemis-bom/pom.xml b/artemis-bom/pom.xml
@@ -185,12 +185,12 @@
          </dependency>
          <dependency>
             <groupId>org.apache.activemq</groupId>
-            <artifactId>artemis-quorum-api</artifactId>
+            <artifactId>artemis-lockmanager-api</artifactId>
             <version>${project.version}</version>
          </dependency>
          <dependency>
             <groupId>org.apache.activemq</groupId>
-            <artifactId>artemis-quorum-ri</artifactId>
+            <artifactId>artemis-lockmanager-ri</artifactId>
             <version>${project.version}</version>
          </dependency>
          <dependency>

diff --git a/artemis-cli/pom.xml b/artemis-cli/pom.xml
@@ -60,7 +60,7 @@
       </dependency>
       <dependency>
          <groupId>org.apache.activemq</groupId>
-         <artifactId>artemis-quorum-api</artifactId>
+         <artifactId>artemis-lockmanager-api</artifactId>
       </dependency>
       <dependency>
          <groupId>org.apache.activemq</groupId>

diff --git a/...main/java/org/apache/activemq/artemis/cli/commands/activation/ActivationSequenceList.java b/...main/java/org/apache/activemq/artemis/cli/commands/activation/ActivationSequenceList.java
@@ -24,14 +24,14 @@
 import org.apache.activemq.artemis.cli.commands.tools.LockAbstract;
 import org.apache.activemq.artemis.core.config.Configuration;
 import org.apache.activemq.artemis.core.config.HAPolicyConfiguration;
-import org.apache.activemq.artemis.core.config.ha.DistributedPrimitiveManagerConfiguration;
+import org.apache.activemq.artemis.core.config.ha.DistributedLockManagerConfiguration;
 import org.apache.activemq.artemis.core.config.ha.ReplicationBackupPolicyConfiguration;
 import org.apache.activemq.artemis.core.config.ha.ReplicationPrimaryPolicyConfiguration;
 import org.apache.activemq.artemis.core.server.NodeManager;
 import org.apache.activemq.artemis.core.server.impl.FileLockNodeManager;
-import org.apache.activemq.artemis.quorum.DistributedLock;
-import org.apache.activemq.artemis.quorum.DistributedPrimitiveManager;
-import org.apache.activemq.artemis.quorum.MutableLong;
+import org.apache.activemq.artemis.lockmanager.DistributedLock;
+import org.apache.activemq.artemis.lockmanager.DistributedLockManager;
+import org.apache.activemq.artemis.lockmanager.MutableLong;
 import picocli.CommandLine.Command;
 import picocli.CommandLine.Option;
 
@@ -84,7 +84,7 @@ public static ListResult execute(final ActivationSequenceList command,
          throw new IllegalArgumentException("--node-id must be used just with --remote");
       }
       final HAPolicyConfiguration policyConfig = config.getHAPolicyConfiguration();
-      final DistributedPrimitiveManagerConfiguration managerConfiguration;
+      final DistributedLockManagerConfiguration managerConfiguration;
       String coordinationId = null;
       if (policyConfig instanceof ReplicationBackupPolicyConfiguration) {
          ReplicationBackupPolicyConfiguration backupPolicyConfig = (ReplicationBackupPolicyConfiguration) policyConfig;
@@ -135,7 +135,7 @@ public static ListResult execute(final ActivationSequenceList command,
          }
          Long coordinatedSequence = null;
          if (!local) {
-            try (DistributedPrimitiveManager manager = DistributedPrimitiveManager.newInstanceOf(
+            try (DistributedLockManager manager = DistributedLockManager.newInstanceOf(
                managerConfiguration.getClassName(), managerConfiguration.getProperties())) {
                if (!manager.start(MANAGER_START_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {
                   throw new IllegalStateException("distributed manager isn't started in " + MANAGER_START_TIMEOUT_SECONDS + " seconds");

diff --git a/.../main/java/org/apache/activemq/artemis/cli/commands/activation/ActivationSequenceSet.java b/.../main/java/org/apache/activemq/artemis/cli/commands/activation/ActivationSequenceSet.java
@@ -24,14 +24,14 @@
 import org.apache.activemq.artemis.cli.commands.tools.LockAbstract;
 import org.apache.activemq.artemis.core.config.Configuration;
 import org.apache.activemq.artemis.core.config.HAPolicyConfiguration;
-import org.apache.activemq.artemis.core.config.ha.DistributedPrimitiveManagerConfiguration;
+import org.apache.activemq.artemis.core.config.ha.DistributedLockManagerConfiguration;
 import org.apache.activemq.artemis.core.config.ha.ReplicationBackupPolicyConfiguration;
 import org.apache.activemq.artemis.core.config.ha.ReplicationPrimaryPolicyConfiguration;
 import org.apache.activemq.artemis.core.server.NodeManager;
 import org.apache.activemq.artemis.core.server.impl.FileLockNodeManager;
-import org.apache.activemq.artemis.quorum.DistributedLock;
-import org.apache.activemq.artemis.quorum.DistributedPrimitiveManager;
-import org.apache.activemq.artemis.quorum.MutableLong;
+import org.apache.activemq.artemis.lockmanager.DistributedLock;
+import org.apache.activemq.artemis.lockmanager.DistributedLockManager;
+import org.apache.activemq.artemis.lockmanager.MutableLong;
 import picocli.CommandLine.Command;
 import picocli.CommandLine.Option;
 
@@ -78,7 +78,7 @@ public static void execute(final ActivationSequenceSet command,
          throw new IllegalArgumentException("--to must be >= 0");
       }
       final HAPolicyConfiguration policyConfig = config.getHAPolicyConfiguration();
-      final DistributedPrimitiveManagerConfiguration managerConfiguration;
+      final DistributedLockManagerConfiguration managerConfiguration;
       String coordinationId = nodeId;
       if (policyConfig instanceof ReplicationBackupPolicyConfiguration) {
          ReplicationBackupPolicyConfiguration backupPolicyConfig = (ReplicationBackupPolicyConfiguration) policyConfig;
@@ -118,7 +118,7 @@ public static void execute(final ActivationSequenceSet command,
             }
          }
          if (!local) {
-            try (DistributedPrimitiveManager manager = DistributedPrimitiveManager.newInstanceOf(
+            try (DistributedLockManager manager = DistributedLockManager.newInstanceOf(
                managerConfiguration.getClassName(), managerConfiguration.getProperties())) {
                if (!manager.start(MANAGER_START_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {
                   throw new IllegalStateException("distributed manager isn't started in " + MANAGER_START_TIMEOUT_SECONDS + " seconds");

diff --git a/...nt/src/main/java/org/apache/activemq/artemis/api/config/ActiveMQDefaultConfiguration.java b/...nt/src/main/java/org/apache/activemq/artemis/api/config/ActiveMQDefaultConfiguration.java
@@ -659,7 +659,7 @@ public static String getDefaultHapolicyBackupStrategy() {
 
    public static final String DEFAULT_TEMPORARY_QUEUE_NAMESPACE = "";
 
-   private static final String DEFAULT_DISTRIBUTED_PRIMITIVE_MANAGER_CLASS_NAME = "org.apache.activemq.artemis.quorum.zookeeper.CuratorDistributedPrimitiveManager";
+   private static final String DEFAULT_DISTRIBUTED_PRIMITIVE_MANAGER_CLASS_NAME = "org.apache.activemq.artemis.lockmanager.zookeeper.CuratorDistributedLockManager";
 
    // Number of concurrent workers for a core bridge
    public static int DEFAULT_BRIDGE_CONCURRENCY = 1;
@@ -1832,7 +1832,7 @@ public static String getDefaultTemporaryQueueNamespace() {
       return DEFAULT_TEMPORARY_QUEUE_NAMESPACE;
    }
 
-   public static String getDefaultDistributedPrimitiveManagerClassName() {
+   public static String getDefaultDistributedLockManagerClassName() {
       return DEFAULT_DISTRIBUTED_PRIMITIVE_MANAGER_CLASS_NAME;
    }
 

diff --git a/artemis-distribution/pom.xml b/artemis-distribution/pom.xml
@@ -130,11 +130,11 @@
       <!-- quorum -->
       <dependency>
          <groupId>org.apache.activemq</groupId>
-         <artifactId>artemis-quorum-api</artifactId>
+         <artifactId>artemis-lockmanager-api</artifactId>
       </dependency>
       <dependency>
          <groupId>org.apache.activemq</groupId>
-         <artifactId>artemis-quorum-ri</artifactId>
+         <artifactId>artemis-lockmanager-ri</artifactId>
       </dependency>
 
       <!--TODO: no other modules seem to use this, is it equivalent to something else they do use ? -->

diff --git a/artemis-features/src/main/resources/features.xml b/artemis-features/src/main/resources/features.xml
@@ -80,7 +80,7 @@
 		<!--bundle dependency="true">mvn:io.micrometer/micrometer-core/${version.micrometer}</bundle-->
 
 		<bundle>mvn:org.apache.activemq/activemq-artemis-native/${activemq-artemis-native-version}</bundle>
-		<bundle>mvn:org.apache.activemq/artemis-quorum-api/${pom.version}</bundle>
+		<bundle>mvn:org.apache.activemq/artemis-lockmanager-api/${pom.version}</bundle>
 		<bundle>mvn:org.apache.activemq/artemis-server-osgi/${pom.version}</bundle>
 	</feature>
 

diff --git a/artemis-quorum-api/pom.xml → ...ckmanager/artemis-lockmanager-api/pom.xml b/artemis-quorum-api/pom.xml → ...ckmanager/artemis-lockmanager-api/pom.xml
@@ -19,13 +19,15 @@
 
    <parent>
       <groupId>org.apache.activemq</groupId>
-      <artifactId>artemis-pom</artifactId>
+      <artifactId>artemis-lockmanager</artifactId>
       <version>2.33.0-SNAPSHOT</version>
-      <relativePath>../artemis-pom/pom.xml</relativePath>
    </parent>
 
-   <artifactId>artemis-quorum-api</artifactId>
+   <artifactId>artemis-lockmanager-api</artifactId>
    <packaging>bundle</packaging>
-   <name>ActiveMQ Artemis Quorum API</name>
+   <name>ActiveMQ Artemis Lock Manager API</name>
 
+   <properties>
+      <activemq.basedir>${project.basedir}/../..</activemq.basedir>
+   </properties>
 </project>
diff --git a/...ivemq/artemis/quorum/DistributedLock.java → .../artemis/lockmanager/DistributedLock.java b/...ivemq/artemis/quorum/DistributedLock.java → .../artemis/lockmanager/DistributedLock.java
@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.activemq.artemis.quorum;
+package org.apache.activemq.artemis.lockmanager;
 
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;

diff --git a/...s/quorum/DistributedPrimitiveManager.java → ...s/lockmanager/DistributedLockManager.java b/...s/quorum/DistributedPrimitiveManager.java → ...s/lockmanager/DistributedLockManager.java
@@ -14,17 +14,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.activemq.artemis.quorum;
+package org.apache.activemq.artemis.lockmanager;
 
 import java.util.Map;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
-public interface DistributedPrimitiveManager extends AutoCloseable {
+public interface DistributedLockManager extends AutoCloseable {
 
-   static DistributedPrimitiveManager newInstanceOf(String className, Map<String, String> properties) throws Exception {
-      return (DistributedPrimitiveManager) Class.forName(className).getDeclaredConstructor(Map.class).newInstance(properties);
+   static DistributedLockManager newInstanceOf(String className, Map<String, String> properties) throws Exception {
+      return (DistributedLockManager) Class.forName(className).getDeclaredConstructor(Map.class).newInstance(properties);
    }
 
    @FunctionalInterface

diff --git a/.../activemq/artemis/quorum/MutableLong.java → ...vemq/artemis/lockmanager/MutableLong.java b/.../activemq/artemis/quorum/MutableLong.java → ...vemq/artemis/lockmanager/MutableLong.java
@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.activemq.artemis.quorum;
+package org.apache.activemq.artemis.lockmanager;
 
 public interface MutableLong extends AutoCloseable {
 

diff --git a/...mis/quorum/UnavailableStateException.java → ...ockmanager/UnavailableStateException.java b/...mis/quorum/UnavailableStateException.java → ...ockmanager/UnavailableStateException.java
@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.activemq.artemis.quorum;
+package org.apache.activemq.artemis.lockmanager;
 
 public final class UnavailableStateException extends Exception {
 

diff --git a/artemis-quorum-ri/pom.xml → ...ockmanager/artemis-lockmanager-ri/pom.xml b/artemis-quorum-ri/pom.xml → ...ockmanager/artemis-lockmanager-ri/pom.xml
@@ -19,14 +19,17 @@
 
    <parent>
       <groupId>org.apache.activemq</groupId>
-      <artifactId>artemis-pom</artifactId>
+      <artifactId>artemis-lockmanager</artifactId>
       <version>2.33.0-SNAPSHOT</version>
-      <relativePath>../artemis-pom/pom.xml</relativePath>
    </parent>
 
-   <artifactId>artemis-quorum-ri</artifactId>
+   <artifactId>artemis-lockmanager-ri</artifactId>
    <packaging>jar</packaging>
-   <name>ActiveMQ Artemis Quorum RI</name>
+   <name>ActiveMQ Artemis Lock Manager RI</name>
+
+   <properties>
+      <activemq.basedir>${project.basedir}/../..</activemq.basedir>
+   </properties>
 
    <dependencies>
       <dependency>
@@ -86,7 +89,7 @@
       </dependency>
       <dependency>
          <groupId>org.apache.activemq</groupId>
-         <artifactId>artemis-quorum-api</artifactId>
+         <artifactId>artemis-lockmanager-api</artifactId>
       </dependency>
       <!-- logging -->
       <dependency>

diff --git a/...uorum/file/FileBasedPrimitiveManager.java → ...ockmanager/file/FileBasedLockManager.java b/...uorum/file/FileBasedPrimitiveManager.java → ...ockmanager/file/FileBasedLockManager.java
@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.activemq.artemis.quorum.file;
+package org.apache.activemq.artemis.lockmanager.file;
 
 import java.io.File;
 import java.io.IOException;
@@ -26,27 +26,27 @@
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
 
-import org.apache.activemq.artemis.quorum.DistributedLock;
-import org.apache.activemq.artemis.quorum.DistributedPrimitiveManager;
-import org.apache.activemq.artemis.quorum.MutableLong;
-import org.apache.activemq.artemis.quorum.UnavailableStateException;
+import org.apache.activemq.artemis.lockmanager.DistributedLock;
+import org.apache.activemq.artemis.lockmanager.DistributedLockManager;
+import org.apache.activemq.artemis.lockmanager.MutableLong;
+import org.apache.activemq.artemis.lockmanager.UnavailableStateException;
 
 /**
  * This is an implementation suitable to be used just on unit tests and it won't attempt
  * to manage nor purge existing stale locks files. It's part of the tests life-cycle to properly
  * set-up and tear-down the environment.
  */
-public class FileBasedPrimitiveManager implements DistributedPrimitiveManager {
+public class FileBasedLockManager implements DistributedLockManager {
 
    private final File locksFolder;
    private final Map<String, FileDistributedLock> locks;
    private boolean started;
 
-   public FileBasedPrimitiveManager(Map<String, String> args) {
+   public FileBasedLockManager(Map<String, String> args) {
       this(new File(args.get("locks-folder")));
    }
 
-   public FileBasedPrimitiveManager(File locksFolder) {
+   public FileBasedLockManager(File locksFolder) {
       Objects.requireNonNull(locksFolder);
       if (!locksFolder.exists()) {
          throw new IllegalStateException(locksFolder + " is supposed to already exists");

diff --git a/...emis/quorum/file/FileDistributedLock.java → ...lockmanager/file/FileDistributedLock.java b/...emis/quorum/file/FileDistributedLock.java → ...lockmanager/file/FileDistributedLock.java
@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.activemq.artemis.quorum.file;
+package org.apache.activemq.artemis.lockmanager.file;
 
 import java.io.File;
 import java.io.IOException;
@@ -24,7 +24,7 @@
 import java.nio.file.StandardOpenOption;
 import java.util.function.Consumer;
 
-import org.apache.activemq.artemis.quorum.DistributedLock;
+import org.apache.activemq.artemis.lockmanager.DistributedLock;
 
 final class FileDistributedLock implements DistributedLock {
 

diff --git a/...rum/zookeeper/CuratorDistributedLock.java → ...ger/zookeeper/CuratorDistributedLock.java b/...rum/zookeeper/CuratorDistributedLock.java → ...ger/zookeeper/CuratorDistributedLock.java
@@ -14,17 +14,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.activemq.artemis.quorum.zookeeper;
+package org.apache.activemq.artemis.lockmanager.zookeeper;
 
 import java.nio.charset.StandardCharsets;
 import java.util.Arrays;
 import java.util.UUID;
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.TimeUnit;
 
-import org.apache.activemq.artemis.quorum.DistributedLock;
-import org.apache.activemq.artemis.quorum.UnavailableStateException;
-import org.apache.activemq.artemis.quorum.zookeeper.CuratorDistributedPrimitiveManager.PrimitiveId;
+import org.apache.activemq.artemis.lockmanager.DistributedLock;
+import org.apache.activemq.artemis.lockmanager.UnavailableStateException;
+import org.apache.activemq.artemis.lockmanager.zookeeper.CuratorDistributedLockManager.PrimitiveId;
 import org.apache.curator.framework.recipes.locks.InterProcessSemaphoreV2;
 import org.apache.curator.framework.recipes.locks.Lease;
 
@@ -35,7 +35,7 @@ final class CuratorDistributedLock extends CuratorDistributedPrimitive implement
    private Lease lease;
    private byte[] leaseVersion;
 
-   CuratorDistributedLock(PrimitiveId id, CuratorDistributedPrimitiveManager manager, InterProcessSemaphoreV2 ipcSem) {
+   CuratorDistributedLock(PrimitiveId id, CuratorDistributedLockManager manager, InterProcessSemaphoreV2 ipcSem) {
       super(id, manager);
       this.ipcSem = ipcSem;
       this.listeners = new CopyOnWriteArrayList<>();

diff --git a/...r/CuratorDistributedPrimitiveManager.java → ...keeper/CuratorDistributedLockManager.java b/...r/CuratorDistributedPrimitiveManager.java → ...keeper/CuratorDistributedLockManager.java
@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.activemq.artemis.quorum.zookeeper;
+package org.apache.activemq.artemis.lockmanager.zookeeper;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -27,9 +27,9 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
-import org.apache.activemq.artemis.quorum.DistributedLock;
-import org.apache.activemq.artemis.quorum.DistributedPrimitiveManager;
-import org.apache.activemq.artemis.quorum.MutableLong;
+import org.apache.activemq.artemis.lockmanager.DistributedLock;
+import org.apache.activemq.artemis.lockmanager.DistributedLockManager;
+import org.apache.activemq.artemis.lockmanager.MutableLong;
 import org.apache.curator.framework.CuratorFramework;
 import org.apache.curator.framework.CuratorFrameworkFactory;
 import org.apache.curator.framework.recipes.atomic.DistributedAtomicLong;
@@ -43,7 +43,7 @@
 import static java.util.Objects.requireNonNull;
 import static java.util.stream.Collectors.joining;
 
-public class CuratorDistributedPrimitiveManager implements DistributedPrimitiveManager, ConnectionStateListener {
+public class CuratorDistributedLockManager implements DistributedLockManager, ConnectionStateListener {
 
    enum PrimitiveType {
       lock, mutableLong;
@@ -154,11 +154,11 @@ private static void validateParameter(String parameterName) {
       }
    }
 
-   public CuratorDistributedPrimitiveManager(Map<String, String> config) {
+   public CuratorDistributedLockManager(Map<String, String> config) {
       this(validateParameters(config), true);
    }
 
-   private CuratorDistributedPrimitiveManager(Map<String, String> config, boolean ignore) {
+   private CuratorDistributedLockManager(Map<String, String> config, boolean ignore) {
       this(config.get(CONNECT_STRING_PARAM),
            config.get(NAMESPACE_PARAM),
            Integer.parseInt(config.getOrDefault(SESSION_MS_PARAM, DEFAULT_SESSION_TIMEOUT_MS)),
@@ -168,13 +168,13 @@ private CuratorDistributedPrimitiveManager(Map<String, String> config, boolean i
            Integer.parseInt(config.getOrDefault(RETRIES_MS_PARAM, DEFAULT_RETRIES_MS)));
    }
 
-   private CuratorDistributedPrimitiveManager(String connectString,
-                                              String namespace,
-                                              int sessionMs,
-                                              int sessionPercent,
-                                              int connectionMs,
-                                              int retries,
-                                              int retriesMs) {
+   private CuratorDistributedLockManager(String connectString,
+                                         String namespace,
+                                         int sessionMs,
+                                         int sessionPercent,
+                                         int connectionMs,
+                                         int retries,
+                                         int retriesMs) {
       curatorBuilder = CuratorFrameworkFactory.builder()
          .connectString(connectString)
          .namespace(namespace)