4.21.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 可按需侦听绑定。如果一个与地址策略包含的地址匹配的地址有 movert 绑定，则与 movert 转发地址匹配的任何队列绑定都将创建需要。默认值为：false。

   max-hops

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

   transformer-ref

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

4. 在 <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">
   
               <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 属性值指定要包含在地址策略中的地址。您可以指定准确的地址，例如 queue.bbc.new 或 queue.usatoday。或者，您可以使用通配符表达式来指定 一组 匹配的地址。在前面的示例中，地址策略还包括以字符串 queue.news 开头的所有地址名称。

   exclude

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

5. （可选）使用 federation 元素，添加 transformer 元素来引用自定义转换器实施。例如：

   <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

   转换器配置的名称。这个名称在本地代理上必须是唯一的。这是您指定为地址策略的 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-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 和 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>