[
https://issues.apache.org/jira/browse/ARTEMIS-2937?focusedWorklogId=505817&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-505817
]
ASF GitHub Bot logged work on ARTEMIS-2937:
-------------------------------------------
Author: ASF GitHub Bot
Created on: 28/Oct/20 17:06
Start Date: 28/Oct/20 17:06
Worklog Time Spent: 10m
Work Description: clebertsuconic commented on a change in pull request
#3316:
URL: https://github.com/apache/activemq-artemis/pull/3316#discussion_r513615262
##########
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>
Review comment:
this can be a follow up change on the docs.
----------------------------------------------------------------
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: 505817)
Time Spent: 30.5h (was: 30h 20m)
> 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: 30.5h
> 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)
