Google Git
Sign in
apache / activemq-website / e4f487fff764263c37e753b31f00d784ed2ba3ad / . / content / components / artemis / documentation / 2.11.0 / federation-queue.html
blob: 0fa12b4506bddb943e00f6c5130b19bdb821725e [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="" >
<head>
<meta charset="UTF-8">
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<title>Queue Federation ยท ActiveMQ Artemis Documentation</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="description" content="">
<meta name="generator" content="GitBook 3.2.3">
<link rel="stylesheet" href="gitbook/style.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">
<meta name="HandheldFriendly" content="true"/>
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
<link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">
<link rel="next" href="ha.html" />
<link rel="prev" href="federation-address.html" />
</head>
<body>
<div class="book">
<div class="book-summary">
<div id="book-search-input" role="search">
<input type="text" placeholder="Type to search" />
</div>
<nav role="navigation">
<ul class="summary">
<li class="chapter " data-level="1.1" data-path="./">
<a href="./">
Introduction
</a>
</li>
<li class="chapter " data-level="1.2" data-path="notice.html">
<a href="notice.html">
Legal Notice
</a>
</li>
<li class="chapter " data-level="1.3" data-path="preface.html">
<a href="preface.html">
Preface
</a>
</li>
<li class="chapter " data-level="1.4" data-path="project-info.html">
<a href="project-info.html">
Project Info
</a>
</li>
<li class="chapter " data-level="1.5" data-path="versions.html">
<a href="versions.html">
Versions
</a>
</li>
<li class="chapter " data-level="1.6" data-path="messaging-concepts.html">
<a href="messaging-concepts.html">
Messaging Concepts
</a>
</li>
<li class="chapter " data-level="1.7" data-path="architecture.html">
<a href="architecture.html">
Architecture
</a>
</li>
<li class="chapter " data-level="1.8" data-path="using-server.html">
<a href="using-server.html">
Using the Server
</a>
</li>
<li class="chapter " data-level="1.9" data-path="upgrading.html">
<a href="upgrading.html">
Upgrading
</a>
</li>
<li class="chapter " data-level="1.10" data-path="address-model.html">
<a href="address-model.html">
Address Model
</a>
</li>
<li class="chapter " data-level="1.11" data-path="protocols-interoperability.html">
<a href="protocols-interoperability.html">
Protocols and Interoperability
</a>
</li>
<li class="chapter " data-level="1.12" data-path="amqp.html">
<a href="amqp.html">
AMQP
</a>
</li>
<li class="chapter " data-level="1.13" data-path="mqtt.html">
<a href="mqtt.html">
MQTT
</a>
</li>
<li class="chapter " data-level="1.14" data-path="stomp.html">
<a href="stomp.html">
STOMP
</a>
</li>
<li class="chapter " data-level="1.15" data-path="openwire.html">
<a href="openwire.html">
OpenWire
</a>
</li>
<li class="chapter " data-level="1.16" data-path="core.html">
<a href="core.html">
Core
</a>
</li>
<li class="chapter " data-level="1.17" data-path="jms-core-mapping.html">
<a href="jms-core-mapping.html">
Mapping JMS Concepts to the Core API
</a>
</li>
<li class="chapter " data-level="1.18" data-path="using-jms.html">
<a href="using-jms.html">
Using JMS
</a>
</li>
<li class="chapter " data-level="1.19" data-path="client-classpath.html">
<a href="client-classpath.html">
The Client Classpath
</a>
</li>
<li class="chapter " data-level="1.20" data-path="examples.html">
<a href="examples.html">
Examples
</a>
</li>
<li class="chapter " data-level="1.21" data-path="wildcard-routing.html">
<a href="wildcard-routing.html">
Routing Messages With Wild Cards
</a>
</li>
<li class="chapter " data-level="1.22" data-path="wildcard-syntax.html">
<a href="wildcard-syntax.html">
Wildcard Syntax
</a>
</li>
<li class="chapter " data-level="1.23" data-path="filter-expressions.html">
<a href="filter-expressions.html">
Filter Expressions
</a>
</li>
<li class="chapter " data-level="1.24" data-path="persistence.html">
<a href="persistence.html">
Persistence
</a>
</li>
<li class="chapter " data-level="1.25" data-path="configuring-transports.html">
<a href="configuring-transports.html">
Configuring Transports
</a>
</li>
<li class="chapter " data-level="1.26" data-path="config-reload.html">
<a href="config-reload.html">
Configuration Reload
</a>
</li>
<li class="chapter " data-level="1.27" data-path="connection-ttl.html">
<a href="connection-ttl.html">
Detecting Dead Connections
</a>
</li>
<li class="chapter " data-level="1.28" data-path="slow-consumers.html">
<a href="slow-consumers.html">
Detecting Slow Consumers
</a>
</li>
<li class="chapter " data-level="1.29" data-path="network-isolation.html">
<a href="network-isolation.html">
Avoiding Network Isolation
</a>
</li>
<li class="chapter " data-level="1.30" data-path="critical-analysis.html">
<a href="critical-analysis.html">
Detecting Broker Issues (Critical Analysis)
</a>
</li>
<li class="chapter " data-level="1.31" data-path="transaction-config.html">
<a href="transaction-config.html">
Resource Manager Configuration
</a>
</li>
<li class="chapter " data-level="1.32" data-path="flow-control.html">
<a href="flow-control.html">
Flow Control
</a>
</li>
<li class="chapter " data-level="1.33" data-path="send-guarantees.html">
<a href="send-guarantees.html">
Guarantees of sends and commits
</a>
</li>
<li class="chapter " data-level="1.34" data-path="undelivered-messages.html">
<a href="undelivered-messages.html">
Message Redelivery and Undelivered Messages
</a>
</li>
<li class="chapter " data-level="1.35" data-path="message-expiry.html">
<a href="message-expiry.html">
Message Expiry
</a>
</li>
<li class="chapter " data-level="1.36" data-path="large-messages.html">
<a href="large-messages.html">
Large Messages
</a>
</li>
<li class="chapter " data-level="1.37" data-path="paging.html">
<a href="paging.html">
Paging
</a>
</li>
<li class="chapter " data-level="1.38" data-path="scheduled-messages.html">
<a href="scheduled-messages.html">
Scheduled Messages
</a>
</li>
<li class="chapter " data-level="1.39" data-path="last-value-queues.html">
<a href="last-value-queues.html">
Last-Value Queues
</a>
</li>
<li class="chapter " data-level="1.40" data-path="ring-queues.html">
<a href="ring-queues.html">
Ring Queues
</a>
</li>
<li class="chapter " data-level="1.41" data-path="retroactive-addresses.html">
<a href="retroactive-addresses.html">
Retroactive Addresses
</a>
</li>
<li class="chapter " data-level="1.42" data-path="exclusive-queues.html">
<a href="exclusive-queues.html">
Exclusive Queues
</a>
</li>
<li class="chapter " data-level="1.43" data-path="message-grouping.html">
<a href="message-grouping.html">
Message Grouping
</a>
</li>
<li class="chapter " data-level="1.44" data-path="consumer-priority.html">
<a href="consumer-priority.html">
Consumer Priority
</a>
</li>
<li class="chapter " data-level="1.45" data-path="pre-acknowledge.html">
<a href="pre-acknowledge.html">
Extra Acknowledge Modes
</a>
</li>
<li class="chapter " data-level="1.46" data-path="management.html">
<a href="management.html">
Management
</a>
</li>
<li class="chapter " data-level="1.47" data-path="management-console.html">
<a href="management-console.html">
Management Console
</a>
</li>
<li class="chapter " data-level="1.48" data-path="metrics.html">
<a href="metrics.html">
Metrics
</a>
</li>
<li class="chapter " data-level="1.49" data-path="security.html">
<a href="security.html">
Security
</a>
</li>
<li class="chapter " data-level="1.50" data-path="masking-passwords.html">
<a href="masking-passwords.html">
Masking Passwords
</a>
</li>
<li class="chapter " data-level="1.51" data-path="broker-plugins.html">
<a href="broker-plugins.html">
Broker Plugins
</a>
</li>
<li class="chapter " data-level="1.52" data-path="resource-limits.html">
<a href="resource-limits.html">
Resource Limits
</a>
</li>
<li class="chapter " data-level="1.53" data-path="jms-bridge.html">
<a href="jms-bridge.html">
The JMS Bridge
</a>
</li>
<li class="chapter " data-level="1.54" data-path="client-reconnection.html">
<a href="client-reconnection.html">
Client Reconnection and Session Reattachment
</a>
</li>
<li class="chapter " data-level="1.55" data-path="diverts.html">
<a href="diverts.html">
Diverting and Splitting Message Flows
</a>
</li>
<li class="chapter " data-level="1.56" data-path="core-bridges.html">
<a href="core-bridges.html">
Core Bridges
</a>
</li>
<li class="chapter " data-level="1.57" data-path="transformers.html">
<a href="transformers.html">
Transformers
</a>
</li>
<li class="chapter " data-level="1.58" data-path="duplicate-detection.html">
<a href="duplicate-detection.html">
Duplicate Message Detection
</a>
</li>
<li class="chapter " data-level="1.59" data-path="clusters.html">
<a href="clusters.html">
Clusters
</a>
</li>
<li class="chapter " data-level="1.60" data-path="federation.html">
<a href="federation.html">
Federation
</a>
<ul class="articles">
<li class="chapter " data-level="1.60.1" data-path="federation-address.html">
<a href="federation-address.html">
Address Federation
</a>
</li>
<li class="chapter active" data-level="1.60.2" data-path="federation-queue.html">
<a href="federation-queue.html">
Queue Federation
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="1.61" data-path="ha.html">
<a href="ha.html">
High Availability and Failover
</a>
</li>
<li class="chapter " data-level="1.62" data-path="graceful-shutdown.html">
<a href="graceful-shutdown.html">
Graceful Server Shutdown
</a>
</li>
<li class="chapter " data-level="1.63" data-path="libaio.html">
<a href="libaio.html">
Libaio Native Libraries
</a>
</li>
<li class="chapter " data-level="1.64" data-path="thread-pooling.html">
<a href="thread-pooling.html">
Thread management
</a>
</li>
<li class="chapter " data-level="1.65" data-path="web-server.html">
<a href="web-server.html">
Embedded Web Server
</a>
</li>
<li class="chapter " data-level="1.66" data-path="logging.html">
<a href="logging.html">
Logging
</a>
</li>
<li class="chapter " data-level="1.67" data-path="rest.html">
<a href="rest.html">
REST Interface
</a>
</li>
<li class="chapter " data-level="1.68" data-path="embedding-activemq.html">
<a href="embedding-activemq.html">
Embedding the Broker
</a>
</li>
<li class="chapter " data-level="1.69" data-path="karaf.html">
<a href="karaf.html">
Apache Karaf
</a>
</li>
<li class="chapter " data-level="1.70" data-path="tomcat.html">
<a href="tomcat.html">
Apache Tomcat
</a>
</li>
<li class="chapter " data-level="1.71" data-path="spring-integration.html">
<a href="spring-integration.html">
Spring Integration
</a>
</li>
<li class="chapter " data-level="1.72" data-path="cdi-integration.html">
<a href="cdi-integration.html">
CDI Integration
</a>
</li>
<li class="chapter " data-level="1.73" data-path="intercepting-operations.html">
<a href="intercepting-operations.html">
Intercepting Operations
</a>
</li>
<li class="chapter " data-level="1.74" data-path="data-tools.html">
<a href="data-tools.html">
Data Tools
</a>
</li>
<li class="chapter " data-level="1.75" data-path="maven-plugin.html">
<a href="maven-plugin.html">
Maven Plugin
</a>
</li>
<li class="chapter " data-level="1.76" data-path="unit-testing.html">
<a href="unit-testing.html">
Unit Testing
</a>
</li>
<li class="chapter " data-level="1.77" data-path="perf-tuning.html">
<a href="perf-tuning.html">
Troubleshooting and Performance Tuning
</a>
</li>
<li class="chapter " data-level="1.78" data-path="configuration-index.html">
<a href="configuration-index.html">
Configuration Reference
</a>
</li>
<li class="divider"></li>
<li>
<a href="https://www.gitbook.com" target="blank" class="gitbook-link">
Published with GitBook
</a>
</li>
</ul>
</nav>
</div>
<div class="book-body">
<div class="body-inner">
<div class="book-header" role="navigation">
<!-- Title -->
<h1>
<i class="fa fa-circle-o-notch fa-spin"></i>
<a href="." >Queue Federation</a>
</h1>
</div>
<div class="page-wrapper" tabindex="-1" role="main">
<div class="page-inner">
<div id="book-search-results">
<div class="search-noresults">
<section class="normal markdown-section">
<h1 id="queue-federation">Queue Federation</h1>
<h2 id="introduction">Introduction</h2>
<p>This feature provides a way of balancing the load of a single queue across remote brokers.</p>
<p>A federated queue links to other queues (called upstream queues). It will retrieve messages from upstream queues in order to satisfy demand for messages from local consumers.
The upstream queues do not need to be reconfigured and they do not have to be on the same broker or in the same cluster.</p>
<p>All of the configuration needed to establish the upstream links and the federated queue is in the downstream broker.</p>
<h3 id="use-cases">Use Cases</h3>
<p>This is not an exhaustive list of what you can do with and the benefits of federated queues, but simply some ideas.</p>
<ul>
<li><p>Higher capacity </p>
<p>By having a &quot;logical&quot; queue distributed over many brokers. Each broker would declare a federated queue with all the other federated queues upstream. (The links would form a complete bi-directional graph on n queues.)</p>
</li>
</ul>
<p>By having this a logical distributed queue is capable of having a much higher capacity than a single queue on a single broker.
When will perform best when there is some degree of locality.</p>
<p>e.g. as many messages as possible are consumed from the same broker as they were published to, where federation only needs to move messages around in order to perform load balancing.</p>
<p><img src="images/federated-queue-symmetric.gif" alt="Federated Queue"></p>
<ul>
<li><p>Supporting multi region or venue</p>
<p>In a multi region setup you may have producers in one region or venue and the consumer in another.
typically you want producers and consumer to keep their connections local to the region, in such as case you can deploy brokers in each region where producers and consumer are, and use federation to move messages over the WAN between regions.</p>
</li>
</ul>
<p><img src="images/federated-queue.gif" alt="Federated Queue"></p>
<ul>
<li><p>Communication between the secure enterprise lan and the DMZ.</p>
<p> Where a number of producer apps maybe in the DMZ and a number of consumer apps in the secure enterprise lan, it may not suitable to allow the producers to connect through to the broker in the secure enterprise lan. </p>
<p> In this scenario you could deploy a broker in the DMZ where the producers publish to, and then have the broker in the enterprise lan connect out to the DMZ broker and federate the queues so that messages can traverse. </p>
<p> This is similar to supporting multi region or venue.</p>
</li>
</ul>
<ul>
<li>Migrating between two clusters.
Consumers and publishers can be moved in any order and the messages won&apos;t be duplicated (which is the case if you do exchange federation). Instead, messages are transferred to the new cluster when your consumers are there.
Here for such a migration with blue/green or canary moving a number of consumers on the same queue, you may want to set the <code>priority-adjustment</code> to 0, or even a positive value, so message would actively flow to the federated queue.</li>
</ul>
<h2 id="configuring-queue-federation">Configuring Queue Federation</h2>
<p>Federation is configured in <code>broker.xml</code>.</p>
<p>Sample Queue Federation setup:</p>
<pre><code>&lt;federations&gt;
&lt;federation name=&quot;eu-north-1&quot; user=&quot;federation_username&quot; password=&quot;32a10275cf4ab4e9&quot;&gt;
&lt;upstream name=&quot;eu-east-1&quot;&gt;
&lt;static-connectors&gt;
&lt;connector-ref&gt;eu-east-connector1&lt;/connector-ref&gt;
&lt;connector-ref&gt;eu-east-connector1&lt;/connector-ref&gt;
&lt;/static-connectors&gt;
&lt;policy ref=&quot;news-queue-federation&quot;/&gt;
&lt;/upstream&gt;
&lt;upstream name=&quot;eu-west-1&quot; &gt;
&lt;static-connectors&gt;
&lt;connector-ref&gt;eu-west-connector1&lt;/connector-ref&gt;
&lt;connector-ref&gt;eu-west-connector1&lt;/connector-ref&gt;
&lt;/static-connectors&gt;
&lt;policy ref=&quot;news-queue-federation&quot;/&gt;
&lt;/upstream&gt;
&lt;queue-policy name=&quot;news-queue-federation&quot; priority-adjustment=&quot;-5&quot; include-federated=&quot;true&quot; transformer-ref=&quot;federation-transformer-3&quot;&gt;
&lt;include queue-match=&quot;#&quot; address-match=&quot;queue.bbc.new&quot; /&gt;
&lt;include queue-match=&quot;#&quot; address-match=&quot;queue.usatoday&quot; /&gt;
&lt;include queue-match=&quot;#&quot; address-match=&quot;queue.news.#&quot; /&gt;
&lt;exclude queue-match=&quot;#.local&quot; address-match=&quot;#&quot; /&gt;
&lt;/queue-policy&gt;
&lt;transformer name=&quot;news-transformer&quot;&gt;
&lt;class-name&gt;org.foo.NewsTransformer&lt;/class-name&gt;
&lt;property key=&quot;key1&quot; value=&quot;value1&quot;/&gt;
&lt;property key=&quot;key2&quot; value=&quot;value2&quot;/&gt;
&lt;/transformer&gt;
&lt;/federation&gt;
&lt;/federations&gt;
</code></pre><p>In the above setup downstream broker <code>eu-north-1</code> is configured to connect to two upstream brokers <code>eu-east-1</code> and <code>eu-east-2</code>, the credentials used for both connections to both brokers in this sample are shared, you can set user and password at the upstream level should they be different per upstream.</p>
<p>Both upstreams are configured with the same queue-policy <code>news-queue-federation</code>, that is selecting addresses which match any of the include criteria, but will exclude any queues that end with <code>.local</code>, keeping these as local queues only.</p>
<p><strong>It is important that federation name is globally unique.</strong></p>
<p>Let&apos;s take a look at all the <code>queue-policy</code> parameters in turn, in order of priority.</p>
<ul>
<li><p><code>name</code> attribute. All address-policies must have a unique name in the server.</p>
</li>
<li><p><code>include</code> the address-match pattern to whitelist addresses, multiple of these can be set. If none are set all addresses are matched.</p>
</li>
<li><p><code>exclude</code> the address-match pattern to blacklist addresses, multiple of these can be set.</p>
</li>
<li><p><code>priority-adjustment</code> when a consumer attaches its priority is used to make the upstream consumer,
but with an adjustment by default -1, so that local consumers get load balanced first over remote, this enables this to be configurable should it be wanted/needed. </p>
</li>
<li><p><code>include-federated</code> by default this is false, we dont federate a federated consumer, this is to avoid issue, where in symmetric or any closed loop setup you could end up when no &quot;real&quot; consumers attached with messages flowing round and round endlessly. </p>
<p> There is though a valid case that if you dont have a close loop setup e.g. three brokers in a chain (A-&gt;B-&gt;C) with producer at broker A and consumer at C, you would want broker B to re-federate the consumer onto A.</p>
</li>
<li><p><code>transformer-ref</code>. The ref name for a transformer (see transformer config) that you may wish to configure to transform the message on federation transfer.</p>
</li>
</ul>
<p><strong>note</strong> <code>address-policy</code>&apos;s and <code>queue-policy</code>&apos;s are able to be defined in the same federation, and be linked to the same upstream.</p>
<p>Now look at all the <code>transformer</code> parameters in turn, in order of priority:</p>
<ul>
<li><p><code>name</code> attribute. This must be a unique name in the server, and is used to ref the transformer in <code>address-policy</code> and <code>queue-policy</code></p>
</li>
<li><p><code>transformer-class-name</code>. An optional transformer-class-name can be
specified. This is the name of a user-defined class which implements the
<code>org.apache.activemq.artemis.core.server.transformer.Transformer</code> interface.</p>
<p>If this is specified then the transformer&apos;s <code>transform()</code> method will be
invoked with the message before it is transferred. This gives you the opportunity
to transform the message&apos;s header or body before it is federated.</p>
</li>
<li><p><code>property</code> holds key, value pairs that can be used to configure the transformer.</p>
</li>
</ul>
<p>Finally look at <code>upstream</code>, this is what defines the upstream broker connection and the policies to use against it.</p>
<ul>
<li><p><code>name</code> attribute. This must be a unique name in the server, and is used to ref the transformer in <code>address-policy</code> and <code>queue-policy</code></p>
</li>
<li><p><code>user</code>. This optional attribute determines the user name to use when creating
the upstream connection to the remote server. If it is not specified the shared
federation user and password will be used if set.</p>
</li>
<li><p><code>password</code>. This optional attribute determines the password to use when
creating the upstream connection to the remote server. If it is not specified the shared
federation user and password will be used if set.</p>
</li>
<li><p><code>static-connectors</code> or <code>discovery-group-ref</code>. Pick either of these options to
connect the bridge to the target server.</p>
<p>The <code>static-connectors</code> is a list of <code>connector-ref</code> elements pointing to
<code>connector</code> elements defined elsewhere. A <em>connector</em> encapsulates knowledge of
what transport to use (TCP, SSL, HTTP etc) as well as the server connection
parameters (host, port etc). For more information about what connectors are and
how to configure them, please see <a href="configuring-transports.html">Configuring the
Transport</a>.</p>
<p>The <code>discovery-group-ref</code> element has one attribute - <code>discovery-group-name</code>.
This attribute points to a <code>discovery-group</code> defined elsewhere. For more
information about what discovery-groups are and how to configure them, please
see <a href="clusters.html">Discovery Groups</a>.</p>
</li>
<li><p><code>ha</code>. This optional parameter determines whether or not this bridge should
support high availability. True means it will connect to any available server
in a cluster and support failover. The default value is <code>false</code>.</p>
</li>
<li><p><code>circuit-breaker-timeout</code> in milliseconds, When a connection issue occurs,
as the single connection is shared by many federated queue and address consumers,
to avoid each one trying to reconnect and possibly causing a thrundering heard issue,
the first one will try, if unsuccessful the circuit breaker will open,
returning the same exception to all, this is the timeout until the circuit can be closed and connection retried.</p>
</li>
<li><p><code>share-connection</code>. If there is a downstream and upstream connection configured for the same broker then
the same connection will be shared as long as both stream configs set this flag to true.
Default is false.</p>
</li>
<li><p><code>check-period</code>. The period (in milliseconds) used to check if the
federation connection has failed to receive pings from another server.
Default is 30000.</p>
</li>
<li><p><code>connection-ttl</code>. This is how long a federation connection should stay
alive if it stops receiving messages from the remote broker. Default is 60000.</p>
</li>
<li><p><code>call-timeout</code>. When a packet is sent via a federation connection and
is a blocking call, i.e. for acknowledgements, this is how long it
will wait (in milliseconds) for the reply before throwing an
exception. Default is 30000.</p>
</li>
<li><p><code>call-failover-timeout</code>. Similar to <code>call-timeout</code> but used when a
call is made during a failover attempt. Default is -1 (no timeout).</p>
</li>
<li><p><code>retry-interval</code>. This optional parameter determines the period in
milliseconds between subsequent reconnection attempts, if the connection to
the target server has failed. The default value is <code>500</code> milliseconds.</p>
</li>
<li><p><code>retry-interval-multiplier</code>. This is a multiplier used to increase
the <code>retry-interval</code> after each reconnect attempt, default is 1.</p>
</li>
<li><p><code>max-retry-interval</code>. The maximum delay (in milliseconds) for
retries. Default is 2000.</p>
</li>
<li><p><code>initial-connect-attempts</code>. The number of times the system will try
to connect to the remote broker in the federation. If the max-retry is
achieved this broker will be considered permanently down and the
system will not route messages to this broker. Default is -1 (infinite
retries).</p>
</li>
<li><p><code>reconnect-attempts</code>. The number of times the system will try to
reconnect to the remote broker in the federation. If the max-retry is achieved
this broker will be considered permanently down and the system will
stop routing messages to this broker. Default is -1 (infinite
retries).</p>
</li>
</ul>
<h2 id="configuring-downstream-federation">Configuring Downstream Federation</h2>
<p>Similarly to <code>upstream</code> configuration, a downstream configuration can be configured. This works by sending a command
to the <code>downstream</code> broker to have it create an <code>upstream</code> connection back to the downstream broker. The benefit of
this is being able to configure everything for federation on one broker in some cases to make it easier, such
as a hub and spoke topology.</p>
<p>All of the same configuration options apply to to <code>downstream</code> as does <code>upstream</code> with the exception of one
extra configuration flag that needs to be set:</p>
<p> The <code>transport-connector-ref</code> is an element pointing to a
<code>connector</code> elements defined elsewhere. This ref is used to tell the downstream broker
what connector to use to create a new upstream connection back to the downstream broker.</p>
<p> A <em>connector</em> encapsulates knowledge of what transport to use (TCP, SSL, HTTP etc) as well as
the server connection parameters (host, port etc). For more information about what connectors are and
how to configure them, please see <a href="configuring-transports.html">Configuring the
Transport</a>.</p>
<p> Sample Downstream Address Federation setup:</p>
<pre><code class="lang-xml">
<span class="hljs-comment">&lt;!--Other config Here --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">connectors</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">connector</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;netty-connector&quot;</span>&gt;</span>tcp://localhost:61616<span class="hljs-tag">&lt;/<span class="hljs-name">connector</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">connector</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;eu-west-1-connector&quot;</span>&gt;</span>tcp://localhost:61616<span class="hljs-tag">&lt;/<span class="hljs-name">connector</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">connector</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;eu-east-1-connector&quot;</span>&gt;</span>tcp://localhost:61617<span class="hljs-tag">&lt;/<span class="hljs-name">connector</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">connectors</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">acceptors</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">acceptor</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;netty-acceptor&quot;</span>&gt;</span>tcp://localhost:61616<span class="hljs-tag">&lt;/<span class="hljs-name">acceptor</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">acceptors</span>&gt;</span>
<span class="hljs-comment">&lt;!--Other config Here --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">federations</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">federation</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;eu-north-1&quot;</span> <span class="hljs-attr">user</span>=<span class="hljs-string">&quot;federation_username&quot;</span> <span class="hljs-attr">password</span>=<span class="hljs-string">&quot;32a10275cf4ab4e9&quot;</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">downstream</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;eu-east-1&quot;</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">static-connectors</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">connector-ref</span>&gt;</span>eu-east-connector1<span class="hljs-tag">&lt;/<span class="hljs-name">connector-ref</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">static-connectors</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">transport-connector-ref</span>&gt;</span>netty-connector<span class="hljs-tag">&lt;/<span class="hljs-name">transport-connector-ref</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">policy</span> <span class="hljs-attr">ref</span>=<span class="hljs-string">&quot;news-address-federation&quot;</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">downstream</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">downstream</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;eu-west-1&quot;</span> &gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">static-connectors</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">connector-ref</span>&gt;</span>eu-west-connector1<span class="hljs-tag">&lt;/<span class="hljs-name">connector-ref</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">static-connectors</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">transport-connector-ref</span>&gt;</span>netty-connector<span class="hljs-tag">&lt;/<span class="hljs-name">transport-connector-ref</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">policy</span> <span class="hljs-attr">ref</span>=<span class="hljs-string">&quot;news-address-federation&quot;</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">downstream</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">queue-policy</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;news-queue-federation&quot;</span> <span class="hljs-attr">priority-adjustment</span>=<span class="hljs-string">&quot;-5&quot;</span> <span class="hljs-attr">include-federated</span>=<span class="hljs-string">&quot;true&quot;</span> <span class="hljs-attr">transformer-ref</span>=<span class="hljs-string">&quot;federation-transformer-3&quot;</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">include</span> <span class="hljs-attr">queue-match</span>=<span class="hljs-string">&quot;#&quot;</span> <span class="hljs-attr">address-match</span>=<span class="hljs-string">&quot;queue.bbc.new&quot;</span> /&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">include</span> <span class="hljs-attr">queue-match</span>=<span class="hljs-string">&quot;#&quot;</span> <span class="hljs-attr">address-match</span>=<span class="hljs-string">&quot;queue.usatoday&quot;</span> /&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">include</span> <span class="hljs-attr">queue-match</span>=<span class="hljs-string">&quot;#&quot;</span> <span class="hljs-attr">address-match</span>=<span class="hljs-string">&quot;queue.news.#&quot;</span> /&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">exclude</span> <span class="hljs-attr">queue-match</span>=<span class="hljs-string">&quot;#.local&quot;</span> <span class="hljs-attr">address-match</span>=<span class="hljs-string">&quot;#&quot;</span> /&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">queue-policy</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">transformer</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;news-transformer&quot;</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">class-name</span>&gt;</span>org.foo.NewsTransformer<span class="hljs-tag">&lt;/<span class="hljs-name">class-name</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">property</span> <span class="hljs-attr">key</span>=<span class="hljs-string">&quot;key1&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;value1&quot;</span>/&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">property</span> <span class="hljs-attr">key</span>=<span class="hljs-string">&quot;key2&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;value2&quot;</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">transformer</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">federation</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">federations</span>&gt;</span>
</code></pre>
</section>
</div>
<div class="search-results">
<div class="has-results">
<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
<ul class="search-results-list"></ul>
</div>
<div class="no-results">
<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
</div>
</div>
</div>
</div>
</div>
</div>
<a href="federation-address.html" class="navigation navigation-prev " aria-label="Previous page: Address Federation">
<i class="fa fa-angle-left"></i>
</a>
<a href="ha.html" class="navigation navigation-next " aria-label="Next page: High Availability and Failover">
<i class="fa fa-angle-right"></i>
</a>
</div>
<script>
var gitbook = gitbook || [];
gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Queue Federation","level":"1.60.2","depth":2,"next":{"title":"High Availability and Failover","level":"1.61","depth":1,"path":"ha.md","ref":"ha.md","articles":[]},"previous":{"title":"Address Federation","level":"1.60.1","depth":2,"path":"federation-address.md","ref":"federation-address.md","articles":[]},"dir":"ltr"},"config":{"plugins":[],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"github":"apache/activemq-artemis","theme":"default","githubHost":"https://github.com/","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"ActiveMQ Artemis Documentation","links":{"home":"http://activemq.apache.org/artemis","issues":"https://issues.apache.org/jira/browse/ARTEMIS","contribute":"http://activemq.apache.org/contributing.html"},"gitbook":"3.x.x","description":"ActiveMQ Artemis User Guide and Reference Documentation"},"file":{"path":"federation-queue.md","mtime":"2020-01-10T14:13:27.000Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2020-01-10T14:51:01.535Z"},"basePath":".","book":{"language":""}});
});
</script>
</div>
<script src="gitbook/gitbook.js"></script>
<script src="gitbook/theme.js"></script>
<script src="gitbook/gitbook-plugin-search/search-engine.js"></script>
<script src="gitbook/gitbook-plugin-search/search.js"></script>
<script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
<script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
<script src="gitbook/gitbook-plugin-sharing/buttons.js"></script>
<script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
</body>
</html>