4.22.8. 配置上游队列联合

流程

1. 打开 <broker_instance_dir>/etc/broker.xml 配置文件。

2. 在新的 <federations> 元素中，添加一个 <federation> 元素。例如：

   <federations>
     <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
     </federation>
   </federations>

   name

   联合配置的名称。在本例中，名称对应于下游代理的名称。

   user

   用于连接到上游代理的共享用户名。

   password

   用于连接到上游代理的共享密码。

   注意
   • 如果上游代理的用户名和密码凭证不同，您可以在将这些代理添加到配置时为这些代理单独指定凭证。这个步骤稍后会对此进行说明。

3. 在 federation 元素 中添加 <queue-policy> 元素。指定 <queue-policy> 元素的属性值。例如：

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
           </queue-policy>
   
       </federation>
   </federations>

   name

   队列策略的名称。代理上配置的所有队列策略都必须具有唯一的名称。

   include-federated

   当此属性的值设为 false 时，配置不会重新使已经有生动的消费者（即联合队列中的消费者）。这可避免在对称或闭环拓扑中，没有非动态使用者，并且系统中无无源地流动消息的情况。

   如果没有 闭环拓扑，您可以将此属性的值设置为 true。例如，假设您有一个由三个代理（ BrokerA、Broker B 和 BrokerC ）组成的链，位于 BrokerA 的生产者和 BrokerC。在这种情况下，您需要 BrokerB 将 消费者更新为 BrokerA。

   priority-adjustment

   当消费者连接到队列时，将在创建上游（ 联合）消费者时使用其优先级。联合消费者的优先级通过 优先级调整属性的值调整。此属性的默认值为 -1，可确保在负载平衡期间本地使用者优先于联合消费者。但是，您可以根据需要更改优先级调整的值。

   transformer-ref

   转换器配置的名称。如果要在联合消息传输过程中转换消息，您可以添加转换器配置。此流程稍后将介绍转换器配置。

