Merge pull request #410 from djadobe16/AC-15629

Adobe Development Doc - Message Queues - ActiveMq (Artemis) updates

Author: jeff-matthews

src/pages/development/components/message-queues/async-configuration.md

@@ -46,28 +46,36 @@ The `queue_publisher.xml` file is generated by the `\Magento\WebapiAsync\Code\Ge
 
 The sort order is set to 0 and allows developers to change some aspects of the generated configuration in configuration readers such as `queue_publisher.xml` and `env.php`.
 
-`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of all REST API routes which can be executed asynchronously. Then it defines the connection name as `amqp` and the exchange as `magento` for each generated topic name.
+`\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of all REST API routes which can be executed asynchronously. Then it defines the connection name as `amqp` (or `stomp` for ActiveMQ Artemis) and the exchange as `magento` for each generated topic name.
 
 ## queue_consumer.xml
 
 The asynchronous/bulk API has one defined consumer which processes all asynchronous/bulk APIs messages.
 
 ```xml
-<consumer name="async.operations.all" queue="async.operations.all" connection="amqp"
+<consumer name="async.operations.all" queue="async.operations.all"
               consumerInstance="Magento\AsynchronousOperations\Model\MassConsumer"/>
 ```
 
+The connection type (AMQP or STOMP) is determined automatically based on your `env.php` configuration.
+
 ### queue_topology.xml
 
 The message queue topology configuration links all auto-generated topic names with prefix `async.` to the `magento` exchange and defines the queue named `async.operations.all` as the destination for all messages.
 
 ```xml
-<exchange name="magento" connection="amqp">
+<exchange name="magento">
     <binding id="async.operations.all" topic="async.#" destination="async.operations.all"/>
 </exchange>
 ```
 
+The connection type is automatically determined from your `env.php` configuration.
+
+<InlineAlert variant="info" slots="text"/>
+
+Message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP or STOMP is configured in deployment configuration of the queue, the respective connection is used. Otherwise, db connection is used.
+As a result, if AMQP or STOMP is configured in deployment configuration of the queue, connection declaration can be omitted in [message queue configuration files](./configuration.md): `queue_customer.xml`, `queue_publisher.xml`, `queue_topology.xml`.
+
 <InlineAlert variant="info" slots="text"/>
 
-Message queues connection is defined dynamically based on deployment configuration in `env.php`. If AMQP is configured in deployment configuration of the queue, AMQP connection is used. Otherwise, db connection is used.
-As a result, if AMQP is configured in deployment configuration of the queue, connection declaration can be omitted in [message queue configuration files](./configuration.md): `queue_customer.xml`, `queue_publisher.xml`, `queue_topology.xml`.
+ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.6 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers.

src/pages/development/components/message-queues/bulk-operations-example.md

@@ -319,35 +319,55 @@ The `queue_consumer.xml` file defines the relationship between a queue and its c
 
 ```xml
 <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/consumer.xsd">
-    <consumer name="<consumer_name>" queue="<queue_name>" connection="amqp" consumerInstance="Magento\Framework\MessageQueue\Consumer" handler="<Consumer_Class>::<Consumer_method>"/>
+    <consumer name="<consumer_name>" queue="<queue_name>" consumerInstance="Magento\Framework\MessageQueue\Consumer" handler="<Consumer_Class>::<Consumer_method>"/>
 </config>
 ```
 
+The connection type (AMQP or STOMP) is determined automatically based on your `env.php` configuration.
+
 ### Create `queue_publisher.xml`
 
 The `queue_publisher.xml` file defines the exchange where a topic is published. Create this file with the following contents:
 
+**For RabbitMQ (AMQP):**
+
 ```xml
 <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/publisher.xsd">
     <publisher topic="<topic_name>">
-        <connection name="amqp" exchange="<exchange>" />
+        <connection exchange="<exchange>" />
     </publisher>
 </config>
 ```
 
+**For ActiveMQ Artemis (STOMP):**
+
+```xml
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/publisher.xsd">
+    <publisher topic="<topic_name>" queue="<queue_name>" />
+</config>
+```
+
+**Note**: For ActiveMQ Artemis, the `<connection>` element is not required as the connection type is determined from `env.php`. When the topic name and queue name are different, you must specify the `queue` attribute in the `<publisher>` element.
+
 ### Create `queue_topology.xml`
 
 The `queue_topology.xml` file defines the message routing rules and declares queues and exchanges. Create this file with the following contents:
 
 ```xml
 <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/topology.xsd">
