activemq-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbertram <...@git.apache.org>
Subject [GitHub] activemq-artemis pull request #1077: Update user man
Date Thu, 09 Mar 2017 17:40:33 GMT
Github user jbertram commented on a diff in the pull request:

    https://github.com/apache/activemq-artemis/pull/1077#discussion_r105225037
  
    --- 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. |
    +
    +## Background (Protocol Managers and Addresses)
    +
    +A protocol manager maps protocol specific concepts down to the Apache ActiveMQ Artemis
core model of addresses, queues and routing types. For example, when a client sends a MQTT
subscription packet with the addresses 
    +
    +```
    +/house/room1/lights
    +/house/room2/lights
    +```
    +
    +The MQTT protocol manager understands that the two addresses require multicast semantics.
The protocol manager will therefore first look to ensure that multicast is enabled for both
addresses. If not, it will attempt to dynamically create them. If successful, the protocol
manager will then create special subscription queues with special names, for each subscription
requested by the client.
    +
    +The special name allows the protocol manager to quickly identify the required client
subscription queues should the client disconnect and reconnect at a later date.  If the subscription
is temporary the protocol manager will delete the queue once the client disconnects.
    +
    +If a client requests a point to point semantic (e.g. JMS Queue).  Apache ActiveMQ Artemis
will first look at the address sent by the client and use that to look up an Apache ActiveMQ
Artemis address.  It will then ensure the point to point (Anycast) routing type is enabled.

    +
    +If it is it will aim to locate a queue with the same name as the address. If it does
not exist, it will look for the first queue available. If this does not exist then it will
auto create the queue (providing auto create is enabled) and then bind the consumer to this
queue.
    +
    +N.B. If the queue is auto created, it will be auto deleted once there are no consumers
and no messages in it.  For more information on auto create see 
    +
    +## 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
    +
    +#### 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.
An example of a publish-subscribe Assign a multicast routing type for an address so that its
queues receive messages in a pubish-subscribe manner.
    --- End diff --
    
    Something was left out of the last sentence in this paragraph, I think.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message