[GitHub] [activemq-artemis] jbertram commented on a change in pull request #3930: ARTEMIS-3657 refactor address docs

[GitBox <gi...@apache.org>]

jbertram commented on a change in pull request #3930:
URL: https://github.com/apache/activemq-artemis/pull/3930#discussion_r812331725



##########
File path: docs/user-manual/en/address-model.md
##########
@@ -1,455 +1,242 @@
-# Addressing Model
+# Address Model
 
-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**.
+Every messaging protocol and API that Apache ActiveMQ Artemis supports defines
+a different set of messaging resources.
+
+ - JMS uses _queues_ and _topics_
+ - STOMP uses generic _destinations_
+ - MQTT uses _topics_
+ - AMQP uses generic _nodes_
+
+In order to deal the the unique semantics and use-cases for each of these the
+broker has a flexible and powerful address model and a _core_ set of resources:
+
+ - **address**
+ - **queue**
+ - **routing type**
 
 ### Address
 
-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.
+Messages are *sent* to an address. An address is given a unique name, a routing
+type, and zero or more queues.
 
 ### Queue
 
-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.
+Messages are *consumed* from a queue. A queue is bound to an address. There can
+be zero or more queues bound to one address. When a message is sent to an
+address it is routed to one or more of its queues based on the configured
+routing type.
 
-### Routing Types
+The name of the queue must be _globally_ unique. For example, you can't have a
+queue named `q1` on address `a1` and also a queue named `q1` address `a2`.
 
-A routing type determines how messages are sent to the queues associated with
-an address. An Apache ActiveMQ Artemis address can be configured with two
-different routing types.
+### Routing Type
 
-Table 1. Routing Types
+A routing type determines how messages are routed from an address to the
+queue(s) bound to that address. Two different routing types are supported,
+**anycast** and **multicast**.
 
 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.
-
-For additional details about these concepts refer to [the core](core.md) chapter.
-
-## 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.
-
-![Point to Point](images/addressing-model-p2p.png)
-Figure 1. Point to Point Messaging
-
-#### Using 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.
+a single queue on the address.|anycast
+every queue on the address.|multicast
 
-**Note:** For normal Point to Point semantics, the queue name **MUST** match the
-address name.
-
-```xml
-<addresses>
-   <address name="orders">
-      <anycast>
-         <queue name="orders"/>
-      </anycast>
-   </address>
-</addresses>
-```
+> **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.

Review comment:
       I honestly can't think of a use-case for this. Can you? I'd be happy to add an explanation of straight-forward use-case if one exists.




-- 
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.

To unsubscribe, e-mail: gitbox-unsubscribe@activemq.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org