4.21.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、BrokerB、BrokerB 和 BrokerC ）的链，在 BrokerA 和消费者在 BrokerC 上有一个消费者。在这种情况下，您希望 BrokerB 重新将消费者重新变为 BrokerA。

   Priority-adjustment

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

   transformer-ref

   转换器配置的名称。如果要在联合消息传输过程中转换信息，可以添加转换器配置。此流程稍后会描述转换器配置。

4. 在 <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">
   
               <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 属性匹配的任何 队列。在这种情况下，所有以字符串 .local 结尾的队列都将被排除。这表明某些队列保留为本地队列，而不是联合。

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

   <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 策略的 transformer-ref 属性的值。

   class-name

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

   转换器的 transform（） 方法会在消息被传输之前通过消息调用。这可让您在联合邮件标头或正文前转换该邮件标头或正文。

   属性

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

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 和 eu-west-1 的上游代理。

   user

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

   password

   创建到上游代理的连接时使用的密码。如果未指定，则使用 federation 元素配置中指定的共享密码。

   call-failover-timeout

   与 call-timeout 类似，但在进行故障转移尝试时使用了调用。默认值为 -1，这表示超时被禁用。

   call-timeout

   时间，以毫秒为单位，在传输一个阻塞调用的数据包时，联合连接会等待来自远程代理的回复。如果此时间过长，连接会引发异常。默认值为 30000。

   check-period

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

   circuit-breaker-timeout

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

   connection-ttl

   如果连接停止从远程代理接收信息，则持续时间（以毫秒为单位）。默认值为 60000。

   discovery-group-ref

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

   ha

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

   initial-connect-attempts

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

   max-retry-interval

   在连接到远程代理时，后续重新连接尝试间最大时间（以毫秒为单位）。默认值为 2000。

   reconnect-attempts

   如果连接失败，下游代理会尝试重新连接到上游代理的次数。如果在不重新建立连接的情况下达到这个值，则上游代理会被永久离线。downstream 代理不再将消息路由到上游代理。默认值为 -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>