[
https://issues.apache.org/jira/browse/ARTEMIS-2937?focusedWorklogId=506155&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-506155
]
ASF GitHub Bot logged work on ARTEMIS-2937:
-------------------------------------------
Author: ASF GitHub Bot
Created on: 29/Oct/20 10:39
Start Date: 29/Oct/20 10:39
Worklog Time Spent: 10m
Work Description: gemmellr commented on a change in pull request #3316:
URL: https://github.com/apache/activemq-artemis/pull/3316#discussion_r514160758
##########
File path: docs/user-manual/en/amqp-broker-connections.md
##########
@@ -0,0 +1,238 @@
+# Broker Connections
+
+Instead of waiting for clients to connect, a broker can initiate a connection
to another endpoint on a specific protocol.
+
+Currently, this feature supports only the AMQP protocol. However, in the
future, it might be expanded to other protocols.
+
+You configure broker connections using a `<broker-connections>` XML element in
the `broker.xml` configuration file.
+
+```xml
+<broker-connections>
+ ...
+</broker-connections>
+```
+
+# AMQP Server Connections
+
+An ActiveMQ Artemis broker can initiate connections using the AMQP protocol.
This means that the broker can connect to another AMQP server (not necessarily
ActiveMQ Artemis) and create elements on that connection.
+
+To define an AMQP broker connection, add an `<amqp-connection>` element within
the `<broker-connections` element in the `broker.xml` configuration file. For
example:
+
+```xml
+<broker-connections>
+ <amqp-connection uri="tcp://MY_HOST:MY_PORT" name="my-broker"
retry-interval="100" reconnect-attempts="-1" user="john" password="doe">
+ ...
+ </amqp-connection>
+</broker-connections>
+```
+
+- `uri`: tcp://host:myport (this is a required argument)
+- `name`: Name of the connection used for management purposes
+- `user`: User name with which to connect to the endpoint (this is an optional
argument)
+- `password`: Password with which to connect to the endpoint (this is an
optional argument)
+- `retry-interval`: Time, in milliseconds to wait before retrying a connection
after an error. The default value is `5000`.
+- `reconnect-attempts`: default is -1 meaning infinite
+- `auto-start` : Should the broker connection start automatically with the
broker. Default is `true`. If false you need to call a management operation to
start it.
+
+*Notice*: If you disable auto-start on the broker connection, the start of the
broker connection will only happen after the management method
`startBrokerConnection(connectionName)` is called on the ServerController.
+
+*Important*: The target endpoint needs permission for all operations that you
configure. Therefore, If you are using a security manager, ensure that you
perform the configured operations as a user with sufficient permissions.
+
+# AMQP Server Connection Operations
+The following types of operations are supported on a AMQP server connection:
+
+* Senders
+ * Messages received on specific queues are transferred to another endpoint
+* Receivers
+ * The broker pulls messages from another endpoint
+* Peers
+ * The broker creates both senders and receivers on another endpoint that
knows how to handle them. Currently, this is implemented by Apache Qpid
Dispatch.
+* Mirrors
+ * The broker uses an AMQP connection to another broker and duplicate
messages and sends acknowledgements over the wire.
+
+## Senders and Receivers
+It is possible to connect an ActiveMQ Artemis broker to another AMQP endpoint
simply by creating a sender or receiver broker connection element.
+
+For a `sender`, the broker creates a message consumer on a queue that sends
messages to another AMQP endpoint.
+
+For a `receiver`, the broker creates a message producer on an address that
receives messages from another AMQP endpoint.
+
+Both elements work like a message bridge. However, there is no additional
overhead required to process messages. Senders and receivers behave just like
any other consumer or producer in ActiveMQ Artemis.
+
+You can configure senders or receivers for specific queues. You can also match
senders and receivers to specific addresses or _sets_ of addresses, using
wildcard expressions. When configuring a sender or receiver, you can set the
following properties:
+
+- `match`: Match the sender or receiver to a specific address or __set__ of
addresses, using a wildcard expression
+- `queue-name`: Configure the sender or receiver for a specific queue
+
+
+Some examples are shown below.
+
+Using address expressions:
+```xml
+<broker-connections>
+ <amqp-connection uri="tcp://MY_HOST:MY_PORT" name="my-broker">
+ <sender match="queues.#"/>
+ <!-- notice the local queues for remotequeues.# need to be
created on this broker -->
+ <receiver match="remotequeues.#"/>
+ </amqp-connection>
+</broker-connections>
+
+<addresses>
+ <address name="remotequeues.A">
+ <anycast>
+ <queue name="remoteQueueA"/>
+ </anycast>
+ </address>
+ <address name="queues.B">
+ <anycast>
+ <queue name="localQueueB"/>
+ </anycast>
+ </address>
+</addresses>
+```
+
+Using queue names:
+```xml
+<broker-connections>
+ <amqp-connection uri="tcp://MY_HOST:MY_PORT" name="my-broker">
+ <receiver queue-name="remoteQueueA"/>
+ <sender queue-name="localQueueB"/>
+ </amqp-connection>
+</broker-connections>
+
+<addresses>
+ <address name="remotequeues.A">
+ <anycast>
+ <queue name="remoteQueueA"/>
+ </anycast>
+ </address>
+ <address name="queues.B">
+ <anycast>
+ <queue name="localQueueB"/>
+ </anycast>
+ </address>
+</addresses>
+
+```
+*Important*: You can match a receiver only to a local queue that already
exists. Therefore, if you are using receivers, make sure that you pre-create
the queue locally. Otherwise, the broker cannot match the remote queues and
addresses.
+
+*Important*: Do not create a sender and a receiver to the same destination.
This creates an infinite loop of sends and receives.
+
+
+# Peers
+A peer broker connection element is a combination of sender and receivers. The
ActiveMQ Artemis broker creates both a sender and a receiver for a peer
element, and the endpoint knows how to deal with the pair without creating an
infinite loop of sending and receiving messages.
+
+Currently, [Apache Qpid Dispatch
Router](https://qpid.apache.org/components/dispatch-router/index.html) is a
peer. ActiveMQ Artemis creates the pair of receivers and sender for each
matching destination. These senders and receivers have special configuration to
let Qpid Dispatch Router know to collaborate with ActiveMQ Artemis.
Review comment:
I dont believe they can actually refer to the Dispatch docs for more
information on this, I think only the router-initiatiated waypointing using
router-based autolink configuration is documented there. Even if/once it was
mentioned, it wouldnt be immediately obvious to people coming to Artemis and
seeing this section of doc, what it is they need to make this Artemis
functionality work. It needs to be discussed in the Artemis docs. Essentially
the tiny paragraph I described is all it needs.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
Issue Time Tracking
-------------------
Worklog Id: (was: 506155)
Time Spent: 33h (was: 32h 50m)
> AMQP Server Connectivity
> ------------------------
>
> Key: ARTEMIS-2937
> URL: https://issues.apache.org/jira/browse/ARTEMIS-2937
> Project: ActiveMQ Artemis
> Issue Type: New Feature
> Components: AMQP
> Reporter: Clebert Suconic
> Assignee: Clebert Suconic
> Priority: Major
> Fix For: 2.16.0
>
> Time Spent: 33h
> Remaining Estimate: 0h
>
> This feature adds server side connectivity.
>
> It is possible to link two brokers directly using AMQP with this feature, and
> have a Queue transferring messages to another broker directly.
>
> For this we would have options called <sender and <receiver
>
>
> it would also be possible to use qpid-dispatch as an intermediary between
> clients and the brokers (or eventually between brokers), on that case the
> option will be <peer
>
> it would also be possible to use <mirror with a few option to replicate data
> between two brokers, bringing the possibility of using it for Disaster &
> Recovery and Failover.
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
