You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by tr...@apache.org on 2015/03/19 21:36:19 UTC
svn commit: r1667868 - in /qpid/dispatch/branches/0.4: ./ doc/book/
python/qpid_dispatch/management/
Author: tross
Date: Thu Mar 19 20:36:18 2015
New Revision: 1667868
URL: http://svn.apache.org/r1667868
Log:
DISPATCH_128 - Ported documentation updates to the 0.4 branch
Added:
qpid/dispatch/branches/0.4/doc/book/basic_usage.rst
qpid/dispatch/branches/0.4/doc/book/client_compatibility.rst
qpid/dispatch/branches/0.4/doc/book/default_config.rst
qpid/dispatch/branches/0.4/doc/book/link_routing.rst
qpid/dispatch/branches/0.4/doc/book/technical_details.rst
qpid/dispatch/branches/0.4/doc/book/tools.rst
Modified:
qpid/dispatch/branches/0.4/TODO
qpid/dispatch/branches/0.4/doc/book/amqp-mapping.rst
qpid/dispatch/branches/0.4/doc/book/book.rst
qpid/dispatch/branches/0.4/doc/book/introduction.rst
qpid/dispatch/branches/0.4/doc/book/schema_rst.py
qpid/dispatch/branches/0.4/doc/book/using.rst
qpid/dispatch/branches/0.4/python/qpid_dispatch/management/qdrouter.json
Modified: qpid/dispatch/branches/0.4/TODO
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/TODO?rev=1667868&r1=1667867&r2=1667868&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/TODO (original)
+++ qpid/dispatch/branches/0.4/TODO Thu Mar 19 20:36:18 2015
@@ -64,26 +64,7 @@ enhancements at the [Qpid Dispatch JIRA
- Security Policy Enforcement
- Proxy (Translation Node) Capability
- Address Provisioning with variable semantics
- - Link Routing
- Management, Instrumentation, and Accounting
- Link Cost
- Area Routing
-## Link routing
-
-Link routing occurs when a new link is attached to the router across one of its AMQP connections.
-It is done based on the `target.address` field of an inbound link and the `source.address` field
-of an outbound link.
-
-Link routing uses the same routing table that message routing uses. The difference is that the
-routing occurs during the link-attach operation, and link attaches are propagated along the appropriate
-path to the destination. What results is a chain of links, connected end-to-end, from source to
-destination. It is similar to a *virtual circuit* in a telecom system.
-
-Each router in the chain holds pairs of link termini that are tied together. The router then simply
-exchanges all deliveries, delivery state changes, and link state changes between the two termini.
-
-The endpoints that use the link chain do not see any difference in behavior between a link chain and
-a single point-to-point link. All of the features available in the link protocol (flow control,
-transactional delivery, etc.) are available over a routed link-chain.
-
Modified: qpid/dispatch/branches/0.4/doc/book/amqp-mapping.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/amqp-mapping.rst?rev=1667868&r1=1667867&r2=1667868&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/amqp-mapping.rst (original)
+++ qpid/dispatch/branches/0.4/doc/book/amqp-mapping.rst Thu Mar 19 20:36:18 2015
@@ -164,7 +164,7 @@ Supported Addresses
+------------------------------+------------------------------------------------------------+
| *Address* | *Description* |
+==============================+============================================================+
-| `_local/$management` |The management agent on the attached router/container. This |
+| `$management` |The management agent on the attached router/container. This |
| |address would be used by an endpoint that is a management |
| |client/console/tool wishing to access management data from |
| |the attached container. |
@@ -182,7 +182,7 @@ Supported Addresses
| |address is used by a router to communicate with other |
| |routers in the network. |
+------------------------------+------------------------------------------------------------+
-| `_topo/0/Router.E/qdxrouter` |The router entity at the specifically indicated router. This|
+| `_topo/0/Router.E/qdrouter` |The router entity at the specifically indicated router. This|
| |address form is used by a router to communicate with a |
| |specific router that may or may not be a neighbor. |
+------------------------------+------------------------------------------------------------+
Added: qpid/dispatch/branches/0.4/doc/book/basic_usage.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/basic_usage.rst?rev=1667868&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/basic_usage.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/basic_usage.rst Thu Mar 19 20:36:18 2015
@@ -0,0 +1,190 @@
+.. 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.
+
+Basic Usage and Examples
+========================
+
+Standalone and Interior Modes
+-----------------------------
+
+The router can operate stand-alone or as a node in a network of routers.
+The mode is configured in the *router* section of the configuration
+file. In stand-alone mode, the router does not attempt to collaborate
+with any other routers and only routes messages among directly connected
+endpoints.
+
+If your router is running in stand-alone mode, *qdstat -a* will look
+like the following:
+
+::
+
+ $ qdstat -a
+ Router Addresses
+ class address phase in-proc local remote in out thru to-proc from-proc
+ ===========================================================================================
+ local $management Y 0 0 0 0 0 0 0
+ mobile $management 0 Y 0 0 1 0 0 1 0
+ local temp.4Q3i01lWbs 1 0 0 0 0 0 0
+
+Note that there are two known addresses. *$management* is the address of
+the router's embedded management agent. *temp.4Q3i01lWbs* is the temporary
+reply-to address of the *qdstat* client making requests to the agent.
+
+If you change the mode to interior and restart the processs, the same
+command will yield additional addresses which are used for
+inter-router communication:
+
+::
+
+ $ qdstat -a
+ Router Addresses
+ class address phase in-proc local remote in out thru to-proc from-proc
+ ===========================================================================================
+ local $management Y 0 0 0 0 0 0 0
+ mobile $management 0 Y 0 0 1 0 0 1 0
+ local qdhello Y 0 0 0 0 0 0 3
+ local qdrouter Y 0 0 0 0 0 0 1
+ local qdrouter.ma Y 0 0 0 0 0 0 0
+ local temp.2ot2AWsnYz 1 0 0 0 0 0 0
+
+Mobile Subscribers
+------------------
+
+The term "mobile subscriber" simply refers to the fact that a client may
+connect to the router and subscribe to an address to receive messages
+sent to that address. No matter where in the network the subscriber
+attaches, the messages will be routed to the appropriate destination.
+
+To illustrate a subscription on a stand-alone router, you can use the
+examples that are provided with Qpid Proton. Using the *simple_recv.py* example
+receiver:
+
+::
+
+ $ python ./simple_recv.py -a 127.0.0.1/my-address
+
+This command creates a receiving link subscribed to the specified
+address. To verify the subscription:
+
+::
+
+ $ qdstat -a
+ Router Addresses
+ class address phase in-proc local remote in out thru to-proc from-proc
+ ===========================================================================================
+ local $management Y 0 0 0 0 0 0 0
+ mobile $management 0 Y 0 0 1 0 0 1 0
+ mobile my-address 0 1 0 0 0 0 0 0
+ local temp.JAgKj1+iB8 1 0 0 0 0 0 0
+
+
+You can then, in a separate command window, run a sender to produce
+messages to that address:
+
+::
+
+ $ python ./simple_send.py -a 127.0.0.1/my-address
+
+Dynamic Reply-To
+----------------
+
+Dynamic reply-to can be used to obtain a reply-to address that routes
+back to a client's receiving link regardless of how many hops it has to
+take to get there. To illustrate this feature, see below a simple
+program (written in C++ against the qpid::messaging API) that queries
+the management agent of the attached router for a list of other known
+routers' management addresses.
+
+::
+
+ #include <qpid/messaging/Address.h>
+ #include <qpid/messaging/Connection.h>
+ #include <qpid/messaging/Message.h>
+ #include <qpid/messaging/Receiver.h>
+ #include <qpid/messaging/Sender.h>
+ #include <qpid/messaging/Session.h>
+
+ using namespace qpid::messaging;
+ using namespace qpid::types;
+
+ using std::stringstream;
+ using std::string;
+
+ int main() {
+ const char* url = "amqp:tcp:127.0.0.1:5672";
+ std::string connectionOptions = "{protocol:amqp1.0}";
+
+ Connection connection(url, connectionOptions);
+ connection.open();
+ Session session = connection.createSession();
+ Sender sender = session.createSender("mgmt");
+
+ // create reply receiver and get the reply-to address
+ Receiver receiver = session.createReceiver("#");
+ Address responseAddress = receiver.getAddress();
+
+ Message request;
+ request.setReplyTo(responseAddress);
+ request.setProperty("x-amqp-to", "amqp:/_local/$management");
+ request.setProperty("operation", "DISCOVER-MGMT-NODES");
+ request.setProperty("type", "org.amqp.management");
+ request.setProperty("name, "self");
+
+ sender.send(request);
+ Message response = receiver.fetch();
+ Variant content(response.getContentObject());
+ std::cout << "Response: " << content << std::endl << std::endl;
+
+ connection.close();
+ }
+
+The equivalent program written in Python against the Proton Messenger
+API:
+
+::
+
+ from proton import Messenger, Message
+
+ def main():
+ host = "0.0.0.0:5672"
+
+ messenger = Messenger()
+ messenger.start()
+ messenger.route("amqp:/*", "amqp://%s/$1" % host)
+ reply_subscription = messenger.subscribe("amqp:/#")
+ reply_address = reply_subscription.address
+
+ request = Message()
+ response = Message()
+
+ request.address = "amqp:/_local/$management"
+ request.reply_to = reply_address
+ request.properties = {u'operation' : u'DISCOVER-MGMT-NODES',
+ u'type' : u'org.amqp.management',
+ u'name' : u'self'}
+
+ messenger.put(request)
+ messenger.send()
+ messenger.recv()
+ messenger.get(response)
+
+ print "Response: %r" % response.body
+
+ messenger.stop()
+
+ main()
+
Modified: qpid/dispatch/branches/0.4/doc/book/book.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/book.rst?rev=1667868&r1=1667867&r2=1667868&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/book.rst (original)
+++ qpid/dispatch/branches/0.4/doc/book/book.rst Thu Mar 19 20:36:18 2015
@@ -1,3 +1,20 @@
+.. 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.
+
.. Qpid Dispatch documentation master file, created by
sphinx-quickstart on Tue Feb 24 11:25:59 2015.
You can adapt this file completely to your liking, but it should at least
@@ -12,6 +29,4 @@ Qpid Dispatch Router Book
introduction
using
- addressing
- amqp-mapping
- schema
+ technical_details
Added: qpid/dispatch/branches/0.4/doc/book/client_compatibility.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/client_compatibility.rst?rev=1667868&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/client_compatibility.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/client_compatibility.rst Thu Mar 19 20:36:18 2015
@@ -0,0 +1,45 @@
+.. 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.
+
+Client Compatibility
+====================
+
+Dispatch Router should, in theory, work with any client that is
+compatible with AMQP 1.0. The following clients have been tested:
+
++-----------------+------------------------------------------------------------------+
+| *Client* | *Notes* |
++=================+==================================================================+
+| qpid::messaging |The Qpid messaging clients work with Dispatch Router as long as |
+| |they are configured to use the 1.0 version of the protocol. To |
+| |enable AMQP 1.0 in the C++ client, use the {protocol:amqp1.0} |
+| |connection option. |
+| | |
++-----------------+------------------------------------------------------------------+
+| Proton Reactor | The Proton Reactor API is compatible with Dispatch Router. |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
++-----------------+------------------------------------------------------------------+
+| Proton Messenger| Messenger works with Dispatch Router. |
+| | |
+| | |
++-----------------+------------------------------------------------------------------+
Added: qpid/dispatch/branches/0.4/doc/book/default_config.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/default_config.rst?rev=1667868&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/default_config.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/default_config.rst Thu Mar 19 20:36:18 2015
@@ -0,0 +1,33 @@
+.. 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.
+
+Configuration
+=============
+
+The default configuration file is installed in
+`install-prefix`/etc/qpid/qdrouterd.conf. This configuration file will
+cause the router to run in standalone mode, listening on the standard
+AMQP port (5672). Dispatch Router looks for the configuration file in
+the installed location by default. If you wish to use a different path,
+the "-c" command line option will instruct Dispatch Router as to which
+configuration to load.
+
+To run the router, invoke the executable: qdrouterd [-c my-config-file]
+
+For more details of the configuration file see the `qdrouterd.conf(5)`
+man page.
+
Modified: qpid/dispatch/branches/0.4/doc/book/introduction.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/introduction.rst?rev=1667868&r1=1667867&r2=1667868&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/introduction.rst (original)
+++ qpid/dispatch/branches/0.4/doc/book/introduction.rst Thu Mar 19 20:36:18 2015
@@ -38,7 +38,7 @@ does not *take responsibility for* messa
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 reciever back across
+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
@@ -70,7 +70,7 @@ senders publishing to a single address 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 difficult of "stuck messages" when implementing this
+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,
@@ -84,8 +84,8 @@ calculate the best path from every point
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
+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.
@@ -97,6 +97,10 @@ 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
@@ -106,8 +110,8 @@ Simplifies reliability
Features
--------
-- Supports arbitrary topology - no restrictions on redundancy
-- Automatic route computation - adjusts quickly to changes in topology
-- Cost-based route computation
-- `Rich addressing semantics <#addressing>`__
+- 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
Added: qpid/dispatch/branches/0.4/doc/book/link_routing.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/link_routing.rst?rev=1667868&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/link_routing.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/link_routing.rst Thu Mar 19 20:36:18 2015
@@ -0,0 +1,145 @@
+.. 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.
+
+Link Routing
+============
+
+This feature was introduced in Qpid Dispatch 0.4.
+
+Link-routing is an alternative strategy for routing messages across a
+network of routers. With the existing message-routing strategy, each
+router makes a routing decision on a per-message basis when the
+message is delivered. Link-routing is different because it makes
+routing decisions when link-attach frames arrive. A link is
+effectively chained across the network of routers from the
+establishing node to the destination node. Once the link is
+established, the transfer of message deliveries, flow frames, and
+dispositions is performed across the routed link.
+
+The main benefit to link-routing is that endpoints can use the full link
+protocol to interact with other endpoints in far-flung parts of the
+network. For example, a client can establish a receiver across the
+network to a queue on a remote broker and use link credit to control
+the flow of messages from the broker.
+
+Why would one want to do this? One reason is to provide client
+isolation. A network like the following can be deployed:
+
+::
+
+ Public Network
+ +-----------------+
+ | +-----+ |
+ | B1 | Rp | |
+ | +/--\-+ |
+ | / \ |
+ | / \ |
+ +----/--------\---+
+ / \
+ / \
+ / \
+ Private Net A / \ Private Net B
+ +--------------/--+ +---\-------------+
+ | +---/-+ | | +--\--+ |
+ | B2 | Ra | | | | Rb | C1 |
+ | +-----+ | | +-----+ |
+ | | | |
+ | | | |
+ +-----------------+ +-----------------+
+
+The clients in Private Net B can be constrained (by firewall policy)
+to only connect to the Router in their own network. Using
+link-routing, these clients can access queues, topics, and other AMQP
+services that are in the Public Network or even in Private Net A.
+
+For example, The router Ra can be configured to expose queues in
+broker B2 to the network. Client C1 can then establish a connection
+to Rb, the local router, open a subscribing link to "b2.event-queue",
+and receive messages stored on that queue in broker B2.
+
+C1 is unable to create a TCP/IP connection to B1 because of its
+isolation (and because B2 is itself in a private network). However,
+with link routing, C1 can interact with B2 using the AMQP link
+protocol.
+
+Note that in this case, neither C1 nor B2 have been modified in any
+way and neither need be aware of the fact that there is a
+message-router network between them.
+
+Configuration
+-------------
+
+Starting with the configured topology shown above, how is link-routing
+configured to support the example described above?
+
+First, router Ra needs to be told how to make a connection to the
+broker B2:
+
+::
+
+ connector {
+ name: broker
+ role: on-demand
+ addr: <B2-url>
+ port: <B2-port>
+ sasl-mechanisms: ANONYMOUS
+ }
+
+This *on-demand* connector tells the router how to connect to an
+external AMQP container when it is needed. The name "broker" will be
+used later to refer to this connection.
+
+Now, the router must be configured to route certain addresses to B2:
+
+::
+
+ linkRoutePattern {
+ prefix: b2.
+ connector: broker
+ }
+
+
+The linkRoutePattern tells router Ra that any sender or receiver that
+is attached with a target or source (respectively) whos address begins
+with "b2.", should be routed to the broker B2 (via the on-demand
+connector).
+
+When the on-demand connector is configured, router Ra establishes a
+connection to the broker. Once the connection is open, Ra tells the
+other routers (Rp and Rb) that it is a valid destination for
+link-routes to the "b2." prefix. This means that sender or receiver
+links attached to Rb or Rp will be routed via the shortest path to Ra
+where they are then routed outbound to the broker B2.
+
+On Rp and Rb, it is advisable to add the following configuration:
+
+::
+
+ linkRoutePattern {
+ prefix: b2.
+ }
+
+This configuration tells the routers that link-routing is intended to
+be available for targets and sources starting with "b2.". This is
+important because it is possible that B2 might be unavailable or shut
+off. If B2 is unreachable, Ra will not advertize itself as a
+destination for "b2." and the other routers might never know that
+"b2." was intended for link-routing.
+
+The above configuration allows Rb and Rp to reject attaches that
+should be routed to B2 with an error message that indicates that there
+is no route available to the destination.
Modified: qpid/dispatch/branches/0.4/doc/book/schema_rst.py
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/schema_rst.py?rev=1667868&r1=1667867&r2=1667868&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/schema_rst.py (original)
+++ qpid/dispatch/branches/0.4/doc/book/schema_rst.py Thu Mar 19 20:36:18 2015
@@ -43,6 +43,10 @@ All management entity types have the fol
without the `org.apache.qpid.dispatch` prefix e.g. `router`. The dispatch
tools will accept the short or long name.
+*name*
+ A user-generated identity for the entity. This can be used in other entities
+ that need to refer to the named entity.
+
*identity*
A system-generated identity of the entity. It includes
the short type name and some identifying information. E.g. `log/AGENT` or
Added: qpid/dispatch/branches/0.4/doc/book/technical_details.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/technical_details.rst?rev=1667868&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/technical_details.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/technical_details.rst Thu Mar 19 20:36:18 2015
@@ -0,0 +1,32 @@
+.. 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.
+
+.. Qpid Dispatch documentation master file, created by
+ sphinx-quickstart on Tue Feb 24 11:25:59 2015.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Technical Details and Specifications
+====================================
+
+.. toctree::
+ :maxdepth: 3
+
+ client_compatibility
+ addressing
+ amqp-mapping
+ schema
Added: qpid/dispatch/branches/0.4/doc/book/tools.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/tools.rst?rev=1667868&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/tools.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/tools.rst Thu Mar 19 20:36:18 2015
@@ -0,0 +1,75 @@
+.. 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.
+
+Tools
+=====
+
+qdstat
+------
+
+*qdstat* is a command line tool that lets you view the status of a
+Dispatch Router. The following options are useful for seeing that the
+router is doing:
+
++----------+-----------------------------------------------------------------------------+
+| *Option* | *Description* |
++==========+=============================================================================+
+| -l |Print a list of AMQP links attached to the router. Links are |
+| |unidirectional. Outgoing links are usually associated with a subscription |
+| |address. The tool distinguishes between *endpoint* links and *router* |
+| |links. Endpoint links are attached to clients using the router. Router links |
+| |are attached to other routers in a network of routbers. |
+| | |
++----------+-----------------------------------------------------------------------------+
+| -a |Print a list of addresses known to the router. |
++----------+-----------------------------------------------------------------------------+
+| -n |Print a list of known routers in the network. |
++----------+-----------------------------------------------------------------------------+
+| -c |Print a list of connections to the router. |
++----------+-----------------------------------------------------------------------------+
+
+For complete details see the `qdstat(8)` man page and the output of
+`qdstat --help`.
+
+qdmanage
+--------
+
+*qdmanage* is a general-purpose AMQP management client that allows you
+to not only view but modify the configuration of a running dispatch
+router.
+
+For example you can query all the connection entities in the router::
+
+ $ qdrouterd query --type connection
+
+To enable logging debug and higher level messages by default::
+
+ $ qdrouter update log/DEFAULT enable=debug+
+
+In fact, everything that can be configured in the configuration file can
+also be created in a running router via management. For example to
+create a new listener in a running router::
+
+ $ qdrouter create type=listener port=5555
+
+Now you can connect to port 5555, for exampple::
+
+ $ qdrouterd query -b localhost:5555 --type listener
+
+For complete details see the `qdmanage(8)` man page and the output of
+`qdmanage --help`. Also for details of what can be configured see the
+`qdrouterd.conf(5)` man page.
Modified: qpid/dispatch/branches/0.4/doc/book/using.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/using.rst?rev=1667868&r1=1667867&r2=1667868&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/using.rst (original)
+++ qpid/dispatch/branches/0.4/doc/book/using.rst Thu Mar 19 20:36:18 2015
@@ -18,273 +18,12 @@
Using Qpid Dispatch
===================
-Configuration
--------------
+.. toctree::
+ :maxdepth: 3
-The default configuration file is installed in
-`install-prefix`/etc/qpid/qdrouterd.conf. This configuration file will
-cause the router to run in standalone mode, listening on the standard
-AMQP port (5672). Dispatch Router looks for the configuration file in
-the installed location by default. If you wish to use a different path,
-the "-c" command line option will instruct Dispatch Router as to which
-configuration to load.
+ default_config
+ tools
+ basic_usage
+ link_routing
-To run the router, invoke the executable: qdrouterd [-c my-config-file]
-For more details of the configuration file see the `qdrouterd.conf(5)`
-man page.
-
-Client Compatibility
---------------------
-
-Dispatch Router should, in theory, work with any client that is
-compatible with AMQP 1.0. The following clients have been tested:
-
-+-----------------+------------------------------------------------------------------+
-| *Client* | *Notes* |
-+=================+==================================================================+
-| qpid::messaging |The Qpid messaging clients work with Dispatch Router as long as |
-| |they are configured to use the 1.0 version of the protocol. To |
-| |enable AMQP 1.0 in the C++ client, use the {protocol:amqp1.0} |
-| |connection option. |
-| | |
-| | |
-| | |
-| | |
-| | |
-| | |
-| | |
-| | |
-| | |
-+-----------------+------------------------------------------------------------------+
-| Proton Messenger| Messenger works with Dispatch Router. |
-| | |
-| | |
-+-----------------+------------------------------------------------------------------+
-
-Tools
------
-
-qdstat
-~~~~~~
-
-*qdstat* is a command line tool that lets you view the status of a
-Dispatch Router. The following options are useful for seeing that the
-router is doing:
-
-+----------+-----------------------------------------------------------------------------+
-| *Option* | *Description* |
-+==========+=============================================================================+
-| -l |Print a list of AMQP links attached to the router. Links are |
-| |unidirectional. Outgoing links are usually associated with a subscription |
-| |address. The tool distinguishes between *endpoint* links and *router* |
-| |links. Endpoint links are attached to clients using the router. Router links |
-| |are attached to other routers in a network of routbers. |
-| | |
-+----------+-----------------------------------------------------------------------------+
-| -a |Print a list of addresses known to the router. |
-+----------+-----------------------------------------------------------------------------+
-| -n |Print a list of known routers in the network. |
-+----------+-----------------------------------------------------------------------------+
-| -c |Print a list of connections to the router. |
-+----------+-----------------------------------------------------------------------------+
-
-For complete details see the `qdstat(8)` man page and the output of
-`qdstat --help`.
-
-qdmanage
-~~~~~~~~
-
-*qdmanage* is a general-purpose AMQP management client that allows you
-to not only view but modify the configuration of a running dispatch
-router.
-
-For example you can query all the connection entities in the router::
-
- $ qdrouterd query --type connection
-
-To enable logging debug and higher level messages by default::
-
- $ qdrouter update log/DEFAULT enable=debug+
-
-In fact, everything that can be configured in the configuration file can
-also be created in a running router via management. For example to
-create a new listener in a running router::
-
- $ qdrouter create type=listener port=5555
-
-Now you can connect to port 5555, for exampple::
-
- $ qdrouterd query -b localhost:5555 --type listener
-
-For complete details see the `qdmanage(8)` man page and the output of
-`qdmanage --help`. Also for details of what can be configured see the
-`qdrouterd.conf(5)` man page.
-
-Features and Examples
----------------------
-
-Standalone and Interior Modes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The router can operate stand-alone or as a node in a network of routers.
-The mode is configured in the *router* section of the configuration
-file. In stand-alone mode, the router does not attempt to collaborate
-with any other routers and only routes messages among directly connected
-endpoints.
-
-If your router is running in stand-alone mode, *qdstat -a* will look
-like the following:
-
-::
-
- $ qdstat -a
- Router Addresses
- class address in-proc local remote in out thru to-proc from-proc
- ===============================================================================
- local $management Y 0 0 1 0 0 1 0
- local temp.AY81ga 1 0 0 0 0 0 0
-
-Note that there are two known addresses. *$management* is the address of
-the router's embedded management agent. *temp.AY81ga* is the temporary
-reply-to address of the *qdstat* client making requests to the agent.
-
-If you change the mode to interior and restart the processs, the same
-command will yield two additional addresses which are used for
-inter-router communication:
-
-::
-
- $ qdstat -a
- Router Addresses
- class address in-proc local remote in out thru to-proc from-proc
- ===============================================================================
- local $management Y 0 0 1 0 0 1 0
- local qdhello Y 0 0 0 0 0 0 3
- local qdrouter Y 0 0 0 0 0 0 1
- local temp.khOpGb 1 0 0 0 0 0 0
-
-Mobile Subscribers
-~~~~~~~~~~~~~~~~~~
-
-The term "mobile subscriber" simply refers to the fact that a client may
-connect to the router and subscribe to an address to receive messages
-sent to that address. No matter where in the network the subscriber
-attaches, the messages will be routed to the appropriate destination.
-
-To illustrate a subscription on a stand-alone router, you can use the
-examples that are provided with Qpid Proton. Using the *recv.py* example
-receiver:
-
-::
-
- $ recv.py amqp://0.0.0.0/my-address
-
-This command creates a receiving link subscribed to the specified
-address. To verify the subscription:
-
-::
-
- $ qdstat -a
- Router Addresses
- class address in-proc local remote in out thru to-proc from-proc
- ================================================================================
- local $management Y 0 0 1 0 0 1 0
- mobile my-address 1 0 0 0 0 0 0
- local temp.fDt8_a 1 0 0 0 0 0 0
-
-You can then, in a separate command window, run a sender to produce
-messages to that address:
-
-::
-
- $ send.py -a amqp://0.0.0.0/my-address
-
-Dynamic Reply-To
-~~~~~~~~~~~~~~~~
-
-Dynamic reply-to can be used to obtain a reply-to address that routes
-back to a client's receiving link regardless of how many hops it has to
-take to get there. To illustrate this feature, see below a simple
-program (written in C++ against the qpid::messaging API) that queries
-the management agent of the attached router for a list of other known
-routers' management addresses.
-
-::
-
- #include <qpid/messaging/Address.h>
- #include <qpid/messaging/Connection.h>
- #include <qpid/messaging/Message.h>
- #include <qpid/messaging/Receiver.h>
- #include <qpid/messaging/Sender.h>
- #include <qpid/messaging/Session.h>
-
- using namespace qpid::messaging;
- using namespace qpid::types;
-
- using std::stringstream;
- using std::string;
-
- int main() {
- const char* url = "amqp:tcp:127.0.0.1:5672";
- std::string connectionOptions = "{protocol:amqp1.0}";
-
- Connection connection(url, connectionOptions);
- connection.open();
- Session session = connection.createSession();
- Sender sender = session.createSender("mgmt");
-
- // create reply receiver and get the reply-to address
- Receiver receiver = session.createReceiver("#");
- Address responseAddress = receiver.getAddress();
-
- Message request;
- request.setReplyTo(responseAddress);
- request.setProperty("x-amqp-to", "amqp:/_local/$management");
- request.setProperty("operation", "DISCOVER-MGMT-NODES");
- request.setProperty("type", "org.amqp.management");
- request.setProperty("name, "self");
-
- sender.send(request);
- Message response = receiver.fetch();
- Variant content(response.getContentObject());
- std::cout << "Response: " << content << std::endl << std::endl;
-
- connection.close();
- }
-
-The equivalent program written in Python against the Proton Messenger
-API:
-
-::
-
- from proton import Messenger, Message
-
- def main():
- host = "0.0.0.0:5672"
-
- messenger = Messenger()
- messenger.start()
- messenger.route("amqp:/*", "amqp://%s/$1" % host)
- reply_subscription = messenger.subscribe("amqp:/#")
- reply_address = reply_subscription.address
-
- request = Message()
- response = Message()
-
- request.address = "amqp:/_local/$management"
- request.reply_to = reply_address
- request.properties = {u'operation' : u'DISCOVER-MGMT-NODES',
- u'type' : u'org.amqp.management',
- u'name' : u'self'}
-
- messenger.put(request)
- messenger.send()
- messenger.recv()
- messenger.get(response)
-
- print "Response: %r" % response.body
-
- messenger.stop()
-
- main()
Modified: qpid/dispatch/branches/0.4/python/qpid_dispatch/management/qdrouter.json
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/python/qpid_dispatch/management/qdrouter.json?rev=1667868&r1=1667867&r2=1667868&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/python/qpid_dispatch/management/qdrouter.json (original)
+++ qpid/dispatch/branches/0.4/python/qpid_dispatch/management/qdrouter.json Thu Mar 19 20:36:18 2015
@@ -726,18 +726,18 @@
},
"linkRoutePattern": {
- "description":"A pattern to match a connected container to endpoints for routed links.",
+ "description":"An address pattern to match against link sources and targets to cause the router to link-route the attach across the network to a remote node.",
"extends": "configurationEntity",
"operations": ["CREATE"],
"attributes": {
"prefix": {
- "description":"The AMQP address prefix for nodes on the container.",
+ "description":"An address prefix to match against target and source addresses. For Dispatch 0.4, this pattern must be of the form '<text>.' and matches any address that contains that prefix. Note that the prefix *must* end with a period (.) and *must not* contain any other periods.",
"type": "string",
"required": true,
"create": true
},
"connector": {
- "description":"The name of the on-demand connector used to reach the waypoint's container.",
+ "description":"The name of the on-demand connector used to reach the target node's container. If this value is not provided, it means that the target container is expected to be connected to a different router in the network. This prevents links to a link-routable address from being misinterpreted as message-routing links when there is no route to a valid destination available.",
"type": "string",
"required": false,
"default": "",
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org