[ 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)