Github user jbertram commented on a diff in the pull request:
https://github.com/apache/activemq-artemis/pull/1077#discussion_r105272326
--- Diff: docs/user-manual/en/address-model.md ---
@@ -0,0 +1,585 @@
+# Apache ActiveMQ Artemis Addressing and Queues
+
+Apache ActiveMQ Artemis has a unique addressing model that is both
powerful and flexible and that offers great performance. The addressing model
comprises three main concepts: addresses, queues and routing types.
+
+An address represents a messaging endpoint. Within the configuration, a
typical address is given a unique name, 0 or more queues, and a routing type.
+
+A queue is associated with an address. There can be multiple queues per
address. Once an incoming message is matched to an address, the message will be
sent on to one or more of its queues, depending on the routing type configured.
Queues can be configured to be automatically created and deleted.
+
+A routing type determines how messages are sent to the queues associated
with an address. A Apache ActiveMQ Artemis address can be configured with two
different routing types.
+
+Table 1. Routing Types
+
+| If you want your messages routed toâ¦â
| Use this routing type â¦â |
+| :----------------------------------------------------------------------:
| :---------------------: |
+| A single queue within the matching address, in a point-to-point manner.
| Anycast |
+| Every queue within the matching address, in a publish-subscribe manner.
| Multicast |
+
+--------------------------------------------------------------------------------------------
+**Note:** It is possible to define more than one routing type per address,
but this typically results in an anti-pattern and is therefore not recommended.
If an address does use both routing types, however, and the client does not
show a preference for either one, the broker typically defaults to the anycast
routing type.
+The one exception is when the client uses the MQTT protocol. In that case,
the default routing type is multicast. |
+
+## Basic Address Configuration
+
+The following examples show how to configure basic point to point and
publish subscribe addresses.
+
+### Point-to-Point Messaging
+
+Point-to-point messaging is a common scenario in which a message sent by a
producer has only one consumer. AMQP and JMS message producers and consumers
can make use of point-to-point messaging queues, for example. Define an anycast
routing type for an address so that its queues receive messages in a
point-to-point manner.
+
+When a message is received on an address using anycast, Apache ActiveMQ
Artemis locates the queue associated with the address and routes the message to
it. When consumers request to consume from the address, the broker locates the
relevant queue and associates this queue with the appropriate consumers. If
multiple consumers are connected to the same queue, messages are distributed
amongst each consumer equally, providing the consumers are equally able to
handle them.
+
+
+Figure 1. Point to Point Messaging
+
+#### Configuring an Address to Use the Anycast Routing Type
+
+Open the file <broker-instance>/etc/broker.xml for editing.
+
+Add an address configuration element and its associated queue if they do
not exist already.
+
+**Note** For normal Point to Point semantics, the queue name **MUST**
match the address name.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="orders">
+ <anycast>
+ <queue name="orders"/>
+ </anycast>
+ </address>
+ </core>
+</configuration>
+```
+
+### Publish-Subscribe Messaging
+
+In a publish-subscribe scenario, messages are sent to every consumer
subscribed to an address. JMS topics and MQTT subscriptions are two examples of
publish-subscribe messaging.
+
+To configure an address with publish-subscribe semantics, create an
address with the multicast routing tyoe.
+
+
+Figure 2. Publish-Subscribe
+
+#### Configuring an Address to Use the Multicast Routing Type
+
+Open the file <broker-instance>/etc/broker.xml for editing.
+
+Add an address configuration element with multicast routing type.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="pubsub.foo">
+ <multicast/>
+ </address>
+ </core>
+</configuration>
+```
+
+When clients connect to an address with the multicast element, a
subscription queue for the client will be automatically created for the client.
It is also possible to pre-configure subscription queues and connect to them
directly using the queue's [Fully Qualified Queue
names](#fully-qualified-queue-names).
+
+Add one more queue elements to the address and wrap the multicast element
around them. This step is typically not needed since the broker will
automatically create a queue for each subscription requested by a client.
+
+```xml
+<configuration ...>
+ <core ...>
+ ...
+ <address name="topic.foo">
--- End diff --
Should these be "pubsub.foo" like above rather than "topic.foo"?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