4. 在 <queue-policy> 元素中，添加 address-matching 模式，以从队列策略中包含和排除地址。例如：

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
       </federation>
   </federations>

   Include

   此元素的 address-match 属性的值指定要包含在队列策略中的地址。您可以指定一个精确的地址，如 queue. bbc.new 或 queue.usatoday。或者，您可以使用通配符表达式来指定匹配的地址 集合。在前面的示例中，队列策略还包含以字符串 queue.news 开头的 所有 地址名称。

   与 address-match 属性相结合，您可以使用 queue-match 属性在队列策略中包含这些地址上的特定队列。与 address-match 属性一样，您可以指定确切的队列名称，也可以使用通配符表达式来指定 一组 队列。在前面的示例中，数字符号(#)通配符字符表示每个地址或地址集合中 的所有 队列都包含在队列策略中。

   exclude

   此元素的 address-match 属性的值指定要从队列策略中排除的地址。您可以指定精确的地址或使用通配符表达式来指定匹配的地址 集合。在前面的示例中，编号符号(#)通配符字符表示将排除 与所有 地址 中的 queue-match 属性匹配 的任何 队列。在这种情况下，任何以 string .local 结尾的队列都将被排除。这表示特定队列保留为本地队列，而不是联合。

5. 在 联合 元素中，添加一个转换 器 元素来引用自定义转换器实施。例如：

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.foo.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   name

   转换器配置的名称。这个名称在相关的代理中必须是唯一的。您可以将此名称指定为 address 策略的 converter-ref 属性的值。

   class-name

   实施 org.apache.activemq.artemis.core.server.transformer.Transformer 接口的用户定义的类的名称。

   转换器的 transformation （） 方法通过消息调用，然后再传输消息。这可让您在联合之前转换邮件标题或正文。

   属性

   用于保存特定转换器配置的键值对。

6. 在 federation 元素中添加一个或多个 上游 元素。每个 上游 元素定义上游代理连接以及应用到该连接的策略。例如：

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <upstream name="eu-east-1">
               <static-connectors>
                   <connector-ref>eu-east-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-queue-federation"/>
           </upstream>
   
           <upstream name="eu-west-1" >
               <static-connectors>
                   <connector-ref>eu-west-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-queue-federation"/>
           </upstream>
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.foo.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   static-connectors

   包含一组 connector -ref 元素，这些元素引用在本地代理的 broker.xml 配置文件里其他位置定义的 连接器 元素。连接器定义用于传出连接的传输（TCP、SSL、HTTP 等）和服务器连接参数（主机、端口等）。此流程的以下步骤演示了如何添加由联合队列配置 的静态连接器元素 引用的连接器。

   policy-ref

   应用于上游代理的下游代理上配置的队列策略的名称。

   您可以为 上游 元素指定的附加选项如下所述：

   name

   上游代理配置的名称。在本例中，名称与名为 eu-east-1 and eu-west-1 的上游代理对应。

   user

   创建与上游代理连接时使用的用户名。如果没有指定，则使用在联合 元素 配置中指定的共享用户名。

   password

   创建与上游代理连接时使用的密码。如果没有指定，则使用在联合 元素 配置中指定的共享密码。

   call-failover-timeout

   与 call-timeout 类似，但在故障切换尝试期间使用调用时。默认值为 -1，这意味着禁用了超时。

   call-timeout

   当联合连接传输阻止调用的数据包时，以毫秒为单位等待来自远程代理的回复。如果这一次到期，连接会引发异常。默认值为 30000。

   check-period

   本地代理发送到远程代理以毫秒为单位的连续"keep-alive"消息之间的时间间隔，以检查联合连接的健康状态。如果联合连接健康，远程代理会响应每个 keep-alive 消息。如果连接不健康，则当下游代理无法从上游代理接收响应时，可以使用称为 断路器 的机制来阻止联合消费者。如需更多信息，请参阅 断路器-timeout 参数的说明。check-period 参数的默认值为 30000。

   circuit-breaker-timeout

   下游和上游代理之间的单一连接可能很多联合队列和地址消费者共享。如果代理间的连接丢失，每个联合消费者可能会尝试同时重新连接。为避免这种情况，称为 断路 器的机制会阻止使用者。当指定的超时值 elapes 时，断路器重新尝试连接。如果成功，用户将不再受阻。否则，断路器将再次应用。

   connection-ttl

   如果联合连接停止从远程代理接收消息，则联合连接以毫秒为单位。默认值为 60000。

   discovery-group-ref

   作为为与上游代理的连接定义静态连接器的替代方案，此元素可用于指定在 broker.xml 配置文件中已在其他位置配置的发现组。特别是，您要将现有发现组指定为此元素的 discovery-group-name 属性的值。有关发现组的详情请参考 第 14.1.5 节 “代理发现方法”。

   ha

   指定是否为与上游代理的连接启用高可用性。如果此参数的值设为 true，本地代理可以连接到上游集群中的任何可用代理，并在实时上游代理关闭时自动切换到备份代理。默认值为 false。

   initial-connect-attempts

   下游代理将连接上游代理的初始尝试次数。如果在没有建立连接的情况下达到这个值，上游代理会永久离线。下游代理不再将消息路由到上游代理。默认值为 -1，这意味着没有限制。

   max-retry-interval

   当与远程代理连接失败时，后续重新连接尝试之间最长的时间（毫秒）。默认值为 2000。

   reconnect-attempts

   如果连接失败，下游代理将尝试重新连接到上游代理的次数。如果在没有重新建立连接的情况下达到这个值，上游代理会永久离线。下游代理不再将消息路由到上游代理。默认值为 -1，这意味着没有限制。

   retry-interval

   如果与远程代理的连接失败，则在后续重新连接尝试之间，以毫秒为单位。默认值为 500。

   retry-interval-multiplier

   应用于 retry-interval 参数值的倍数。默认值为 1。

   share-connection

   如果为同一代理同时配置了下游和上游连接，则共享相同的连接，只要下游和上游配置都将该参数的值设置为 true。默认值为 false。

7. 在本地代理中，将连接器添加到远程代理中。这些是您联合地址配置 的静态连接器元素 中引用的连接器。例如：

   <connectors>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>