diff --git a/src/pages/development/components/message-queues/async-configuration.md b/src/pages/development/components/message-queues/async-configuration.md index ef216ef16..9cc1c0c5d 100644 --- a/src/pages/development/components/message-queues/async-configuration.md +++ b/src/pages/development/components/message-queues/async-configuration.md @@ -1,6 +1,6 @@ --- title: Asynchronous Configuration | Commerce PHP Extensions -description: Learn about the important configuration files that you must configure in your Adobe commerce and Magento Open Source extensions. +description: Learn about the message queue configuration files for asynchronous and bulk API operations in Adobe Commerce. contributor_name: comwrap GmbH contributor_link: https://www.comwrap.com keywords: @@ -9,21 +9,16 @@ keywords: # Asynchronous configuration -When using the message queue, four configuration files in your component must be updated: +When using the message queue, four configuration files are required in your component: -* communication.xml -* queue_consumer.xml -* queue_topology.xml -* queue_publisher.xml +* `communication.xml` +* `queue_consumer.xml` +* `queue_topology.xml` +* `queue_publisher.xml` -More information can be found in [Configure message queues](configuration.md). +For more information, see [Configure message queues](configuration.md). -Asynchronous and Bulk APIs are built on top of the usual REST API and use the Message Queue Framework for processing messages. To ease development efforts, the Asynchronous API pre-generates the following configuration files: - -* communication.xml -* queue_publisher.xml - -and provides the `queue_topology.xml` and `queue_consumer.xml` files within the `Magento/WebapiAsync` module. +Asynchronous and Bulk APIs are built on top of the REST API and use the Message Queue Framework for processing messages. To simplify development, the Asynchronous API auto-generates `communication.xml` and `queue_publisher.xml`. The `Magento/WebapiAsync` module provides `queue_topology.xml` and `queue_consumer.xml`. ## communication.xml @@ -46,28 +41,33 @@ 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. +The `\Magento\WebapiAsync\Code\Generator\Config\RemoteServiceReader\Publisher::read()` method calls `\Magento\AsynchronousOperations\Model\ConfigInterface::getServices()` to get an array of REST API routes that can be executed asynchronously. It then dynamically resolves the connection name (`db` (default), `amqp`, or `stomp` for ActiveMQ Artemis) based on the `env.php` deployment configuration and defines 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 - ``` -### queue_topology.xml +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. +The message queue topology configuration links all auto-generated topic names with the `async.` prefix to the `magento` exchange. It defines the queue named `async.operations.all` as the destination for all messages. ```xml - + ``` -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`. +The message queue connection is defined dynamically based on the deployment configuration in `env.php`. If AMQP or STOMP is configured for the queue, that connection is used. Otherwise, the database connection is used. Because the connection is resolved dynamically, explicit declarations are unnecessary in the [message queue configuration files](./configuration.md): `queue_consumer.xml`, `queue_publisher.xml`, `queue_topology.xml`. + + + +ActiveMQ Artemis (STOMP) support was introduced in Adobe Commerce 2.4.5. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. diff --git a/src/pages/development/components/message-queues/bulk-operations-example.md b/src/pages/development/components/message-queues/bulk-operations-example.md index e75df910a..1cfcd1022 100644 --- a/src/pages/development/components/message-queues/bulk-operations-example.md +++ b/src/pages/development/components/message-queues/bulk-operations-example.md @@ -1,23 +1,29 @@ --- -title: Bulk operations implementation | Commerce PHP Extensions -description: Use this example to create your own bulk operation in Adobe Commerce or Magento Open Source. +title: Example bulk operations implementation +description: Learn how to implement bulk operations for asynchronous processing in Adobe Commerce. keywords: - Extensions --- # Example bulk operations implementation -This document describes how bulk operations can be implemented. There are three primary tasks to accomplish this: +This topic explains how to implement bulk operations in Adobe Commerce. Bulk operations allow you to process large sets of data asynchronously using message queues. -* Create a publisher that sends messages to the message queue -* Create a consumer that receives and processes messages -* Configure the message queues +Implementation requires three components: + +* **Publisher** - Sends messages to the message queue +* **Consumer** - Receives and processes messages from the queue +* **Message queue configuration** - Defines the queue topology and routing ## Create a publisher -A publisher's duties include scheduling a bulk operation. It must generate a `bulkUuid` for each operation, send each operation to the message queue, and report on the status of each operations. +The publisher schedules bulk operations by performing these tasks: + +* Generating a unique `bulkUuid` for the operation +* Publishing each operation to the message queue +* Tracking and reporting operation status -The following code sample shows how these duties can be completed. +The following example demonstrates a publisher implementation: ```php //etc` directory. +Configure the message queue topology by creating or editing the following files in the `app/code///etc` directory: -* `communication.xml` -* `di.xml` -* `queue_consumer.xml` -* `queue_publisher.xml` -* `queue_topology.xml` +* `communication.xml` +* `di.xml` +* `queue_consumer.xml` +* `queue_publisher.xml` +* `queue_topology.xml` -For more information about the `di.xml` file, see [Dependency Injection](../dependency-injection.md). For information the other files, see [Configure message queues](configuration.md). +For more information about `di.xml`, see [Dependency Injection](../dependency-injection.md). For information about the other files, see [Configure message queues](configuration.md). -### Create `communication.xml` +### communication.xml -The `communication.xml` file defines aspects of the message queue system that apply to all topics for the module. Create this file with the following contents: +The `communication.xml` file defines message queue topics for the module: ```xml @@ -299,9 +305,9 @@ The `communication.xml` file defines aspects of the message queue system that ap ``` -### Create `di.xml` +### di.xml -Add the following type to the module's `di.xml` file. +Add the following type to the module's `di.xml` file: ```xml @@ -313,35 +319,60 @@ Add the following type to the module's `di.xml` file. ``` -### Create `queue_consumer.xml` +### queue_consumer.xml -The `queue_consumer.xml` file defines the relationship between a queue and its consumer. Create this file with the following contents: +The `queue_consumer.xml` file defines the relationship between a queue and its consumer: ```xml - + ``` -### Create `queue_publisher.xml` +The connection type (AMQP or STOMP) is determined automatically from the `env.php` configuration. + +### queue_publisher.xml + +The `queue_publisher.xml` file defines the exchange where a topic is published. + +**For RabbitMQ (AMQP):** + +```xml + + + + +``` -The `queue_publisher.xml` file defines the exchange where a topic is published. Create this file with the following contents: +Alternatively, you can explicitly specify the connection and exchange: ```xml - + ``` -### Create `queue_topology.xml` +**For ActiveMQ Artemis (STOMP):** + +```xml + + + +``` + + + +For ActiveMQ Artemis, the `` element is not required because the connection type is determined from `env.php`. If the topic name and queue name differ, specify the `queue` attribute in the `` element. + +### 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: +The `queue_topology.xml` file defines message routing rules and declares queues and exchanges: ```xml - + @@ -349,5 +380,4 @@ The `queue_topology.xml` file defines the message routing rules and declares que -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). +Message queue connections are resolved dynamically from `env.php`. When AMQP or STOMP is configured, the corresponding connection is applied; otherwise, the database connection is used. You can omit connection declarations from `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` when using AMQP or STOMP. ActiveMQ Artemis (STOMP) was introduced in Adobe Commerce 2.4.5 and uses ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. See [Message queue configuration files](configuration.md). diff --git a/src/pages/development/components/message-queues/configuration.md b/src/pages/development/components/message-queues/configuration.md index aa68277c0..8aa9204bb 100644 --- a/src/pages/development/components/message-queues/configuration.md +++ b/src/pages/development/components/message-queues/configuration.md @@ -8,27 +8,32 @@ keywords: # Configure message queues -The message queue topology is an Adobe Commerce and Magento Open Source feature. You can also add it to existing modules. +The message queue topology is an Adobe Commerce and Magento Open Source feature that can be added to existing modules. Configuring the message queue topology involves creating and modifying the following configuration files in the `/etc` directory: -* [`communication.xml`](#communicationxml) - Defines aspects of the message queue system that all communication types have in common. -* [`queue_consumer.xml`](#queue_consumerxml) - Defines the relationship between an existing queue and its consumer. -* [`queue_topology.xml`](#queue_topologyxml) - Defines the message routing rules and declares queues and exchanges. -* [`queue_publisher.xml`](#queue_publisherxml) - Defines the exchange where a topic is published. +* [`communication.xml`](#communicationxml)—Defines aspects of the message queue system that all communication types have in common. +* [`queue_consumer.xml`](#queue_consumerxml)—Defines the relationship between an existing queue and its consumer. +* [`queue_topology.xml`](#queue_topologyxml)—Defines the message routing rules and declares queues and exchanges. +* [`queue_publisher.xml`](#queue_publisherxml)—Defines the exchange where a topic is published. + + + +If you are upgrading from Adobe Commerce or Magento Open Source 2.0 or 2.1, see [Migrate message queue configuration](migration.md). ## Use cases -Depending on your needs, you may only need to create and configure `communication.xml` and one or two of these files. +Depending on your use case, you can create and configure `communication.xml` along with one or more of the following files: + +* **Publish messages to an existing queue created by a third-party system**—Configure the `queue_publisher.xml` file only. + +* **Consume messages from an existing queue**—Configure the `queue_consumer.xml` file only. -* If you only want to publish to an existing queue created by a 3rd party system, you will only need the `queue_publisher.xml` file. -* If you only want to consume from an existing queue, you will only need the `queue_consumer.xml` config file. -* In cases where you want to configure the local queue and publish to it for 3rd party systems to consume, you will need the `queue_publisher.xml` and `queue_topology.xml` files. -* When you want to configure the local queue and consume messages published by 3rd party system, you will need the `queue_topology.xml` and `queue_consumer.xml` files. +* **Define a local queue and consume messages published by a third-party system**—Configure both the `queue_topology.xml` and `queue_consumer.xml` files. ## `communication.xml` -The `/etc/communication.xml` file defines aspects of the message queue system that all communication types have in common. This release supports AMQP and database connections. +The `/etc/communication.xml` file defines aspects of the message queue system that all communication types have in common. Adobe Commerce supports AMQP, STOMP, and database connections. ### Example @@ -46,29 +51,31 @@ The following sample defines two synchronous topics. The first topic is for RPC ``` -#### topic element +#### `topic` element Topic configuration is flexible in that you can switch the transport layer for topics at deployment time. These values can be overwritten in the `env.php` file. -The `name` parameter is required. The topic definition must include either a `request` or a `schema`. Use `schema` if you want to implement a custom service interface. Otherwise, specify `request`. If `request` is specified, then also specify `response` if the topic is synchronous. +The `name` parameter is required. The topic definition must include either a `request` or a `schema`. Use `schema` if you want to implement a custom service interface. Otherwise, specify `request`. If `request` is specified, then also specify `response` if the topic is synchronous. -Parameter | Description ---- | --- -name | A string that uniquely identifies the topic. A topic name should be a series of strings that are separated by periods. The leftmost string should be the most general, and each string afterward should narrow the scope. For example, to describe actions for tending to pets, you might create names such as `cat.white.feed` and `dog.retriever.walk`. Wildcards are not supported in the `communication.xml` file. -request | Specifies the data type of the topic. -response | Specifies the format of the response. This parameter is required if you are defining a synchronous topic. Omit this parameter if you are defining an asynchronous topic. -schema | The interface that describes the structure of the message. The format must be `\Api\::`. +| Parameter | Description | +| --- | --- | +| `name` | A unique string identifier for the topic. Use a series of period-separated strings, with the leftmost being most general and each subsequent string narrowing the scope. For example, `cat.white.feed` and `dog.retriever.walk`. Wildcards are not supported in `communication.xml`. +| `request` | Specifies the data type of the topic. | +| `response` | Specifies the format of the response. This parameter is required if you are defining a synchronous topic. Omit this parameter if you are defining an asynchronous topic. | +| `schema` | The interface that describes the structure of the message. The format must be `\Api\::`. | -#### handler element +#### `handler` element The `handler` element specifies the class where the logic for handling messages exists and the method it executes. -Parameter | Description ---- | --- -name | A string that uniquely defines the handler. The name can be derived from the topic name if the handler is specific to the topic. If the handler provides more generic capabilities, name the handler so that it describes those capabilities. -type | The class or interface that defines the handler. -method | The method this handler executes. -disabled | Determines whether this handler is disabled. The default value is `false`. +| Parameter | Description | +| --- | --- | +| `name` | A string that uniquely defines the handler. The name can be derived from the topic name if the handler is specific to the topic. If the handler provides more generic capabilities, name the handler so that it describes those capabilities. | +| `type` | The class or interface that defines the handler. | +| `method` | The method this handler executes. | +| `disabled` | Determines whether this handler is disabled. The default value is `false`. | + +See [Handler processing](#handler-processing). ## `queue_consumer.xml` @@ -81,71 +88,37 @@ The `queue_consumer.xml` file contains one or more `consumer` elements: - - + + ``` #### `consumer` element -| Attribute | Description | -| ----------------------------- | ----------- | -| name (required) | The name of the consumer. | -| queue (required) | Defines the queue name to send the message to. | -| handler | Specifies the class and method that processes the message. The value must be specified in the format `\Module\::`.| -| consumerInstance | The class name that consumes the message. Default value: `Magento\Framework\MessageQueue\Consumer`. | -| connection | Connection is defined dynamically based on deployment configuration of message queue in `env.php`. If AMQP is configured in deployment configuration, AMQP connection is used. Otherwise, db connection is used. If you still want to specify connection type for consumer, keep in mind that for AMQP connections, the connection name must match the `connection` attribute in the `queue_topology.xml` file. Otherwise, the connection name must be `db`. | -| maxMessages | Specifies the maximum number of messages to consume.| -| maxIdleTime | Defines the maximum waiting time in seconds for a new message from the queue. If no message was handled within this period of time, the consumer exits. Default value: `null`| -| sleep | Specifies time in seconds to sleep before checking if a new message is available in the queue. Default value is `null` which equals to 1 second.| -| onlySpawnWhenMessageAvailable | Boolean value (`1` or `0` only) that identifies whether a consumer should be spawned only if there is available message in the related queue. Default value: `null`| +| Attribute | Description | +| --- | --- | +| `name` (required) | The name of the consumer. | +| `queue` (required) | Specifies the queue name to send the message to. | +| `handler` | Specifies the class and method that processes the message. The value must be specified in the format `\Module\::`. See [Handler processing](#handler-processing). | +| `consumerInstance` | The class name that consumes the message. The default value is `Magento\Framework\MessageQueue\Consumer`. | +| `connection` | For explicit values, use `amqp`, `stomp`, or `db`. If omitted, the connection is resolved automatically. See [Connection resolution](#connection-resolution). | +| `maxMessages` | Specifies the maximum number of messages to consume. | +| `maxIdleTime` | Defines the maximum waiting time in seconds for a new message from the queue. If no message was handled within this period of time, the consumer exits. The default value is `null`. | +| `sleep` | Specifies time in seconds to sleep before checking if a new message is available in the queue. The default value is `null` which equals 1 second. | +| `onlySpawnWhenMessageAvailable` | Boolean value (`1` or `0` only) that identifies whether a consumer should be spawned only if there is available message in the related queue. The default value is `null`. | -The `maxIdleTime` and `sleep` attributes will be handled only by consumers that were fired with a defined `maxMessages` parameter. The `onlySpawnWhenMessageAvailable` attribute is only checked and validated by the `\Magento\MessageQueue\Model\Cron\ConsumersRunner` class that runs consumer processes with cron. - -It is possible to set `onlySpawnWhenMessageAvailable` globally by setting `queue/only_spawn_when_message_available` equal to `0` or `1` in `app/etc/env.php`. By default, the global value of `only_spawn_when_message_available` for all consumers is `1`. -The `onlySpawnWhenMessageAvailable` consumer attribute has higher priority than the global `queue/only_spawn_when_message_available` setting in `app/etc/env.php`. Therefore, it is possible to overwrite the global `only_spawn_when_message_available` value by setting `onlySpawnWhenMessageAvailable` equal to `0` or `1` for each consumer in `queue_consumer.xml`. - -The `onlySpawnWhenMessageAvailable` and `maxIdleTime` attributes may be combined if a specific consumer needs to run infrequently. The consumer will only spawn when it is needed, and it terminates itself if it is inactive for a certain period. -It is also possible to combine the global `queue/only_spawn_when_message_available` setting in `app/etc/env.php` with the `queue/consumers-wait-for-messages` setting. That means that the consumer will run only when there is an available message in the queue, and it will be terminated when there are no more messages to process. This combination of settings is recommended to save server resources such as CPU usage. - -The [`consumers-wait-for-messages`](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/tutorials/message-consumers) option works similar to `onlySpawnWhenMessageAvailable`. When it is set to `false`, the consumer processes all messages and exits if there are no available messages in the queue. -The problem is that every time the cron job `cron_consumers_runner` runs, it spawns a new consumer process, the consumer checks if messages are available, and it terminates itself if there are no messages. -Meanwhile, the `onlySpawnWhenMessageAvailable` attribute first checks if there are available messages, and it spawns a new consumer process only if there are messages. It means that it does not spawn unneeded processes which take up memory, live for a very short period, and then disappear. - - - -The [`consumers-wait-for-messages`](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/tutorials/message-consumers) option is a global option and cannot be configured separately for each consumer, such as the `onlySpawnWhenMessageAvailable` option. - -#### `handler` element - -A handler is a class and method that processes a message. The application has two ways to define a handler for messages. - -* In the `` element of the module's `communication.xml` file -* In the `handler` attribute of the module's `queue_consumer.xml` file - -The following conditions determine how these handlers are processed: - -* If the consumer in `queue_consumer.xml` does not have a `consumerInstance` defined, then the system uses the default consumer: `Magento\Framework\MessageQueue\Consumer`. In this case, if the `` element contains the `handler` attribute, then it will be used, and the `` element in `communication.xml` will be ignored. -* If the consumer in `queue_consumer.xml` has a `consumerInstance` defined, then the specific consumer implementation defines how the `handler` is used. - -The application provides these consumers out-of-the-box: - -| Class name | Handler in `communication.xml` will be executed? | Handler in `queue_consumer.xml` will be executed? | -| ---------------- | ----------- | ---------- | -| `Magento\Framework\MessageQueue\Consumer` | Only if not defined in `queue_consumer.xml` | Yes, if exists | -| `Magento\Framework\MessageQueue\BatchConsumer` | Only if not defined in `queue_consumer.xml` | Yes, if exists | -| `Magento\AsynchronousOperations\Model\MassConsumer` | Yes, if exists | Yes, if exists | +The `maxIdleTime` and `sleep` attributes are handled only by consumers fired with a defined `maxMessages` parameter. The `onlySpawnWhenMessageAvailable` attribute is only validated by the `\Magento\MessageQueue\Model\Cron\ConsumersRunner` class that runs consumer processes with cron. For details, see [Consumer spawning behavior](#consumer-spawning-behavior). ## `queue_topology.xml` The `queue_topology.xml` file defines the message routing rules and declares queues and exchanges. It contains the following elements: -* `exchange` -* `exchange/binding` (optional) -* `exchange/arguments` (optional) -* `exchange/binding/arguments` (optional) +* `exchange` +* `exchange/binding` (optional) +* `exchange/arguments` (optional) +* `exchange/binding/arguments` (optional) ### Example @@ -155,7 +128,7 @@ The `queue_topology.xml` file defines the message routing rules and declares que - + value @@ -176,12 +149,12 @@ The `queue_topology.xml` file defines the message routing rules and declares que | Attribute | Description | | -------------- | ----------- | - name (required) | A unique ID for the exchange. - type | Specifies the type of exchange. The default value is `topic` because only `topic` type is supported. - connection (required) | Connection is defined dynamically based on deployment configuration of message queue in `env.php`. If AMQP is configured in deployment configuration, AMQP connection is used. Otherwise, db connection is used. If you still want to specify connection, the connection name must be `amqp` for AMQP. For MySQL connections, the connection name must be `db`. - durable | Boolean value indicating whether the exchange is persistent. Non-durable exchanges are purged when the server restarts. The default is `true`. - autoDelete | Boolean value indicating whether the exchange is deleted when all queues have finished using it. The default is `false`. - internal | Boolean value. If set to true, the exchange may not be used directly by publishers, but only when bound to other exchanges. The default is `false`. +| `name` (required) | A unique ID for the exchange. | +| `type` | Specifies the type of exchange. Currently, the only value supported is `topic`. | +| `connection` | For explicit values, use `amqp`, `stomp`, or `db`. If omitted, the connection is resolved automatically. See [Connection resolution](#connection-resolution). | +| `durable` | Boolean value indicating whether the exchange is persistent. Non-durable exchanges are purged when the server restarts. The default value is `true`. | +| `autoDelete` | Boolean value indicating whether the exchange is deleted when all queues have finished using it. The default is `false`. | +| `internal` | Boolean value. If set to true, the exchange may not be used directly by publishers, but only when bound to other exchanges. The default is `false`. | #### `binding` element @@ -189,20 +162,20 @@ The `binding` element is a subnode of the `exchange` element. | Attribute | Description | | -------------- | ----------- | -| id (required) | A unique ID for this binding. | -| topic (required) | The name of a topic. You can specify an asterisk (*) or pound sign (#) as wildcards. These are described below the table.| -| destinationType | The default value is `queue`. | -| destination (required) | Identifies the name of a queue. | -| disabled | Determines whether this binding is disabled. The default value is `false`. | +| `id` (required) | A unique ID for this binding. | +| `topic` (required) | The name of a topic. You can specify an asterisk (*) or pound sign (#) as wildcards. These are described below the table.| +| `destinationType` | The default value is `queue`. | +| `destination` (required) | Identifies the name of a queue. | +| `disabled` | Determines whether this binding is disabled. The default value is `false`. | Example topic names that include wildcards: -| Pattern | Description | Example matching topics | Example non-matching topics -| --- | --- | --- | --- -`*.*.*` | Matches any topic that contains exactly two periods. | `mytopic.createOrder.success`, `mytopic.updatePrice.item1` | `mytopic.createOrder`, `mytopic.createOrder.success.true` -`#`| Matches any topic name. | `mytopic`, `mytopic.createOrder.success`, `this.is.a.long.topic.name` | Not applicable -`mytopic.#` | Matches any topic name that begins with `mytopic` and has a period afterward. | `mytopic.success`, `mytopic.createOrder.error` | `new.mytopic.success`, -`*.Order.#` | There must be one string before __.Order__. There can be any number of strings (including 0) after that. | `mytopic.Order`, `mytopic.Order.Create`, `newtopic.Order.delete.success` | `mytopic.Sales.Order.Create` +| Pattern | Description | Example matching topics | Example non-matching topics | +| --- | --- | --- | --- | +| `*.*.*` | Matches any topic that contains three segments (two periods) | `mytopic.createOrder.success`, `mytopic.updatePrice.item1` | `mytopic.createOrder`, `mytopic.createOrder.success.true` | +| `#` | Matches any topic name. | `mytopic`, `mytopic.createOrder.success`, `this.is.a.long.topic.name` | Not applicable | +| `mytopic.#` | Matches any topic name that begins with `mytopic` and has a period afterward. | `mytopic.success`, `mytopic.createOrder.error` | `new.mytopic.success` | +| `*.Order.#` | There must be one string before `.Order`. There can be any number of strings (including 0) after that. | `mytopic.Order`, `mytopic.Order.Create`, `newtopic.Order.delete.success` | `mytopic.Sales.Order.Create` | #### `arguments` element @@ -210,10 +183,10 @@ The `arguments` element is an optional element that contains one or more `argume Each `argument` definition must have the following parameters: -| Attribute | Description | -| --------------- | ----------- | -| name | The parameter name | -| type | The data type of the value | +| Attribute | Description | +| --- | --- | +| `name` | The parameter name. | +| `type` | The data type of the value. | The following illustrates an `arguments` block: @@ -228,11 +201,13 @@ The following illustrates an `arguments` block: The `queue_publisher.xml` file defines which connection and exchange to use to publish messages for a specific topic. It contains the following elements: -* publisher -* publisher/connection +* `publisher` +* `publisher/connection` ### Example +**For RabbitMQ (AMQP):** + ```xml @@ -244,27 +219,199 @@ The `queue_publisher.xml` file defines which connection and exchange to use to p ``` +**For ActiveMQ Artemis (STOMP):** + +```xml + + + + + + + + +``` + #### `publisher` element -| Attribute | Description | -| -------------------- | ----------- | -| topic (required) | The name of the topic. | -| disabled | Determines whether this queue is disabled. The default value is `false`. | +| Attribute | Description | +| --- | --- | +| `topic` (required) | The name of the topic. | +| `queue` | For ActiveMQ Artemis (STOMP), specifies the queue name when it differs from the topic name. | +| `disabled` | Determines whether this queue is disabled. The default value is `false`. | #### `connection` element -The `connection` element is a subnode of the `publisher` element. There must not be more than one enabled active connection to a publisher defined at a time. If you omit the `connection` element, connection will be defined dynamically based on deployment configuration of message queue in `env.php` and exchange `magento` will be used. If AMQP is configured in deployment configuration, AMQP connection is used. Otherwise, db connection is used. +The `connection` element is a subnode of the `publisher` element. Only one enabled connection can be defined for a publisher at any given time. If you omit the `connection` element, the connection is resolved automatically and `magento` is used as the exchange. See [Connection resolution](#connection-resolution). -| Attribute | Description | -| -------------------- | ----------- | -| name | Connection name is defined dynamically based on deployment configuration of message queue in `env.php`. If you still want to specify connection type for publisher, keep in mind that for AMQP connections, the connection name must match the `connection` attribute in the `queue_topology.xml` file. Otherwise, the connection name must be `db`. | -| exchange | The name of the exchange to publish to. The default system exchange name is `magento`. | -| disabled | Determines whether this queue is disabled. The default value is `false`. | +| Attribute | Description | +| --- | --- | +| `name` | The connection name. For explicit values, use `amqp`, `stomp`, or `db`. If you omit the `connection` element, the [connection is resolved automatically](#connection-resolution). +| `exchange` | The name of the exchange to publish to. The default system exchange name is `magento`. | +| `disabled` | Determines whether this queue is disabled. The default value is `false`. | You cannot enable more than one `publisher` for each `topic`. +## Connection resolution + +Connection names are resolved dynamically based on the message queue deployment configuration in `env.php`. If you don't explicitly specify a connection, the system automatically selects the appropriate one. + +### Automatic resolution + +The system checks `env.php` for message queue configuration: + +* If AMQP (RabbitMQ) is configured, the `amqp` connection is used +* If STOMP (ActiveMQ Artemis) is configured, the `stomp` connection is used +* Otherwise, the database (`db`) connection is used + +### Explicit connection values + +When specifying a connection explicitly, use one of these values: + +| Connection type | Value | Notes | +| --- | --- | --- | +| RabbitMQ | `amqp` | For AMQP connections in `queue_consumer.xml`, the value must match the `connection` attribute in `queue_topology.xml`. | +| ActiveMQ Artemis | `stomp` | Requires Adobe Commerce or Magento Open Source 2.4.5 or later. Use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. | +| Database | `db` | MySQL-based queue storage. Used as fallback when no message broker is configured. | + +## Handler processing + +A [handler](#handler-element) is a class and method that processes a message. You can define a handler in two places: + +* In the `` element of the module's `communication.xml` file +* In the `handler` attribute of the module's `queue_consumer.xml` file + +The following conditions determine which handler is executed: + +* If the consumer in `queue_consumer.xml` does not have a `consumerInstance` defined, the system uses the default consumer: `Magento\Framework\MessageQueue\Consumer`. In this case, if the `` element contains the `handler` attribute, it is used and the `` element in `communication.xml` is ignored. +* If the consumer in `queue_consumer.xml` has a `consumerInstance` defined, the specific consumer implementation defines how the handler is used. + +The following table shows how the built-in consumers process handlers: + +| Class name | Handler in `communication.xml` executed? | Handler in `queue_consumer.xml` executed? | +| --- | --- | --- | +| `Magento\Framework\MessageQueue\Consumer` | Only if not defined in `queue_consumer.xml` | Yes, if exists | +| `Magento\Framework\MessageQueue\BatchConsumer` | Only if not defined in `queue_consumer.xml` | Yes, if exists | +| `Magento\AsynchronousOperations\Model\MassConsumer` | Yes, if exists | Yes, if exists | + +## Consumer spawning behavior + +Two settings control when consumers spawn and exit: `onlySpawnWhenMessageAvailable` and [`consumers-wait-for-messages`](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/tutorials/message-consumers). Both help reduce server resource usage, but they work differently. + +| Setting | Scope | Behavior | +| --- | --- | --- | +| `onlySpawnWhenMessageAvailable` | Per-consumer or global | Checks for messages *before* spawning. Only creates a consumer process if messages exist in the queue. | +| `consumers-wait-for-messages` | Global only | Always spawns a consumer. When set to `false`, the consumer exits immediately if no messages are available. Because this option is a global option, it cannot be configured separately for each consumer. | + +The key difference between the two settings: `onlySpawnWhenMessageAvailable` prevents unnecessary process creation, while `consumers-wait-for-messages` creates a process that immediately terminates if the queue is empty. + +### Configuration + +Set `onlySpawnWhenMessageAvailable` globally in `app/etc/env.php`: + +```php +'queue' => [ + 'only_spawn_when_message_available' => 1 +] +``` + +The default global value is `1`. To override for a specific consumer, set the `onlySpawnWhenMessageAvailable` attribute in `queue_consumer.xml`. The per-consumer setting takes priority over the global setting. + +### Recommended combinations + +* **Infrequent consumers**—Combine `onlySpawnWhenMessageAvailable` with `maxIdleTime`. The consumer spawns only when needed and terminates after a period of inactivity. +* **Resource optimization**—Combine the global `only_spawn_when_message_available` setting with `consumers-wait-for-messages` set to `false`. Consumers run only when messages exist and exit when the queue is empty. + +## `env.php` Configuration + +The message queue connection configuration is defined in the `app/etc/env.php` file. When `connection` elements are omitted from `queue_consumer.xml`, `queue_publisher.xml`, and `queue_topology.xml` files, the system automatically uses the connection configured in `env.php`. + +### Example configurations + +**For RabbitMQ (AMQP) only:** + +```php +return [ + // ... other configuration + 'queue' => [ + 'amqp' => [ + 'host' => 'localhost', + 'port' => '5672', + 'user' => 'guest', + 'password' => 'guest', + 'virtualhost' => '/' + ], + 'consumers_wait_for_messages' => 1 + ] +]; +``` + +**For ActiveMQ Artemis (STOMP) only:** + +```php +return [ + // ... other configuration + 'queue' => [ + 'stomp' => [ + 'host' => 'localhost', + 'port' => '61613', + 'user' => 'admin', + 'password' => 'admin' + ], + 'consumers_wait_for_messages' => 1 + ] +]; +``` + +**For MySQL (Database) only:** + +```php +return [ + // ... other configuration + 'queue' => [ + 'consumers_wait_for_messages' => 1 + ] + // Database connection uses existing 'db' configuration +]; +``` + +**When multiple connection types are configured:** + +If you have both AMQP and STOMP configured, you must specify `default_connection` to indicate which one the system should use: + +```php +return [ + // ... other configuration + 'queue' => [ + 'amqp' => [ + 'host' => 'localhost', + 'port' => '5672', + 'user' => 'guest', + 'password' => 'guest', + 'virtualhost' => '/' + ], + 'stomp' => [ + 'host' => 'localhost', + 'port' => '61613', + 'user' => 'admin', + 'password' => 'admin' + ], + 'default_connection' => 'amqp', // Required when multiple connections exist + 'consumers_wait_for_messages' => 1 + ] +]; +``` + +The `default_connection` value can be `db`, `amqp`, or `stomp`. When only one connection type is configured in `env.php`, the system automatically uses that connection and `default_connection` is not required. If `queue/default_connection` is specified, that connection is used for all message queues unless a specific connection is defined in a module's `queue_topology.xml`, `queue_publisher.xml`, or `queue_consumer.xml` file. + +## ActiveMQ Artemis (STOMP) support + + + +ActiveMQ Artemis (STOMP) support was introduced in Adobe Commerce 2.4.5 and later versions. For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. + ## Updating `queue.xml` See [Migrate message queue configuration](migration.md) for information about upgrading from Adobe Commerce and Magento Open Source 2.0 or 2.1. diff --git a/src/pages/development/components/message-queues/index.md b/src/pages/development/components/message-queues/index.md index 10db2b50d..e0ed2451e 100644 --- a/src/pages/development/components/message-queues/index.md +++ b/src/pages/development/components/message-queues/index.md @@ -1,37 +1,57 @@ --- title: Message Queues | Commerce PHP Extensions -description: Review an introduction to the message queue system in Adobe Commerce and Magento Open Source. +description: Learn about the Message Queue Framework (MQF) for asynchronous communication in Adobe Commerce and how to configure different messaging brokers. +role: Admin, Developer keywords: - Extensions --- # Message queues -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. +Message queues provide an asynchronous communications mechanism in which the sender and the receiver of a message do not contact each other directly. When a sender places a message onto a queue, the message is stored until the recipient receives it. -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. +## Message Queue Framework overview -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. +The Adobe Commerce Message Queue Framework (MQF) is a fully-functional system that allows a module to publish messages to queues and create consumers to receive them asynchronously. + +The MQF supports the following messaging brokers: + +| Broker | Protocol | Description | +| --- | --- | --- | +| [RabbitMQ](http://www.rabbitmq.com) | AMQP 0.9.1 | The primary messaging broker with a scalable platform for sending and receiving messages. Includes a mechanism for storing undelivered messages. | +| [Apache ActiveMQ Artemis](https://activemq.apache.org/components/artemis/) | STOMP | An alternative messaging broker using Simple Text Oriented Messaging Protocol (STOMP) for reliable and scalable messaging. | +| MySQL adapter | Database | A basic message queue system that stores messages in the database using three tables: `queue`, `queue_message`, and `queue_message_status`. Cron jobs ensure consumers receive messages. | + + + +The MySQL adapter is not scalable. Use an external message broker like RabbitMQ or ActiveMQ Artemis for production environments whenever possible. See [Configure message queues](configuration.md) for information about setting up the message queue system. -## Send a message from the publisher to a queue +## Publish messages to a queue -The following code sends a message to the queue. The `publish` method is defined in `PublisherInterface` +Use the `publish` method defined in `PublisherInterface` to send a message to the queue: ```php -$publisher->publish($topic, $message) +$publisher->publish($topic, $message); ``` -In a MySQL adapter environment, a message that is published to multiple queues creates a single record in `queue_message` and multiple records in `queue_message_status`: one for each queue. (A join on the `queue`, `queue_message`, and `queue_message_status` tables is required). +When using the MySQL adapter, a message published to multiple queues creates: + +- A single record in `queue_message` +- Multiple records in `queue_message_status` (one for each queue) + +Retrieving these messages requires a join on the `queue`, `queue_message`, and `queue_message_status` tables. -## Instantiate a consumer +## Instantiate consumers -The procedure for instantiating a consumer differs, depending on which message queue system is being used. +The procedure for instantiating a consumer differs depending on the message queue system. -### RabbitMQ +### RabbitMQ and ActiveMQ Artemis -This 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)` +For external brokers, consumers are defined in a [`queue_consumer.xml`](configuration.md#queue_consumerxml) file. The consumer listens to the queue, receives messages, and invokes a callback method for each one. + +The following example instantiates the `customer_created_listener` consumer, which calls `Magento\Some\Class::processMessage($message)` for each message: ```php $this->consumerFactory->get('customer_created_listener') @@ -40,32 +60,37 @@ $this->consumerFactory->get('customer_created_listener') ### MySQL adapter -Implement `\Magento\Framework\MessageQueue\ConsumerInterface::process($maxNumberOfMessages)` to instantiate a consumer. +For the MySQL adapter, implement `ConsumerInterface::process($maxNumberOfMessages)` and perform the following steps: + +1. Get the queue name using `ConsumerConfigurationInterface::getQueueName`. +1. Select `$maxNumberOfMessages` records, filtering on `queue_name`. Join all three tables (`queue`, `queue_message`, `queue_message_status`). Extract fewer records at a time to improve load distribution across consumers. +1. Decode the message using the topic name from `ConsumerConfigurationInterface`. +1. Invoke `ConsumerConfigurationInterface::getCallback` with the decoded data. -Perform the following actions: +## Switch from MySQL to an external broker -1. Define the queue name associated with current consumer using `\Magento\Framework\MessageQueue\ConsumerConfigurationInterface::getQueueName`. -1. Select `$maxNumberOfMessages` message records, filtering on the `queue_name` field. You must join on all 3 tables. To accomplish this, you may want to extract fewer records at a time to improve load distribution between multiple consumers. -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. +You can switch from the MySQL adapter to an external message broker by adding runtime configuration to redefine the adapter for a topic. The configuration disables the `db` connection and enables the external broker connection. -## Change message queue from MySQL to AMQP +The following example shows how to switch a topic to an external broker. Replace the placeholder values based on your broker: -The following sample introduces a runtime configuration that allows you to redefine the adapter for a topic. +| Broker | Publisher value | Connection name | +| --- | --- | --- | +| RabbitMQ | `amqp-magento` | `amqp` | +| ActiveMQ Artemis | `stomp-magento` | `stomp` | ```php 'queue' => [ 'topics' => [ - 'product_action_attribute.update' => [ - 'publisher' => 'amqp-magento' + '' => [ + 'publisher' => '' ] ], 'config' => [ 'publishers' => [ - 'product_action_attribute.update' => [ + '' => [ 'connections' => [ - 'amqp' => [ - 'name' => 'amqp', + '' => [ + 'name' => '', 'exchange' => 'magento', 'disabled' => false ], @@ -79,9 +104,11 @@ The following sample introduces a runtime configuration that allows you to redef ] ], 'consumers' => [ - 'product_action_attribute.update' => [ - 'connection' => 'amqp', - ], - ], + '' => [ + 'connection' => '', + ] + ] ], ``` + +For example, to switch the `product_action_attribute.update` topic to RabbitMQ, use `amqp-magento` as the publisher and `amqp` as the connection name. diff --git a/src/pages/development/components/message-queues/migration.md b/src/pages/development/components/message-queues/migration.md index ee5a47094..9a9a1c2e3 100644 --- a/src/pages/development/components/message-queues/migration.md +++ b/src/pages/development/components/message-queues/migration.md @@ -1,20 +1,217 @@ --- -title: Migrate Configuration | Commerce PHP Extensions -description: Use these examples to migrate your message queue configuration between 2.x versions of Adobe Commerce and Magento Open Source. +title: Migrate message queue configuration +description: Learn how to migrate message queue configuration between Adobe Commerce versions, including support for RabbitMQ (AMQP) and ActiveMQ Artemis (STOMP). keywords: - Configuration - - Extensions --- # Migrate message queue configuration -## Migrate from 2.1 to 2.2 +This guide provides migration instructions for message queue configuration across Adobe Commerce versions. Use these examples to update your `env.php` and XML configuration files when upgrading. + +## Migrate from 2.4.4 to 2.4.5+ + +Adobe Commerce 2.4.5 and later versions support Apache ActiveMQ Artemis (STOMP) as an alternative message broker to RabbitMQ (AMQP). When upgrading from 2.4.4 or earlier, you can continue using RabbitMQ or migrate to ActiveMQ Artemis. + +### Key changes in 2.4.5+ + +- **ActiveMQ Artemis (STOMP) support**—New message broker option alongside RabbitMQ +- **Extended dynamic connection detection**—Supports STOMP in addition to AMQP +- **Enhanced SSL configuration**—Improved SSL options for both brokers +- **Multiple named connections**—Configure multiple broker connections simultaneously + +For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers. + +### Configuration File Changes + +The following table shows the key differences between 2.4.4 and 2.4.5+ configurations: + +| Configuration Area | 2.4.4 | 2.4.5+ | +| ------------------ | ----- | ------ | +| `env.php` default_connection | Optional when single broker configured | Optional when single broker configured; required when multiple brokers (can be `'amqp'`, `'stomp'`, or `'db'`) | +| `env.php` broker configuration | RabbitMQ (AMQP) only | RabbitMQ (AMQP) and/or ActiveMQ Artemis (STOMP) | +| `queue_consumer.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.5+) | +| `queue_publisher.xml` connection element | Optional for AMQP, supports multiple connections | Optional for AMQP/STOMP, enhanced multiple connections | +| `queue_topology.xml` connection attribute | Optional (auto-detected from env.php) | Optional (auto-detected, now includes STOMP in 2.4.5+) | + +### Update `env.php` Configuration + +**For RabbitMQ (AMQP) - No Changes Required:** + +```php +'queue' => [ + 'amqp' => [ + 'host' => 'rabbitmq.example.com', + 'port' => '5672', + 'user' => 'magento', + 'password' => 'magento', + 'virtualhost' => '/', + 'ssl' => false + ] +] +``` + +**For ActiveMQ Artemis (STOMP):** + +```php +'queue' => [ + 'stomp' => [ + 'host' => 'activemq.example.com', + 'port' => '61613', + 'user' => 'artemis', + 'password' => 'artemis', + 'ssl' => false + ] +] +``` + +**For both brokers (requires `default_connection`):** + +```php +'queue' => [ + 'default_connection' => 'amqp', // Required when multiple brokers are configured + 'amqp' => [ + 'host' => 'rabbitmq.example.com', + 'port' => '5672', + 'user' => 'magento', + 'password' => 'magento', + 'virtualhost' => '/', + 'ssl' => false + ], + 'stomp' => [ + 'host' => 'activemq.example.com', + 'port' => '61613', + 'user' => 'artemis', + 'password' => 'artemis', + 'ssl' => false + ] +] +``` + + + +The `default_connection` parameter is required only when multiple brokers are configured. When only one broker is configured, the system uses it automatically. The `connection` attribute in XML configuration files is optional—omit it to use the default broker, or specify `connection="amqp"` or `connection="stomp"` to force a specific broker. + +### Update `queue_consumer.xml` files + +All `` attributes (`name`, `queue`, `handler`, `consumerInstance`, `maxMessages`) remain unchanged. The only difference is the `connection` attribute: + +| Attribute | Change in 2.4.5+ | +| --- | --- | +| `connection` | Now also supports `stomp` value. Optional in both versions—auto-detected from `env.php`. Specify explicitly to force a specific broker. | + +**2.4.4 Example:** + +```xml + +``` + +**2.4.5+ Example (Uses default broker from env.php):** + +```xml + +``` + +**2.4.5+ Example (Explicitly specifies broker):** + +```xml + + + + + +``` + +### Update `queue_publisher.xml` files + +The `topic` and `disabled` attributes remain unchanged. Key differences in 2.4.5+: + +| Attribute | Change in 2.4.5+ | +| --- | --- | +| `/queue` | New attribute for ActiveMQ Artemis | +| `/name` | Can now specify `stomp` for ActiveMQ | +| `/exchange` | Not used with STOMP connections | +| `/disabled` | Enhanced support for multiple connections | + +**2.4.4 Example (RabbitMQ only):** + +```xml + + + +``` + +**2.4.5+ Example (RabbitMQ):** + +```xml + + + + +``` + +**2.4.5+ Example (ActiveMQ Artemis):** + +```xml + + + + +``` + +### Update `queue_topology.xml` files + +All `` and `` attributes (`name`, `type`, `durable`, `autoDelete`, `id`, `topic`, `destinationType`, `destination`) remain unchanged. The only difference is the `connection` attribute: + +| Attribute | Change in 2.4.5+ | +| --- | --- | +| `connection` | Now also supports `stomp` value. Optional in both versions—auto-detected from `env.php`. Specify explicitly to force a specific broker. | + +**2.4.4 Example:** + +```xml + + + +``` + +**2.4.5+ Example (Uses default broker from env.php):** + +```xml + + + +``` + +**2.4.5+ Example (Explicitly specifies broker):** + +```xml + + + + + + + + + +``` + + + +Connection detection is dynamic based on your `env.php` configuration. In 2.4.5+, this detection supports both AMQP and STOMP, allowing you to omit connection declarations in XML files. + +## Legacy migrations + +The following sections document migration paths for older Adobe Commerce versions. These are provided for reference when upgrading from legacy installations. + +### Migrate from 2.1 to 2.2 To upgrade the message queues for Adobe Commerce or Magento Open Source 2.1, you must create the following files in the `/etc` directory for each module that will use the message queue framework. -* `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. -* `queue_topology.xml`- Defines the message routing rules and declares queues and exchanges. -* `queue_publisher.xml` - Defines the exchange where a topic is published. +- `queue_consumer.xml`—Defines the relationship between an existing queue and its consumer. +- `queue_topology.xml`—Defines the message routing rules and declares queues and exchanges. +- `queue_publisher.xml`—Defines the exchange where a topic is published. The existing `queue.xml` file is deprecated. @@ -24,102 +221,90 @@ For complete details about these files, see [Configure message queues](configura The Adobe Commerce and Magento Open Source 2.1 `communication.xml` file has not changed for Adobe Commerce and Magento Open Source 2.2. -### Create the `queue_consumer.xml` file - -The first column in the following table lists the all the parameters in the `queue_consumer.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.1 `queue.xml` file the equivalent parameters are located. +#### Create the `queue_consumer.xml` file -| 2.2 Attribute | 2.1 queue.xml source | -| ---------------- | ----------- | -`/name` | `//consumer` -`/queue` | `//name` -`/handler` | `//handler` -`/consumerInstance` | `//consumerInstance` -`/connection` | `/type` -`/maxMessages` | `//maxMessages` +| 2.2 Attribute | 2.1 queue.xml source | +| --- | --- | +| `/name` | `//consumer` | +| `/queue` | `//name` | +| `/handler` | `//handler` | +| `/consumerInstance` | `//consumerInstance` | +| `/connection` | `/type` | +| `/maxMessages` | `//maxMessages` | -### Create the `queue_topology.xml` file +#### Create the `queue_topology.xml` file -The first column in the following table lists the all the parameters in the `queue_topology.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.1 `queue.xml` file the equivalent parameters are located. +| 2.2 Attribute | 2.1 queue.xml source | +| --- | --- | +| `/name` | `/exchange` | +| `/type` | Not present in 2.1. Set this value to `topic`. | +| `/connection` | `/type` | +| `/durable` | Not present in 2.1. Omit this parameter to accept the default value. | +| `/autoDelete` | Not present in 2.1. Omit this parameter to accept the default value. | +| `/internal` | Not present in 2.1. Omit this parameter to accept the default value. | +| `//id` | Not present in 2.1. Concatenate the 2.1 exchange name, topic name, and queue name to create a value for the `id` parameter. | +| `//topic` | `/topic` | +| `//destinationType` | Not present in 2.1. This value must be set to `queue`. | +| `//destination` | `//name` | +| `//disabled` | Not present in 2.1. Omit this parameter to accept the default value. | +| `/` and `//` | Not present in 2.1. Omit this element. | -| 2.2 Attribute | 2.1 queue.xml source | -| ---------------- | -----------| -`/name` | `/exchange` -`/type` | Not present in 2.1. Set this value to `topic`. -`/connection` | `/type` -`/durable` | Not present in 2.1. Omit this parameter to accept the default value. -`/autoDelete` | Not present in 2.1. Omit this parameter to accept the default value. -`/internal` | Not present in 2.1. Omit this parameter to accept the default value. -`//id` | Not present in 2.1. It is recommended that you concatenate the 2.1 exchange name, topic name, and queue name to create a value for the `id` parameter. -`//topic` | `/topic` -`//destinationType` | Not present in 2.1. This value must be set to `queue`. -`//destination` | `//name` -`//disabled` | Not present in 2.1. Omit this parameter to accept the default value. -`/` and `//` | Not present in 2.1. Omit this element. +#### Create the `queue_publisher.xml` file -### Create the `queue_publisher.xml` file +| 2.2 Attribute | 2.1 queue.xml source | +| --- | --- | +| `/topic` | `/topic` | +| `/disabled` | Not present in 2.1. Omit this parameter to accept the default value. | +| `//name` | `/type` | +| `//exchange` | `/exchange` | +| `//disabled` | Not present in 2.1. Omit this parameter to accept the default value. | -The first column in the following table lists the all the parameters in the `queue_publisher.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.1 `queue.xml` file the equivalent parameters are located. - -| 2.2 Attribute | 2.1 queue.xml source | -| ---------------- | ----------- | -`/topic` | `/topic` -`/disabled` | Not present in 2.1. Omit this parameter to accept the default value. -`//name` | `/type` -`//exchange` | `exchange` -`//disabled` | Not present in 2.1. Omit this parameter to accept the default value. - -## Migrate from 2.0 to 2.2 +### Migrate from 2.0 to 2.2 To upgrade from Adobe Commerce or Magento Open Source 2.0, you must create the following files in the `/etc` directory for each module that will use the message queue framework. -* `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. -* `queue_topology.xml`- Defines the message routing rules. -* `queue_publisher.xml` - Defines the relationship between a topic and its publisher. +- `queue_consumer.xml` - Defines the relationship between an existing queue and its consumer. +- `queue_topology.xml`—Defines the message routing rules. +- `queue_publisher.xml`—Defines the relationship between a topic and its publisher. The existing `queue.xml` file is deprecated. For complete details about these files, see [Configure message queues](configuration.md) -### Create the `queue_consumer.xml` file - -The first column in the following table lists the all the parameters in the `queue_consumer.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.0 `queue.xml` file the equivalent parameters are located. - -2.2 Attribute | 2.0 queue.xml Source ----------------- | ----------- -`/name` | `/name` -`/queue` | `/queue` -`/handler` | Use the values from `/class` and `/method` in the format `\Module\::`. -`/consumerInstance` | `/executor` -`/connection` | `/connection` -`/maxMessages` | `/max_messages` - -### Create the `queue_topology.xml` file - -The first column in the following table lists the all the parameters in the `queue_topology.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.0 `queue.xml` file the equivalent parameters are located. - -| 2.2 Attribute | 2.0 queue.xml Source | -| ---------------- | -----------| -`/name` | `/exchange` -`/type` | Not present in 2.0. Set this value to `topic`. -`/connection` | `/connection` -`/durable` | Not present in 2.0. Omit this parameter to accept the default value. -`/autoDelete` | Not present in 2.0. Omit this parameter to accept the default value. -`/internal` | Not present in 2.0. Omit this parameter to accept the default value. -`//id` | Not present in 2.0. It is recommended that you concatenate the 2.1 exchange name, topic name, and queue name to create a value for the `id` parameter. -`//topic` | `/topic` -`//destinationType` | Not present in 2.0. This value must be set to `queue`. -`//destination` | `/queue` -`//disabled` | Not present in 2.0. Omit this parameter to accept the default value. -`` | Not present in 2.0. Omit this element. - -### Create the `queue_publisher.xml` file - -The first column in the following table lists the all the parameters in the `queue_publisher.xml` file. The second column lists where in the Adobe Commerce and Magento Open Source 2.0 `queue.xml` file the equivalent parameters are located. - -| 2.2 Attribute | 2.0 queue.xml Source | -| ---------------- | ----------- | -`/topic` | `/name` -`/disabled` | Not present in 2.0. Omit this parameter to accept the default value. -`//name` | `/connection` -`//exchange` | `/exchange` -`//disabled` | Not present in 2.0. Omit this parameter to accept the default value. +#### Create the `queue_consumer.xml` file + +| 2.2 Attribute | 2.0 queue.xml source | +| --- | --- | +| `/name` | `/name` | +| `/queue` | `/queue` | +| `/handler` | Use the values from `/class` and `/method` in the format `\Module\::`. | +| `/consumerInstance` | `/executor` | +| `/connection` | `/connection` | +| `/maxMessages` | `/max_messages` | + +#### Create the `queue_topology.xml` file + +| 2.2 Attribute | 2.0 queue.xml source | +| --- | --- | +| `/name` | `/exchange` | +| `/type` | Not present in 2.0. Set this value to `topic`. | +| `/connection` | `/connection` | +| `/durable` | Not present in 2.0. Omit this parameter to accept the default value. | +| `/autoDelete` | Not present in 2.0. Omit this parameter to accept the default value. | +| `/internal` | Not present in 2.0. Omit this parameter to accept the default value. | +| `//id` | Not present in 2.0. Concatenate the exchange name, topic name, and queue name to create a value for the `id` parameter. | +| `//topic` | `/topic` | +| `//destinationType` | Not present in 2.0. This value must be set to `queue`. | +| `//destination` | `/queue` | +| `//disabled` | Not present in 2.0. Omit this parameter to accept the default value. | +| `` | Not present in 2.0. Omit this element. | + +#### Create the `queue_publisher.xml` file + +| 2.2 Attribute | 2.0 queue.xml source | +| --- | --- | +| `/topic` | `/name` | +| `/disabled` | Not present in 2.0. Omit this parameter to accept the default value. | +| `//name` | `/connection` | +| `//exchange` | `/exchange` | +| `//disabled` | Not present in 2.0. Omit this parameter to accept the default value. |