Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 56C1A200C32 for ; Thu, 9 Mar 2017 19:01:19 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id 55513160B75; Thu, 9 Mar 2017 18:01:19 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 5849F160B5F for ; Thu, 9 Mar 2017 19:01:18 +0100 (CET) Received: (qmail 45595 invoked by uid 500); 9 Mar 2017 18:01:17 -0000 Mailing-List: contact dev-help@activemq.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@activemq.apache.org Delivered-To: mailing list dev@activemq.apache.org Received: (qmail 45584 invoked by uid 99); 9 Mar 2017 18:01:17 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 09 Mar 2017 18:01:17 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 267B4DFB7D; Thu, 9 Mar 2017 18:01:17 +0000 (UTC) From: jbertram To: dev@activemq.apache.org Reply-To: dev@activemq.apache.org References: In-Reply-To: Subject: [GitHub] activemq-artemis pull request #1077: Update user man Content-Type: text/plain Message-Id: <20170309180117.267B4DFB7D@git1-us-west.apache.org> Date: Thu, 9 Mar 2017 18:01:17 +0000 (UTC) archived-at: Thu, 09 Mar 2017 18:01:19 -0000 Github user jbertram commented on a diff in the pull request: https://github.com/apache/activemq-artemis/pull/1077#discussion_r105229583 --- 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 /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 + + + ... +
+ + + +
+ + +``` + +### 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. + +When a message is received on an address with a multicast routing type, Apache ActiveMQ Artemis will route a copy of the message (in reality only a message reference to reduce the overhead of copying) to each queue. + +![Publish Subscribe](images/addressing-model-pubsub.png) +Figure 2. Publish-Subscribe + +#### Configuring an Address to Use the Multicast Routing Type + +Open the file /etc/broker.xml for editing. + +Add an address configuration element with multicast routing type. + +```xml + + + ... +
+ +
+ + +``` + +(Optional) 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 + + + ... +
+ + + + +
+ + +``` + +Figure 3. Point-to-Point with Two Queues + +### Point-to-Point Address multiple Queues + +It is actually possible to define more than one queue on an address with an anycast routing type. When messages are received on such an address, they are firstly distributed evenly across all the defined queues. Using Fully Qualified Queue Names described later, clients are able to select the queue that they’d like to subscribe to. Should more than one consumer connect direct to a single queue, Apache ActiveMQ Artemis will take care of distributing messages between them, as in the example above. + +![Point to Point](images/addressing-model-p2p2.png) +Figure 3. Point-to-Point with Two Queues + +-------------------------------------------------------------------------------------------- +**Note:** This is how Apache ActiveMQ Artemis handles load balancing of queues across multiple nodes in a cluster. +Configuring a Point-to-Point Address with Two Queues +Open the file /etc/broker.xml for editing. + +Add an address configuration with Anycast routing type element and its associated queues. + +```xml + + + ... +
+ + + + +
+ + +``` + +### Point-to-Point and Publish-Subscribe Addresses + +It is possible to define an address with both point-to-point and publish-subscribe semantics enabled. While not typically recommend, this can be useful when you want, for example, a JMS Queue say orders and a JMS Topic named orders. The different routing types make the addresses appear to be distinct. + +Using an example of JMS Clients, the messages sent by a JMS queue producer will be routed using the anycast routing type. Messages sent by a JMS topic producer will use the multicast routing type. In addition when a JMS topic consumer attaches it will be attached to it’s own subscription queue. JMS queue consumer will be attached to the anycast queue. + +![Point to Point](images/addressing-model-p2p-pubsub.png) +Figure 4. [Point-to-Point and Publish-Subscribe + +-------------------------------------------------------------------------------------------- +**Note:** The behavior in this scenario is dependent on the protocol being used. For JMS there is a clear distinction between topic and queue producers and consumers, which make the logic straight forward. Other protocols like AMQP do not make this distinction. A message being sent via AMQP will be routed by both anycast and multicast and consumers will default to anycast. For more information, please check the behavior of each protocol in the sections on protocols. + +The XML snippet below is an example of what the configuration for an address using both anycast and multicast would look like in /etc/broker.xml. routing types. Note that subscription queues are typically created on demand, so there is no need to list specific queue elements inside the multicast routing type. + +```xml + + + ... +
+ + + + +
+ + +``` + +## How to filter messages + +Apache ActiveMQ Artemis supports the ability to filter messages using Apache Artemis [Filter Expressions](#filter-expressions). + +Filters can be applied in two places, on a queue and on a consumer. + +### Queue Filter + +When a filter is applied to a queue, messages are filter before they sent to the queue. To add a queue filter use the +filter element when configuring a queue. Open up the broker.xml and add an address with a queue, using the filter element +to configure a filter on this queue. + +```xml +
+ + + +
+``` + +The filter defined above ensures that only messages with an attribute "color='red'" is sent to this queue. + +### Consumer Filters + +Consumer filters are applied after messages have reached a queue and are defined using the appropriate client APIs. The +follow JMS example shows how to consumer filters work. + +1. Define an address with a single queue, with no filter applied. + +```xml +
+ + --- End diff -- Above it says, "Define an address with a single queue, with no filter applied." However, there is a filter applied here, no? --- 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. ---