4.22.5. 配置上游地址联合

流程

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

2. 添加一个包含 <federation> 元素的新 <federations > 元素。例如：

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

   name

   联合配置的名称。在这个示例中，名称对应于本地代理的名称。

   user

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

   password

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

   注意

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

3. 在 federation 元素 中添加 <address-policy> 元素。例如：

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
           </address-policy>
   
       </federation>
   </federations>

   name

   地址策略的名称。代理上配置的所有地址策略必须具有唯一的名称。

   auto-delete

   在地址联合期间，本地代理会在远程地址上动态创建持久队列。auto-delete 属性的值指定一旦本地代理断开连接并且也达到了 auto-delete- delay 和 auto-delete- message-count 属性的值，是否应删除 远程队列。如果要自动清理动态创建的队列，这个选项非常有用。如果您想在本地代理长时间断开连接时防止在本地代理上构建信息，则这个选项也非常有用。但是，如果您希望信息始终在断开连接时一直为本地代理排队，您可以把这个选项设置为 false，以避免本地代理上的信息丢失。

   auto-delete-delay

   本地代理断开连接后，此属性的值指定在动态创建的远程队列有资格自动删除前，以毫秒为单位。

   auto-delete-message-count

   断开本地代理后，此属性的值指定在该队列有资格自动删除前仍可在动态创建的远程队列中的最大消息数。

   enable-divert-bindings

   将此属性设置为 true 可根据需求侦听此绑定。如果存在带有与地址策略所包含地址匹配的地址转换的绑定，则任何与转义地址的转发地址匹配的队列绑定都将产生需求。默认值为 false。

   max-hops

   消息在联合期间可以做出的最大跃点数。特定的拓扑需要此属性的特定值。要了解更多有关这些要求的信息，请参阅 第 4.22.2 节 “地址联合的通用拓扑”。

   transformer-ref

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

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

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
       </federation>
   </federations>

   Include

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

   exclude

   此元素的 address-match 属性的值指定要从 address 策略中排除的地址。您可以指定确切的地址名称，或者使用通配符表达式来指定匹配的地址 集合。在上例中，address 策略排除以字符串 queue.news.sport 开头的 所有 地址名称。

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

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-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

   转换器配置的名称。这个名称在本地代理中必须是唯一的。这是您指定为地址策略 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-address-federation"/>
           </upstream>
   
           <upstream name="eu-west-1" >
               <static-connectors>
                   <connector-ref>eu-west-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-address-federation"/>
           </upstream>
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-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 等）和服务器连接参数（主机、端口等）。此流程的下一步演示了如何添加 static-connectors 元素中引用的连接器。

   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>