.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.

Introduction
============

Overview
--------

The Dispatch router is an AMQP message message router that provides
advanced interconnect capabilities. It allows flexible routing of
messages between any AMQP-enabled endpoints, whether they be clients,
servers, brokers or any other entity that can send or receive standard
AMQP messages.

A messaging client can make a single AMQP connection into a messaging
bus built of Dispatch routers and, over that connection, exchange
messages with one or more message brokers, and at the same time exchange
messages directly with other endpoints without involving a broker at
all.

The router is an intermediary for messages but it is *not* a broker. It
does not *take responsibility for* messages. It will, however, propagate
settlement and disposition across a network such that delivery
guarantees are met. In other words: the router network will deliver the
message, possibly via several intermediate routers, *and* it will route
the acknowledgement of that message by the ultimate receiver back across
the same path. This means that *responsibility* for the message is
transfered from the original sender to the ultimate receiver *as if they
were directly connected*. However this is done via a flexible network
that allows highly configurable routing of the message transparent to
both sender and receiver.

There are some patterns where this enables "brokerless messaging"
approaches that are preferable to brokered approaches. In other cases a
broker is essential (in particular where you need the separation of
responsibility and/or the buffering provided by store-and-forward) but a
dispatch network can still be useful to tie brokers and clients together
into patterns that are difficult with a single broker.

For a "brokerless" example, consider the common brokered implementation
of the request-response pattern, a client puts a request on a queue and
then waits for a reply on another queue. In this case the broker can be
a hindrance - the client may want to know immediatly if there is nobody
to serve the request, but typically it can only wait for a timeout to
discover this. With a dispatch network, the client can be informed
immediately if its message cannot be delivered because nobody is
listening. When the client receives acknowledgement of the request it
knows not just that it is sitting on a queue, but that it has actually
been received by the server.

For an exampe of using dispatch to enhance the use of brokers, consider
using an array of brokers to implement a scalable distributed work
queue. A dispatch network can make this appear as a single queue, with
senders publishing to a single address and receivers subscribing to a
single address. The dispatch network can distribute work to any broker
in the array and collect work from any broker for any receiver. Brokers
can be shut down or added without affecting clients. This elegantly
solves the common difficulty of "stuck messages" when implementing this
pattern with brokers alone. If a receiver is connected to a broker that
has no messages, but there are messages on another broker, you have to
somehow transfer them or leave them "stuck". With a dispatch network,
*all* the receivers are connected to *all* the brokers. If there is a
message anywhere it can be delivered to any receiver.

The router is meant to be deployed in topologies of multiple routers,
preferably with redundant paths. It uses link-state routing protocols
and algorithms (similar to OSPF or IS-IS from the networking world) to
calculate the best path from every point to every other point and to
recover quickly from failures. It does not need to use clustering for
high availability; rather, it relies on redundant paths to provide
continued connectivity in the face of system or network failure. Because
it never takes responsibility for messages it is effectively stateless.
Messages not delivered to their final destination will not be
acknowledged to the sender and therefore the sender can re-send such
messages if it is disconnected from the network.

Benefits
--------

Simplifies connectivity

- An endpoint can do all of its messaging through a single transport connection
- Avoid opening holes in firewalls for incoming connections

Provides messaging connectivity where there is no TCP/IP connectivity

- A server or broker can be in a private IP network (behind a NAT firewall) and be accessible by messaging endpoints in other networks (learn more).

Simplifies reliability

- Reliability and availability are provided using redundant topology, not server clustering
- Reliable end-to-end messaging without persistent stores
- Use a message broker only when you need store-and-forward semantics

Features
--------

- Can be deployed stand-alone or in a network of routers
  - Supports arbitrary network topology - no restrictions on redundancy
  - Automatic route computation - adjusts quickly to changes in topology
- Provides remote access to brokers or other AMQP servers
- Security