[ARTEMIS-1030] document url escaping of the virtualTopicConsumerWildcards value

artemis-server/src/test/java/org/apache/activemq/artemis/uri/AcceptorParserTest.java

@@ -35,4 +35,15 @@ public class AcceptorParserTest {
          Assert.assertTrue(config.getExtraParams().get("banana").equals("x"));
       }
    }
+
+   @Test
+   public void testAcceptorWithQueryParamEscapes() throws Exception {
+      List<TransportConfiguration> configs = ConfigurationUtils.parseAcceptorURI("test", "tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;virtualTopicConsumerWildcards=Consumer.*.%3E%3B2");
+
+      for (TransportConfiguration config : configs) {
+         System.out.println("config:" + config);
+         System.out.println(config.getExtraParams().get("virtualTopicConsumerWildcards"));
+         Assert.assertTrue(config.getExtraParams().get("virtualTopicConsumerWildcards").equals("Consumer.*.>;2"));
+      }
+   }
 }

docs/migration-guide/en/VirtualTopics.md

@@ -39,13 +39,15 @@ would be replaced with an Artemis FQQN comprised of the address and queue.
 
 This does require modification to the destination name used by consumers which is not ideal.
 If OpenWire clients cannot be modified, Artemis supports a virtual topic wildcard filter
-mechanism on the openwire protocol handler that will automatically convert the consumer destination into the
+mechanism on the OpenWire protocol handler that will automatically convert the consumer destination into the
 corresponding FQQN.
 The format is a comma separated list of strings pairs, delimited with a ';'. Each pair identifies a filter to match
 the virtual topic consumer destination and an int that specifies the number of path matches that terminate the consumer
 queue identity.
 
-E.g: For the default 5.x virtual topic consumer prefix of ```Consumer.*.``` the url parameter ```virtualTopicConsumerWildcards``` should be: ```Consumer.*.>;2```.
+E.g: For the default 5.x virtual topic consumer prefix of ```Consumer.*.``` the parameter ```virtualTopicConsumerWildcards``` should be: ```Consumer.*.>;2```.
+However, there is a caveat because this value needs to be a encoded in a uri for the xml configuration. Any unsafe url characters
+, in this case: ```> ;``` need to be escaped with their hex code point representation; leading to a value of ```Consumer.*.%3E%3B2```. 
 In this way a consumer destination of ```Consumer.A.VirtualTopic.Orders``` will be transformed into a FQQN of
 ```VirtualTopic.Orders::Consumer.A```. 
 

docs/user-manual/en/protocols-interoperability.md

@@ -206,7 +206,7 @@ The two parameters are configured on openwire acceptors, via URLs or API. For ex
 
 ### Virtual Topic Consumer Destination Translation
 
-For existing Openwire consumers of virtual topic destinations it is possible to configure a mapping function
+For existing OpenWire consumers of virtual topic destinations it is possible to configure a mapping function
 that will translate the virtual topic consumer destination into a FQQN address. This address then represents
 the consumer as a multicast binding to an address representing the virtual topic. 
 
@@ -215,9 +215,11 @@ The first is the 5.x style destination filter that identifies the destination as
 The second identifies the number of ```paths``` that identify the consumer queue such that it can be parsed from the
 destination.
 For example, the default 5.x virtual topic with consumer prefix of ```Consumer.*.```, would require a
-```virtualTopicConsumerWildcards``` filter of:
+```virtualTopicConsumerWildcards``` filter of ```Consumer.*.>;2```. As a url parameter this transforms to ```Consumer.*.%3E%3B2``` when
+the url significant characters ```>;``` are escaped with their hex code points. 
+In an acceptor url it would be:
 
-     <acceptor name="artemis">tcp://127.0.0.1:61616?protocols=OPENWIRE;virtualTopicConsumerWildcards=Consumer.*.>;2</acceptor>
+     <acceptor name="artemis">tcp://127.0.0.1:61616?protocols=OPENWIRE;virtualTopicConsumerWildcards=Consumer.*.%3E%3B2</acceptor>
 
 This will translate ```Consumer.A.VirtualTopic.Orders``` into a FQQN of ```VirtualTopic.Orders::Consumer.A``` using the
 int component ```2``` of the configuration to identify the consumer queue as the first two paths of the destination.