QPID-4498: HA module should only initialize if requested

This commit provides better control over loading the HA module. In particular it
is not loaded if no ha options are set. This will prevent clashes with the old
cluster plugin in configurations where the HA module is not explicitly used.
HA documentation has been updated to state that HA and old cluster cannot be used
together.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@1419850 13f79535-47bb-0310-9956-ffa450edef68

4 files changed, 54 insertions, 7 deletions

diff --git a/cpp/src/qpid/ha/HaPlugin.cpp b/cpp/src/qpid/ha/HaPlugin.cpp
index 3d77a4cbd1..cba9c0bb26 100644
--- a/cpp/src/qpid/ha/HaPlugin.cpp
+++ b/cpp/src/qpid/ha/HaPlugin.cpp
@@ -33,6 +33,8 @@ struct Options : public qpid::Options {
         addOptions()
             ("ha-cluster", optValue(settings.cluster, "yes|no"),
              "Join a HA active/passive cluster.")
+            ("ha-queue-replication", optValue(settings.queueReplication, "yes|no"),
+             "Enable replication of specific queues without joining a cluster")
             ("ha-brokers-url", optValue(settings.brokerUrl,"URL"),
              "URL with address of each broker in the cluster.")
             ("ha-public-url", optValue(settings.clientUrl,"URL"),
@@ -68,7 +70,7 @@ struct HaPlugin : public Plugin {
 
     void earlyInitialize(Plugin::Target& target) {
         broker::Broker* broker = dynamic_cast<broker::Broker*>(&target);
-        if (broker) {
+        if (broker && (settings.cluster || settings.queueReplication)) {
             if (!broker->getManagementAgent()) {
                 QPID_LOG(info, "HA plugin disabled because management is disabled");
                 if (settings.cluster)
diff --git a/cpp/src/qpid/ha/Settings.h b/cpp/src/qpid/ha/Settings.h
index 1be068063a..d3dcb96dad 100644
--- a/cpp/src/qpid/ha/Settings.h
+++ b/cpp/src/qpid/ha/Settings.h
@@ -35,11 +35,13 @@ namespace ha {
 class Settings
 {
   public:
-    Settings() : cluster(false), replicateDefault(NONE), backupTimeout(5),
+    Settings() : cluster(false), queueReplication(false),
+                 replicateDefault(NONE), backupTimeout(5),
                  flowMessages(100), flowBytes(0)
     {}
 
     bool cluster;               // True if we are a cluster member.
+    bool queueReplication;      // True if enabled.
     std::string clientUrl;
     std::string brokerUrl;
     Enum<ReplicateLevel> replicateDefault;
diff --git a/cpp/src/tests/ha_tests.py b/cpp/src/tests/ha_tests.py
index bc5566ae63..968ffa8b4a 100755
--- a/cpp/src/tests/ha_tests.py
+++ b/cpp/src/tests/ha_tests.py
@@ -279,11 +279,13 @@ class ReplicationTests(HaBrokerTest):
         """Test replication of individual queues outside of cluster mode"""
         l = LogLevel(ERROR) # Hide expected WARNING log messages from failover.
         try:
-            primary = HaBroker(self, name="primary", ha_cluster=False)
+            primary = HaBroker(self, name="primary", ha_cluster=False,
+                               args=["--ha-queue-replication=yes"]);
             pc = primary.connect()
             ps = pc.session().sender("q;{create:always}")
             pr = pc.session().receiver("q;{create:always}")
-            backup = HaBroker(self, name="backup", ha_cluster=False)
+            backup = HaBroker(self, name="backup", ha_cluster=False,
+                              args=["--ha-queue-replication=yes"])
             br = backup.connect().session().receiver("q;{create:always}")
 
             # Set up replication with qpid-ha
@@ -304,7 +306,8 @@ class ReplicationTests(HaBrokerTest):
         finally: l.restore()
 
     def test_queue_replica_failover(self):
-        """Test individual queue replication from a cluster to a standalone backup broker, verify it fails over."""
+        """Test individual queue replication from a cluster to a standalone
+        backup broker, verify it fails over."""
         l = LogLevel(ERROR) # Hide expected WARNING log messages from failover.
         try:
             cluster = HaCluster(self, 2)
@@ -312,7 +315,8 @@ class ReplicationTests(HaBrokerTest):
             pc = cluster.connect(0)
             ps = pc.session().sender("q;{create:always}")
             pr = pc.session().receiver("q;{create:always}")
-            backup = HaBroker(self, name="backup", ha_cluster=False)
+            backup = HaBroker(self, name="backup", ha_cluster=False,
+                              args=["--ha-queue-replication=yes"])
             br = backup.connect().session().receiver("q;{create:always}")
             backup.replicate(cluster.url, "q")
             ps.send("a")
diff --git a/doc/book/src/cpp-broker/Active-Passive-Cluster.xml b/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
index 65ce108aef..be5cb14a61 100644
--- a/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
+++ b/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
@@ -173,6 +173,13 @@ under the License.
 	  </listitem>
 	</itemizedlist>
       </para>
+      <para>
+	You should not enable the old and new cluster modules at the same time
+	in a broker, as they may interfere with each other. In other words you
+	should not set <literal>cluster-name</literal> at the same time as
+	either <literal>ha-cluster</literal> or
+	<literal>ha-queue-replication</literal>
+      </para>
     </section>
     <section>
       <title>Limitations</title>
@@ -254,6 +261,14 @@ under the License.
 	  </row>
 	  <row>
 	    <entry>
+	      <literal>ha-queue-replication <replaceable>yes|no</replaceable></literal>
+	    </entry>
+	    <entry>
+	      Enable replication of specific queues without joining a cluster, see <xref linkend="ha-queue-replication"/>.
+	    </entry>
+	  </row>
+	  <row>
+	    <entry>
 	      <literal>ha-brokers-url <replaceable>URL</replaceable></literal>
 	    </entry>
 	    <entry>
@@ -548,7 +563,7 @@ NOTE: fencing is not shown, you must configure fencing appropriately for your cl
   </section>
 
   <section id="ha-creating-replicated">
-    <title>Creating replicated queues and exchanges</title>
+    <title>Controlling replication of queues and exchanges</title>
     <para>
       By default, queues and exchanges are not replicated automatically. You can change
       the default behavior by setting the <literal>ha-replicate</literal> configuration
@@ -849,6 +864,30 @@ NOTE: fencing is not shown, you must configure fencing appropriately for your cl
       or to simulate a cluster on a single node. For deployment, a resource manager is required.
     </para>
   </section>
+  <section id="ha-queue-replication">
+    <title>Replicating specific queues</title>
+    <para>
+      In addition to the automatic replication performed in a cluster, you can
+      set up replication for specific queues between arbitrary brokers, even if
+      the brokers are not members of a cluster. The command:
+    </para>
+    <programlisting>
+      qpid-ha replicate <replaceable>QUEUE</replaceable> <replaceable>REMOTE-BROKER</replaceable>
+    </programlisting>
+    <para>
+    sets up replication of <replaceable>QUEUE</replaceable> on <replaceable>REMOTE-BROKER</replaceable> to <replaceable>QUEUE</replaceable> on the current broker.
+    </para>
+    <para>
+      Set the configuration option
+      <literal>ha-queue-replication=yes</literal> on both brokers to enable this
+      feature on non-cluster brokers. It is automatically enabled for brokers
+      that are part of a cluster.
+    </para>
+    <para>
+      Note that this feature does not provide automatic fail-over, for that you
+      need to run a cluster.
+    </para>
+  </section>
 </section>
 
 <!-- LocalWords:  scalability rgmanager multicast RGManager mailto LVQ qpidd IP dequeued Transactional username