-    <exchange name="magento" type="topic" connection="amqp">
+    <exchange name="magento" type="topic">
         <binding id="defaultBinding" topic="" destinationType="queue" destination="<queue_name>"/>
     </exchange>
 </config>
 ```
 
+The connection type is automatically determined from your `env.php` configuration.
+
+<InlineAlert variant="info" slots="text"/>
+
+Message queue connections are defined dynamically, based on the deployment configuration in the `env.php` file. If AMQP or STOMP is configured in the deployment configuration of the queue, the respective connection is used. Otherwise, database connections are used.
+As a result, if AMQP or STOMP is configured in the deployment configuration of the queue, you can omit connection declarations in the `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` [message queue configuration files](./configuration.md).
+
 <InlineAlert variant="info" slots="text"/>
 
-Message queue connections are defined dynamically, based on the deployment configuration in the `env.php` file. If AMQP is configured in the deployment configuration of the queue, AMQP connections are used. Otherwise, database connections are used.
-As a result, if AMQP is configured in the deployment configuration of the queue, you can omit connection declarations in the `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` [message queue configuration files](./configuration.md).
+ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.6 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers.

src/pages/development/components/message-queues/index.md

@@ -9,9 +9,12 @@ keywords:
 
 Message queues provide an asynchronous communications mechanism in which the sender and the receiver of a message do not contact each other, nor do they need to communicate with the message queue at the same time. When a sender places a message onto a queue, it is stored until the recipient receives them.
 
-In Adobe Commerce and Magento Open Source, the Message Queue Framework (MQF) is a fully-functional system that allows a module to publish messages to queues. It also creates consumers to receive them asynchronously. The MQF primarily uses [RabbitMQ](http://www.rabbitmq.com) as the messaging broker, which provides a scalable platform for sending and receiving messages. It also includes a mechanism for storing undelivered messages. RabbitMQ is based on the Advanced Message Queuing Protocol (AMQP) 0.9.1 specification.
+In Adobe Commerce and Magento Open Source, the Message Queue Framework (MQF) is a fully-functional system that allows a module to publish messages to queues. It also creates consumers to receive them asynchronously. The MQF supports multiple messaging brokers:
 
-A basic message queue system can also be set up without using RabbitMQ. In this system, a MySQL adapter stores messages in the database. Three database tables (`queue`, `queue_message`, and `queue_message_status`) manage the message queue workload. Cron jobs ensure the consumers are able to receive messages. This solution is not very scalable. RabbitMQ should be used whenever possible.
+- **[RabbitMQ](http://www.rabbitmq.com)** - The primary messaging broker, which provides a scalable platform for sending and receiving messages. It includes a mechanism for storing undelivered messages and is based on the Advanced Message Queuing Protocol (AMQP) 0.9.1 specification.
+- **[Apache ActiveMQ Artemis](https://activemq.apache.org/components/artemis/)** - An alternative messaging broker that uses the STOMP (Simple Text Oriented Messaging Protocol) for reliable and scalable messaging, offering flexibility for STOMP-based integrations.
+
+A basic message queue system can also be set up without using external message brokers. In this system, a MySQL adapter stores messages in the database. Three database tables (`queue`, `queue_message`, and `queue_message_status`) manage the message queue workload. Cron jobs ensure the consumers are able to receive messages. This solution is not very scalable. External message brokers like RabbitMQ or ActiveMQ Artemis should be used whenever possible.
 
 See [Configure message queues](configuration.md) for information about setting up the message queue system.
 
@@ -49,7 +52,11 @@ Perform the following actions:
 1. Decode the message using topic name taken from the `\Magento\Framework\MessageQueue\ConsumerConfigurationInterface`.
 1. Invoke callback `Magento\Framework\MessageQueue\ConsumerConfigurationInterface::getCallback` and pass the decoded data as an argument.
 
-## Change message queue from MySQL to AMQP
+### ActiveMQ Artemis (STOMP)
+
+Similar to RabbitMQ, ActiveMQ Artemis instantiates a consumer that is defined in a [`queue_consumer.xml`](configuration.md#queue_consumerxml) file. The consumer (`customer_created_listener`) listens to the queue and receives all new messages. For every message, it invokes `Magento\Some\Class::processMessage($message)`
+
+## Change message queue from MySQL to external brokers
 
 The following sample introduces a runtime configuration that allows you to redefine the adapter for a topic.
 
@@ -85,3 +92,40 @@ The following sample introduces a runtime configuration that allows you to redef
     ],
 ],
 ```
+
+### Switch from MySQL to STOMP (ActiveMQ Artemis)
+
+The following configuration shows how to configure a topic to use STOMP instead of MySQL:
+
+```php
+'queue' => [
+    'topics' => [
+        'inventory.update' => [
+            'publisher' => 'stomp-magento'
+        ]
+    ],
+    'config' => [
+        'publishers' => [
+            'inventory.update' => [
+                'connections' => [
+                    'stomp' => [
+                        'name' => 'stomp',
+                        'exchange' => 'magento',
+                        'disabled' => false
+                    ],
+                    'db' => [
+                        'name' => 'db',
+                        'exchange' => 'magento',
+                        'disabled' => true
+                    ]
+                ]
+            ]
+        ]
+    ],
+    'consumers' => [
+        'inventory.update' => [
+            'connection' => 'stomp',
+        ],
+    ]
+],
+```