You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2015/03/12 15:34:29 UTC
svn commit: r1666214 [1/3] - in /qpid/dispatch/branches/0.4: doc/ doc/book/
doc/man/ doc/notes/ python/qpid_dispatch_internal/management/
Author: aconway
Date: Thu Mar 12 14:34:28 2015
New Revision: 1666214
URL: http://svn.apache.org/r1666214
Log:
DISPATCH-125: Convert documentation to rst, generate book and HTML man pages from sphinx.
Sphinx and RST are more complete & flexible documentation tools.
- Converted doc to RST (using pandoc)
- Generate HTML book and HTML man pages with sphinx
- Generating man pages with sphinx
NOTE: to install everything including documentation you need to do:
make all
make doc
make install
Note that "make doc install" will not install the doc properly (the install runs
before building the docs)
Added:
qpid/dispatch/branches/0.4/doc/README.rst
qpid/dispatch/branches/0.4/doc/TODO
- copied, changed from r1665930, qpid/dispatch/branches/0.4/doc/book/TODO
qpid/dispatch/branches/0.4/doc/book/addressing.rst
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
- copied, changed from r1665930, qpid/dispatch/branches/0.4/doc/book/schema_md.py
qpid/dispatch/branches/0.4/doc/book/using.rst
qpid/dispatch/branches/0.4/doc/conf.py.in
qpid/dispatch/branches/0.4/doc/index.rst
qpid/dispatch/branches/0.4/doc/man/*shell*
qpid/dispatch/branches/0.4/doc/man/help2rst.py
- copied, changed from r1665930, qpid/dispatch/branches/0.4/doc/man/help2md.py
qpid/dispatch/branches/0.4/doc/man/qdmanage.rst.in
qpid/dispatch/branches/0.4/doc/man/qdrouterd.rst.in
qpid/dispatch/branches/0.4/doc/man/qdstat.rst
qpid/dispatch/branches/0.4/doc/notes/code-conventions.rst
Removed:
qpid/dispatch/branches/0.4/doc/README
qpid/dispatch/branches/0.4/doc/book/README
qpid/dispatch/branches/0.4/doc/book/TODO
qpid/dispatch/branches/0.4/doc/book/addressing.md
qpid/dispatch/branches/0.4/doc/book/amqp-mapping.md
qpid/dispatch/branches/0.4/doc/book/introduction.md
qpid/dispatch/branches/0.4/doc/book/release-0.1.md
qpid/dispatch/branches/0.4/doc/book/schema_md.py
qpid/dispatch/branches/0.4/doc/book/site-html.pd
qpid/dispatch/branches/0.4/doc/book/using.md
qpid/dispatch/branches/0.4/doc/index.md
qpid/dispatch/branches/0.4/doc/man/README
qpid/dispatch/branches/0.4/doc/man/help2md.py
qpid/dispatch/branches/0.4/doc/man/man.template.pd
qpid/dispatch/branches/0.4/doc/man/man2book.py
qpid/dispatch/branches/0.4/doc/man/qdrouterd.8.noopt.md.in
qpid/dispatch/branches/0.4/doc/man/qdstat.8.noopt.md.in
qpid/dispatch/branches/0.4/doc/notes/code-conventions.md
Modified:
qpid/dispatch/branches/0.4/doc/CMakeLists.txt
qpid/dispatch/branches/0.4/doc/man/qdrouterd_conf_man.py
qpid/dispatch/branches/0.4/python/qpid_dispatch_internal/management/schema_doc.py
Modified: qpid/dispatch/branches/0.4/doc/CMakeLists.txt
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/CMakeLists.txt?rev=1666214&r1=1666213&r2=1666214&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/doc/CMakeLists.txt (original)
+++ qpid/dispatch/branches/0.4/doc/CMakeLists.txt Thu Mar 12 14:34:28 2015
@@ -18,16 +18,30 @@
##
+# In recent versions of cmake the documentation is not built automatically, you need to
+# run "make doc", so you can leave this ON. In older (< 2.8) versions, documentation
+# is built by "make all" so you need to turn BUILD_DOCS OFF if you don't want that.
option(BUILD_DOCS "Generate documentation" ON)
-set(src ${CMAKE_CURRENT_SOURCE_DIR})
-set(bin ${CMAKE_CURRENT_BINARY_DIR})
-
if(BUILD_DOCS)
+ set(src ${CMAKE_CURRENT_SOURCE_DIR})
+ set(bin ${CMAKE_CURRENT_BINARY_DIR})
+ set(tools ${CMAKE_SOURCE_DIR}/tools)
+
+ if ("${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION}" VERSION_LESS "2.8")
+ # OPTIONAL does not exist in install before 2.8 so always make docs and install
+ add_custom_target(doc ALL)
+ else()
+ set (OPTIONAL OPTIONAL)
+ add_custom_target(doc)
+ endif()
+ macro(install_doc)
+ install(${ARGN} ${OPTIONAL})
+ endmacro()
+
find_package(Doxygen)
- find_program(PANDOC pandoc)
- find_program(PDFLATEX pdflatex)
+ find_program(SPHINX_BUILD sphinx-build)
# Create an option to enable/disable a doc tool and check if the tool is present.
# If tool is present, option defaults to ON else OFF.
@@ -47,25 +61,83 @@ if(BUILD_DOCS)
endif(${var})
endmacro()
- doc_tool(pandoc USE_PANDOC PANDOC "HTML and man page documentation")
- doc_tool(pdflatex USE_PDFLATEX PDFLATEX "PDF documentation (also requires pandoc)")
+ doc_tool(sphinx-build USE_SPHINX SPHINX_BUILD "HTML and man page documentation")
doc_tool(doxygen USE_DOXYGEN DOXYGEN_FOUND "API documentation")
doc_tool(dot USE_DOT DOT "diagrams in API documentation (also requires doxygen)")
- add_subdirectory(api)
- add_subdirectory(man)
- add_subdirectory(book)
-
- # Index for installed doc
- install(FILES ${src}/index.md DESTINATION ${QD_DOC_INSTALL_DIR})
- if(USE_PANDOC)
+ file(REMOVE_RECURSE ${bin}) # Force rebuild after re-configuration.
+ file(MAKE_DIRECTORY ${bin}/book ${bin}/man)
+
+ # Copy configuration and rst sources to build directory to generate book.
+ # Use configure_file to ensure we re-copy if the source changes.
+ configure_file(${src}/conf.py.in ${bin}/conf.py)
+ configure_file(${src}/man/qdmanage.rst.in ${bin}/man/qdmanage.rst)
+ configure_file(${src}/man/qdrouterd.rst.in ${bin}/man/qdrouterd.rst)
+ file(GLOB_RECURSE RST_SRC RELATIVE ${src} *.rst)
+ foreach(file ${RST_SRC})
+ configure_file(${src}/${file} ${bin}/${file} COPYONLY)
+ endforeach()
+
+ # Generate files from management schema
+ set(schema, "${CMAKE_SOURCE_DIR}/python/qpid_router/management/qdrouterd.json")
+ set(py_management ${CMAKE_SOURCE_DIR}/python/qpid_dispatch_internal/management)
+ set(schema_gen_deps ${py_management}/schema_doc.py ${py_management}/schema.py ${schema})
+
+ macro(schema_gen output script)
+ add_custom_command(
+ OUTPUT ${output}
+ COMMAND ${RUN} -s ${script} 1> ${output}
+ DEPENDS ${script} ${schema_gen_deps}
+ )
+ list(APPEND SCHEMA_GEN ${output})
+ endmacro()
+
+ schema_gen(${bin}/book/schema.rst ${src}/book/schema_rst.py)
+ schema_gen(${bin}/man/qdrouterd.conf.rst ${src}/man/qdrouterd_conf_man.py)
+
+ add_custom_target(doc-schema DEPENDS ${SCHEMA_GEN})
+ add_dependencies(doc doc-schema)
+
+ # Generate rst text from --help output for man pages
+ macro(help2rst program path)
+ set(help ${bin}/man/${program}_help.rst)
+ list(APPEND HELP_GEN ${help})
+ add_custom_command (
+ OUTPUT ${help}
+ COMMAND ${RUN} -s ${src}/man/help2rst.py ${path}/${program} --help > ${help}
+ DEPENDS ${path}/${program} ${schema_doc} ${src}/man/help2rst.py
+ )
+ endmacro()
+
+ help2rst(qdrouterd ${CMAKE_BINARY_DIR}/router)
+ help2rst(qdstat ${tools})
+ help2rst(qdmanage ${tools})
+
+ # Run sphinx to generate HTML and man pages
+ if(USE_SPHINX)
+ foreach(manpage qdmanage.8 qdrouterd.8 qdrouterd.conf.5 qdstat.8)
+ list(APPEND MAN_PAGES ${bin}/man/${manpage})
+ string(REGEX MATCH "[0-9]*$" section ${manpage})
+ install_doc(FILES ${bin}/man/${manpage}
+ DESTINATION ${CMAKE_INSTALL_PREFIX}/${MAN_INSTALL_DIR}/man${section})
+ endforeach()
+
+ set(SPHINX_OUTPUT ${bin}/html/index.html ${bin}/singlehtml/book/book.html ${MAN_PAGES})
+
add_custom_command(
- OUTPUT ${bin}/index.html
- COMMAND ${PANDOC} --standalone -f markdown -t html -o ${bin}/index.html ${src}/index.md
- DEPENDS ${src}/index.md
+ OUTPUT ${SPHINX_OUTPUT}
+ COMMAND ${SPHINX_BUILD} -d ${bin}/doctrees -b html ${bin} ${bin}/html
+ COMMAND ${SPHINX_BUILD} -d ${bin}/doctrees -b man ${bin} ${bin}/man
+ COMMAND ${SPHINX_BUILD} -d ${bin}/doctrees -b singlehtml -Dmaster_doc=book/book ${bin} ${bin}/htmlsingle
+ DEPENDS ${RST_SRC} ${HELP_GEN} ${SCHEMA_GEN}
)
- add_custom_target(doc-index ALL DEPENDS ${bin}/index.html)
- install(FILES ${bin}/index.html DESTINATION ${QD_DOC_INSTALL_DIR})
- endif(USE_PANDOC)
+ add_custom_target(doc-sphinx DEPENDS ${SPHINX_OUTPUT})
+ add_dependencies(doc doc-sphinx)
+
+ install_doc(DIRECTORY ${bin}/html DESTINATION ${QD_DOC_INSTALL_DIR})
+ endif(USE_SPHINX)
+
+ # Install rst documentation as baseline in case we have no generator
+ install_doc(DIRECTORY ${bin}/book DESTINATION ${QD_DOC_INSTALL_DIR})
endif(BUILD_DOCS)
Added: qpid/dispatch/branches/0.4/doc/README.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/README.rst?rev=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/README.rst (added)
+++ qpid/dispatch/branches/0.4/doc/README.rst Thu Mar 12 14:34:28 2015
@@ -0,0 +1,71 @@
+.. 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
+ nspecific language governing permissions and limitations
+ under the License.
+
+Building documentation
+======================
+
+Build the documentation with ``make doc``.
+
+If you have an older verbsion of cmake, the documentation may be built when you
+do ``make all``. If so you can disable documentation build with
+
+::
+
+ cmake -DBUILD_DOCS=OFF
+
+You need the following tools to build the documentation:
+
+- python-sphinx (1.1.3) for book and man pages (requires python-docutils)
+- doxygen (1.8) for API documentation.
+- graphviz (2.34) for ``dot`` program needed to include diagrams in API documentation.
+
+The versions above are known to work, earlier versions may or may not.
+
+Writing documentation
+=====================
+
+Documentation is written in `reStructuedText <http://docutils.sourceforge.net/rst.html>`__
+
+All rst and html format documentation is installed in the share/doc directory.
+Man pages are also installed in the standard share/man locations.
+
+The `dispatch web site <http://qpid.apache.org/components/dispatch-router>`__
+has pre-generated documentation for each release and a random snapshot of the
+trunk.
+
+Documentation sub-directories:
+
+- ``book/``: Book-format documentation.
+- ``man/``: Unix man pages.
+- ``api/``: Generated API documentation.
+- ``notes/``: Developer notes: project information, design notes, or
+ anything else that's primarily of developer interest. These are not
+ installed.
+
+Editing the book.
+=================
+
+Most chapters of the book are restructuredText_ files, you can edit them with
+any text editor. See the `quick reference`_ for a handy guide to syntax.
+
+Some chapters are generated by python scripts rather than being simple
+source files. For example ``schema.md`` is generated by ``schema_md.py``
+from the documentation strings in the management schema
+``qdrouterd.json``.
+
+.. _restructuredText: http://docutils.sourceforge.net/rst.html
+.. _`quick reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
Copied: qpid/dispatch/branches/0.4/doc/TODO (from r1665930, qpid/dispatch/branches/0.4/doc/book/TODO)
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/TODO?p2=qpid/dispatch/branches/0.4/doc/TODO&p1=qpid/dispatch/branches/0.4/doc/book/TODO&r1=1665930&r2=1666214&rev=1666214&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/TODO (original)
+++ qpid/dispatch/branches/0.4/doc/TODO Thu Mar 12 14:34:28 2015
@@ -6,9 +6,9 @@
;; 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
Added: qpid/dispatch/branches/0.4/doc/book/addressing.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/addressing.rst?rev=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/addressing.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/addressing.rst Thu Mar 12 14:34:28 2015
@@ -0,0 +1,127 @@
+.. 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.
+
+Addressing
+==========
+
+AMQP addresses are used to control the flow of messages across a network
+of routers. Addresses are used in a number of different places in the
+AMQP 1.0 protocol. They can be used in a specific message in the `to`
+and `reply-to` fields of a message's properties. They are also used
+during the creation of links in the `address` field of a `source` or
+a `target`.
+
+Addresses designate various kinds of entities in a messaging network:
+
+- Endpoint processes that consume data or offer a service
+- Topics that match multiple consumers to multiple producers
+- Entities within a messaging broker:
+ - Queues
+ - Durable Topics
+ - Exchanges
+
+The syntax of an AMQP address is opaque as far as the router network is
+concerned. A syntactical structure may be used by the administrator that
+creates addresses, but the router treats them as opaque strings. Routers
+consider addresses to be mobile such that any address may be directly
+connected to any router in a network and may move around the topology.
+In cases where messages are broadcast to or balanced across multiple
+consumers, an address may be connected to multiple routers in the
+network.
+
+Addresses have semantics associated with them. When an address is
+created in the network, it is assigned a set of semantics (and access
+rules) during a process called provisioning. The semantics of an address
+control how routers behave when they see the address being used.
+
+Address semantics include the following considerations:
+
+- *Routing pattern* - direct, multicast, balanced
+- *Undeliverable action* - drop, hold and retry, redirect
+- *Reliability* - N destinations, etc.
+
+Routing patterns
+----------------
+
+Routing patterns constrain the paths that a message can take across a
+network.
+
++---------------+-------------------------------------------------------------------------+
+| *Pattern* | *Description* |
++===============+=========================================================================+
+| *Direct* |Direct routing allows for only one consumer to use an address at a |
+| |time. Messages (or links) follow the lowest cost path across the network |
+| |from the sender to the one receiver. |
++---------------+-------------------------------------------------------------------------+
+| *Multicast* |Multicast routing allows multiple consumers to use the same address at |
+| |the same time. Messages are routed such that each consumer receives a |
+| |copy of the message. |
++---------------+-------------------------------------------------------------------------+
+| *Balanced* |Balanced routing also allows multiple consumers to use the same |
+| |address. In this case, messages are routed to exactly one of the |
+| |consumers, and the network attempts to balance the traffic load across |
+| |the set of consumers using the same address. |
++---------------+-------------------------------------------------------------------------+
+
+Routing mechanisms
+------------------
+
+The fact that addresses can be used in different ways suggests that
+message routing can be accomplished in different ways. Before going into
+the specifics of the different routing mechanisms, it would be good to
+first define what is meant by the term *routing*:
+
+ In a network built of multiple routers connected by connections
+ (i.e., nodes and edges in a graph), *routing* determines which
+ connection to use to send a message directly to its destination or
+ one step closer to its destination.
+
+Each router serves as the terminus of a collection of incoming and
+outgoing links. The links either connect directly to endpoints that
+produce and consume messages, or they connect to other routers in the
+network along previously established connections.
+
+Message routing
+~~~~~~~~~~~~~~~
+
+Message routing occurs upon delivery of a message and is done based on
+the address in the message's `to` field.
+
+When a delivery arrives on an incoming link, the router extracts the
+address from the delivered message's `to` field and looks the address
+up in its routing table. The lookup results in zero or more outgoing
+links onto which the message shall be resent.
+
++-----------------+-----------------------------------------------------------------------+
+| *Delivery* | *Handling* |
++=================+=======================================================================+
+| *pre-settled* |If the arriving delivery is pre-settled (i.e., fire and forget), the |
+| |incoming delivery shall be settled by the router, and the outgoing |
+| |deliveries shall also be pre-settled. In other words, the pre-settled |
+| |nature of the message delivery is propagated across the network to the |
+| |message's destination. |
+| | |
++-----------------+-----------------------------------------------------------------------+
+| *unsettled* |Unsettled delivery is also propagated across the network. Because |
+| |unsettled delivery records cannot be discarded, the router tracks the |
+| |incoming deliveries and keeps the association of the incoming |
+| |deliveries to the resulting outgoing deliveries. This kept association |
+| |allows the router to continue to propagate changes in delivery state |
+| |(settlement and disposition) back and forth along the path which the |
+| |message traveled. |
+| | |
++-----------------+-----------------------------------------------------------------------+
Added: 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=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/amqp-mapping.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/amqp-mapping.rst Thu Mar 12 14:34:28 2015
@@ -0,0 +1,204 @@
+.. 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.
+
+AMQP Mapping
+============
+
+Dispatch Router is an AMQP router and as such, it provides extensions,
+code-points, and semantics for routing over AMQP. This page documents the
+details of Dispatch Router's use of AMQP.
+
+Message Annotations
+-------------------
+
+The following Message Annotation fields are defined by Dispatch Router:
+
++--------------------+------------------+-------------------------------------------------------+
+| *Field* | *Type* | *Description* |
++====================+==================+=======================================================+
+| x-opt-qd.ingress | string |The identity of the ingress router for a message-routed|
+| | |message. The ingress router is the first router |
+| | |encountered by a transiting message. The router will, |
+| | |if this field is present, leave it unaltered. If the |
+| | |field is not present, the router shall insert the field|
+| | |with its own identity. |
+| | | |
+| | | |
+| | | |
++--------------------+------------------+-------------------------------------------------------+
+| x-opt-qd.trace | list of string |The list of routers through which this message-routed |
+| | |message has transited. If this field is not present, |
+| | |the router shall do nothing. If the field is present, |
+| | |the router shall append its own identity to the end of |
+| | |the list. |
+| | | |
+| | | |
++--------------------+------------------+-------------------------------------------------------+
+| x-opt-qd.to | string |To-Override for message-routed messages. If this field |
+| | |is present, the address in this field shall be used for|
+| | |routing in lieu of the *to* field in the message |
+| | |properties. A router may append, remove, or modify this|
+| | |annotation field depending on the policy in place for |
+| | |routing the message. |
+| | | |
+| | | |
+| | | |
++--------------------+------------------+-------------------------------------------------------+
+| x-opt-qd.class | string |Message class. This is used to allow the router to |
+| | |provide separate paths for different classes of |
+| | |traffic. |
++--------------------+------------------+-------------------------------------------------------+
+
+Source/Target Capabilities
+--------------------------
+
+The following Capability values are used in Sources and Targets.
+
++----------------+----------------------------------------------------------------------------+
+| *Capability* | *Description* |
++================+============================================================================+
+| qd.router |This capability is added to sources and targets that are used for |
+| |inter-router message exchange. |
+| | |
++----------------+----------------------------------------------------------------------------+
+
+Dynamic-Node-Properties
+-----------------------
+
+The following dynamic-node-properties are used by Dispatch in Sources.
+
++--------------------+-----------------------------------------------------------------------+
+| *Property* | *Description* |
++====================+=======================================================================+
+| x-opt-qd.address |The node address describing the destination desired for a dynamic |
+| |source. If this is absent, the router will terminate any dynamic |
+| |receivers. If this address is present, the router will use the address |
+| |to route the dynamic link attach to the proper destination container. |
+| | |
++--------------------+-----------------------------------------------------------------------+
+
+Addresses and Address Formats
+-----------------------------
+
+The following AMQP addresses and address patterns are used within
+Dispatch Router.
+
+Address Patterns
+~~~~~~~~~~~~~~~~
+
++--------------------------------+-------------------------------------------------------+
+| *Pattern* | *Description* |
++================================+=======================================================+
+| `_local/<addr>` |An address that references a locally attached |
+| |endpoint. Messages using this address pattern shall not|
+| |be routed over more than one link. |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
++--------------------------------+-------------------------------------------------------+
+| `_topo/<area>/<router>/<addr>` |An address that references an endpoint attached to a |
+| |specific router node in the network topology. Messages |
+| |with addresses that follow this pattern shall be routed|
+| |along the shortest path to the specified router. Note |
+| |that addresses of this form are a-priori routable in |
+| |that the address itself contains enough information to |
+| |route the message to its destination. |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
++--------------------------------+-------------------------------------------------------+
+| `<addr>` |A mobile address. An address of this format represents |
+| |an endpoint or a set of distinct endpoints that are |
+| |attached to the network in arbitrary locations. It is |
+| |the responsibility of the router network to determine |
+| |which router nodes are valid destinations for mobile |
+| |addresses. |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
++--------------------------------+-------------------------------------------------------+
+
+Supported Addresses
+~~~~~~~~~~~~~~~~~~~
+
++------------------------------+------------------------------------------------------------+
+| *Address* | *Description* |
++==============================+============================================================+
+| `_local/$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. |
++------------------------------+------------------------------------------------------------+
+| `_topo/0/Router.E/agent` |The management agent at Router.E in area 0. This address |
+| |would be used by a management client wishing to access |
+| |management data from a specific container that is reachable |
+| |within the network. |
++------------------------------+------------------------------------------------------------+
+| `_local/qdhello` |The router entity in each of the connected routers. This |
+| |address is used to communicate with neighbor routers and is |
+| |exclusively for the HELLO discovery protocol. |
++------------------------------+------------------------------------------------------------+
+| `_local/qdrouter` |The router entity in each of the connected routers. This |
+| |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|
+| |address form is used by a router to communicate with a |
+| |specific router that may or may not be a neighbor. |
++------------------------------+------------------------------------------------------------+
+
+Implementation of the AMQP Management Specification
+---------------------------------------------------
+
+Qpid Dispatch is manageable remotely via AMQP. It is compliant with the
+emerging AMQP Management specification (draft 9).
+
+Differences from the specification:
+
+- The `name` attribute is not required when an entity is created. If
+ not supplied it will be set to the same value as the system-generated
+ "identity" attribute. Otherwise it is treated as per the standard.
+- The `REGISTER` and `DEREGISTER` operations are not implemented. The router
+ automatically discovers peer routers via the router network and makes
+ their management addresses available via the standard GET-MGMT-NODES
+ operation.
Added: 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=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/book.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/book.rst Thu Mar 12 14:34:28 2015
@@ -0,0 +1,17 @@
+.. 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.
+
+Qpid Dispatch Router Book
+=========================
+
+.. toctree::
+ :numbered:
+ :maxdepth: 3
+
+ introduction
+ using
+ addressing
+ amqp-mapping
+ schema
Added: 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=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/introduction.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/introduction.rst Thu Mar 12 14:34:28 2015
@@ -0,0 +1,113 @@
+.. 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 reciever 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 difficult 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
+
+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
+--------
+
+- Supports arbitrary topology - no restrictions on redundancy
+- Automatic route computation - adjusts quickly to changes in topology
+- Cost-based route computation
+- `Rich addressing semantics <#addressing>`__
+- Security
Copied: qpid/dispatch/branches/0.4/doc/book/schema_rst.py (from r1665930, qpid/dispatch/branches/0.4/doc/book/schema_md.py)
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/book/schema_rst.py?p2=qpid/dispatch/branches/0.4/doc/book/schema_rst.py&p1=qpid/dispatch/branches/0.4/doc/book/schema_md.py&r1=1665930&r2=1666214&rev=1666214&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/schema_md.py (original)
+++ qpid/dispatch/branches/0.4/doc/book/schema_rst.py Thu Mar 12 14:34:28 2015
@@ -37,23 +37,26 @@ updated. Some entity types also support
All management entity types have the following standard attributes:
-- *type*: The fully qualified type of the entity,
+*type*
+ The fully qualified type of the entity,
e.g. `org.apache.qpid.dispatch.router`. This document uses the short name
without the `org.apache.qpid.dispatch` prefix e.g. `router`. The dispatch
tools will accept the short or long name.
-- *identity*: A system-generated identity of the entity. It includes
+*identity*
+ A system-generated identity of the entity. It includes
the short type name and some identifying information. E.g. `log/AGENT` or
`listener/localhost:amqp`
There are two main categories of management entity type.
-- *Configuration* Entities: Parameters that can be set in the configuration file
+*Configuration* Entities
+ Parameters that can be set in the configuration file
(see `qdrouterd.conf(5)` man page) or set at run-time with the `qdmanage(8)`
tool.
-- *Operational* Entities: Run-time status values that can be queried using
- `qdstat(8)` or `qdmanage(8)` tools.
+*Operational* Entities
+ Run-time status values that can be queried using `qdstat(8)` or `qdmanage(8)` tools.
""")
with self.section("Configuration Entities"):
@@ -70,7 +73,7 @@ be modified using the `update` operation
self.writeln("""
Operational entities provide statistics and other run-time attributes of the router.
The `qdstat(8)` tool provides a convenient way to query run-time statistics.
-You can also use the general-purpose management tool `qdmanage(8)` to query
+You can also use the general-purpose management tool `qdmanage(8)` to query
operational attributes.
""")
self.entity_types_extending("operationalEntity")
Added: 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=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/book/using.rst (added)
+++ qpid/dispatch/branches/0.4/doc/book/using.rst Thu Mar 12 14:34:28 2015
@@ -0,0 +1,290 @@
+.. 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.
+
+Using Qpid Dispatch
+===================
+
+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.
+
+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()
Added: qpid/dispatch/branches/0.4/doc/conf.py.in
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/conf.py.in?rev=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/conf.py.in (added)
+++ qpid/dispatch/branches/0.4/doc/conf.py.in Thu Mar 12 14:34:28 2015
@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+# Sphinx configuration file.
+
+import sys, os
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Qpid Dispatch'
+copyright = u'2013, Apache Qpid <http://qpid.apache.org/>'
+
+# The short X.Y version.
+version = '${QPID_DISPATCH_VERSION}'
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ["**/*_help.rst"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinxdoc'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('man/qdrouterd', 'qdrouterd', u'dispatch router', None, '8'),
+ ('man/qdrouterd.conf', 'qdrouterd.conf', u'dispatch router configuration', None, '5'),
+ ('man/qdstat', 'qdstat', u'dispatch router status', None, '8'),
+ ('man/qdmanage', 'qdmanage', u'dispatch management tool', None, '8'),
+]
Added: qpid/dispatch/branches/0.4/doc/index.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/index.rst?rev=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/index.rst (added)
+++ qpid/dispatch/branches/0.4/doc/index.rst Thu Mar 12 14:34:28 2015
@@ -0,0 +1,34 @@
+.. 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.
+
+Documentation for dispatch
+==========================
+
+See also the `dispatch router website <http://qpid.apache.org/components/dispatch-router>`_
+
+Documentation
+
+- `Dispatch router book <book/book.html>`__
+
+Manual pages
+
+- `qdrouterd <man/qdrouterd.html>`__ The router daemon
+- `qdrouterd.conf <man/qdrouterd.conf.html>`__ Router daemon
+ configuration
+- `qdstat <man/qdstat.html>`__ Check statistics for a running router
+- `qdmanage <man/qdmanage.html>`__ Query and set management attributes of
+ a running router.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org