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/01/10 19:01:13 UTC
svn commit: r1650775 - in /qpid/dispatch/trunk: ./ doc/book/
python/qpid_dispatch/management/ python/qpid_dispatch_internal/management/
Author: aconway
Date: Sat Jan 10 18:01:13 2015
New Revision: 1650775
URL: http://svn.apache.org/r1650775
Log:
NO-JIRA: Improvements to documentation.
- Remove link routing mentions from doc, not yet implemented.
- Remove out-of-date "Known issues", belongs on website not book.
- Improve schema chapter of book, more user focused, remove irrelevant low-level detail.
Modified:
qpid/dispatch/trunk/TODO
qpid/dispatch/trunk/doc/book/addressing.md
qpid/dispatch/trunk/doc/book/schema_md.py
qpid/dispatch/trunk/doc/book/using.md
qpid/dispatch/trunk/python/qpid_dispatch/management/qdrouter.json
qpid/dispatch/trunk/python/qpid_dispatch/management/qdrouter.json.readme.txt
qpid/dispatch/trunk/python/qpid_dispatch_internal/management/schema.py
Modified: qpid/dispatch/trunk/TODO
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/TODO?rev=1650775&r1=1650774&r2=1650775&view=diff
==============================================================================
--- qpid/dispatch/trunk/TODO (original)
+++ qpid/dispatch/trunk/TODO Sat Jan 10 18:01:13 2015
@@ -1,4 +1,4 @@
-;;
+<!--*-markdown-*-
;; 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
@@ -15,59 +15,75 @@
;; KIND, either express or implied. See the License for the
;; specific language governing permissions and limitations
;; under the License.
-;;
+-->
-Qpid Dispatch TODO List
-==============================================================================
-Beyond this simple laundry list, you can find the list of bugs and
-enhancements to be fixed by going to the Apache Qpid JIRA instance:
+# Qpid Dispatch TODO List
- http://issues.apache.org/jira/browse/QPID
-==============================================================================
+Beyond this simple laundry list, you can find the list of bugs and
+enhancements at the [Apache Qpid JIRA instance](http://issues.apache.org/jira/browse/QPID)
-- Router Mode:
- o Stand-Alone-Router - Does not participate in routing protocol, does not permit inter-router
+- Router Mode
+ - Stand-Alone-Router - Does not participate in routing protocol, does not permit inter-router
links, acts as a normal interior-router otherwise.
- o Interior-Router - Participates in the routing protocol
- o Edge-Concentrator - Does not participate in routing protocol, requires uplink connection(s)
+ - Interior-Router - Participates in the routing protocol
+ - Edge-Concentrator - Does not participate in routing protocol, requires uplink connection(s)
This mode should be used when Dispatch is integrated into an endpoint
application or when it is acting as a connection concentrator.
Proxy and access-protocol functions will be available in this mode.
- Connection Annotation:
- o Type: Inter-router, uplink, endpoint, etc. This formal annotation can be accessed internally
+ - Type: Inter-router, uplink, endpoint, etc. This formal annotation can be accessed internally
by the connection handlers to guide Dispatch's handling of new connections.
- o Weight-{in,out}: Weight/Cost metrics for inter-router links
+ - Weight-{in,out}: Weight/Cost metrics for inter-router links
- Statistics for Instrumentation:
- o Link
+ - Link
. delivery count {unsettled, pre-settled}
. deliveries {accepted, rejected, released, modified}
. octets of delivery {accepted, rejected, released, modified}
. flow frame count
. disposition frame count {forward, backward}
- o Address
+ - Address
. deliveries {ingress, egress, transit}
. octets of delivery {ingress, egress, transit}
- Infrastructure
- o Router_Link - Buffer and Iterator for a copy of the link's target address (for use
+ - Router_Link - Buffer and Iterator for a copy of the link's target address (for use
as an address for messages with no 'to' field).
- o Router Event Queue - Event queue to feed alerts to the Python router code.
+ - Router Event Queue - Event queue to feed alerts to the Python router code.
Neighbor-link-loss is a valuable event because it accelerates the
detection of topology change.
- o All PyRouter stimulus through a work queue.
- o Router Code Updates
+ - All PyRouter stimulus through a work queue.
+ - Router Code Updates
. Report address mappings to routers
. Generate RA immediately after updating routing tables
. Generate unsolicited updates for mobile addresses?
- o Expose idle-timeout/keepalive on connectors and listeners
+ - Expose idle-timeout/keepalive on connectors and listeners
- Major Roadmap Features
- o Security Policy Enforcement
- o Proxy (Translation Node) Capability
- o Address Provisioning with variable semantics
- o Link Routing
- o Management, Instrumentation, and Accounting
- o Link Cost
- o Area Routing
+ - 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/trunk/doc/book/addressing.md
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/addressing.md?rev=1650775&r1=1650774&r2=1650775&view=diff
==============================================================================
--- qpid/dispatch/trunk/doc/book/addressing.md (original)
+++ qpid/dispatch/trunk/doc/book/addressing.md Sat Jan 10 18:01:13 2015
@@ -48,7 +48,6 @@ The semantics of an address control how
Address semantics include the following considerations:
- *Routing pattern* - direct, multicast, balanced
- - *Routing mechanism* - message routed, link routed
- *Undeliverable action* - drop, hold and retry, redirect
- *Reliability* - N destinations, etc.
@@ -60,7 +59,7 @@ Routing patterns constrain the paths tha
|-----------|---------------|
| *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 (or links) 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. |
+ | *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
@@ -73,18 +72,17 @@ meant by the term *routing*:
> 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.
-Some of the links are designated for message routing, and others are designated for
-link routing. In both cases, 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.
+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 message-routing link, the router extracts the
+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.
@@ -93,22 +91,3 @@ shall be resent.
|------------|------------|
| *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. |
-
-### 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/trunk/doc/book/schema_md.py
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/schema_md.py?rev=1650775&r1=1650774&r2=1650775&view=diff
==============================================================================
--- qpid/dispatch/trunk/doc/book/schema_md.py (original)
+++ qpid/dispatch/trunk/doc/book/schema_md.py Sat Jan 10 18:01:13 2015
@@ -18,12 +18,13 @@
##
"""
-Generate the schema.md makrdown documentation for management schema.
+Generate the schema.md chapter for the dispatch book from the qdrouter.json schema.
"""
import sys, re
from pkgutil import get_data
from qpid_dispatch_internal.management.qdrouter import QdSchema
+from qpid_dispatch_internal.management.schema import quotestr
class SchemaWriter(object):
"""Write the schema as a markdown document"""
@@ -43,69 +44,88 @@ class SchemaWriter(object):
default = attr.default
if isinstance(default, basestring) and default.startswith('$'):
default = None # Don't show defaults that are references, confusing.
- self.write('\n`%s` '%(attr.name))
+ self.write('\n*%s* '%(attr.name))
self.write('(%s)\n'%(', '.join(
filter(None, [str(attr.atype),
attr.required and "required",
attr.unique and "unique",
- default and "default=%s"%default]))))
+ default and "default=%s" % quotestr(default)]))))
if attr.description:
self.write(": %s\n"%attr.description)
else:
self.warn("Warning: No description for %s in %s" % (attr, thing.short_name))
- def preface(self, thing):
- self.write('\n### `%s`\n' % thing.short_name)
- if thing.description:
- self.write('\n%s\n' % thing.description)
- else:
- self.warn("Warning no description for %s" % thing)
-
def attributes(self, thing):
for attr in thing.my_attributes:
self.attribute(attr, thing)
- def annotation(self, annotation):
- self.preface(annotation)
- used_by = ["`%s`" % e.short_name
- for e in self.schema.filter(lambda e: annotation in e.annotations)]
- if used_by:
- self.write('\nUsed by %s.\n'%(', '.join(used_by)))
- self.attributes(annotation)
-
- def summary(self, thing):
- return "`%s` (%s)" % (thing.short_name, ", ".join("`%s`" % a for a in thing.attributes))
+ def preface(self, thing):
+ self.write('\n### %s\n' % thing.short_name)
+ if thing.description:
+ self.write('\n%s\n' % thing.description)
+ else:
+ self.warn("Warning no description for %s" % entity_type)
def entity_type(self, entity_type):
self.preface(entity_type)
- if entity_type.base:
- self.write('\nExtends: %s.\n' % self.summary(entity_type.base))
- if entity_type.annotations:
- self.write('\nAnnotations: %s.\n' % (
- ', '.join([self.summary(a) for a in entity_type.annotations])))
+ for a in entity_type.annotations: self.attributes(a)
self.attributes(entity_type)
+ ops = entity_type.operations
+ if entity_type.singleton: ops.remove('CREATE')
+ if ops:
+ self.write("\nOperations allowed: %s\n\n" % ", ".join(entity_type.operations))
def entity_types(self, base_name):
base = self.schema.entity_type(base_name)
- self.entity_type(base)
for entity_type in self.schema.filter(lambda t: t.extends(base)):
self.entity_type(entity_type)
def run(self):
- self.write(get_data('qpid_dispatch.management', 'qdrouter.json.readme.txt')) # Preface
- self.write("The rest of this section provides the schema documentation in readable format.\n")
+ self.write("""
+# Management Schema
- self.write("\n## Annotations\n")
- for annotation in self.schema.annotations.itervalues():
- self.annotation(annotation)
+This chapter documents the set of *management entity types* that define configuration and
+management of a Dispatch Router.
- self.write("\n## Base Entity Type\n")
- self.entity_type(self.schema.entity_type("entity"))
+All management entity types have the following attributes:
- self.write("\n## Configuration Entities\n")
+- *type*: The fully qualified type of the entity,
+ e.g. `org.apache.qpid.dispatch.router`. In this documentation and when using
+ dispatch tools you can use the short name of the type, e.g. `router`
+
+- *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 kinds of management entity type.
+
+- *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.
+
+
+""")
+
+ self.write("""## Configuration Entities
+
+Configuration entities define the attributes allowed in the configuration file
+(see `qdrouterd.conf(5)`) but you can also create entities once the router is
+running using the `qdrouterd(8)` tool's `create` operation. Some entities can also
+be modified using the `update` operation, see the entity descriptions below.
+
+""")
self.entity_types("configurationEntity")
- self.write("\n## Operational Entities\n")
+ self.write("""\n## Operational Entities
+
+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
+operational attributes.
+""")
self.entity_types("operationalEntity")
def main():
Modified: qpid/dispatch/trunk/doc/book/using.md
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/using.md?rev=1650775&r1=1650774&r2=1650775&view=diff
==============================================================================
--- qpid/dispatch/trunk/doc/book/using.md (original)
+++ qpid/dispatch/trunk/doc/book/using.md Sat Jan 10 18:01:13 2015
@@ -29,8 +29,7 @@ to use a different path, the "-c" comman
which configuration to load.
To run the router, invoke the executable:
-o
- $ qdrouterd [-c my-config-file]
+ qdrouterd [-c my-config-file]
For more details of the configuration file see the `qdrouterd.conf(5)` man page.
@@ -53,7 +52,7 @@ Router. The following options are usefu
| *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 routers. |
+ | -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. |
@@ -222,25 +221,3 @@ The equivalent program written in Python
messenger.stop()
main()
-
-
-## Known Issues and Limitations
-
-This is an early test release. It is expected that users will find bugs and other
-various instabilities. The main goal of this release is to prove that the process can be
-run and that users can demonstrate basic functionality as described in this document.
-Nevertheless, the following are known issues with the 0.1 release:
-
- - Subscriber addresses are not always cleaned up after a consumer disconnects. See
- <https://issues.apache.org/jira/browse/QPID-4964>.
- - Dispatch Router does not currently use the target address of a client's sender link to
- route messages. It only looks at the "to" field in the message's headers. See
- <https://issues.apache.org/jira/browse/QPID-5175>.
- - All subscription sources are treated as multicast addresses. There is currently no
- facility for provisioning different types of addresses. Multicast means that if there
- are multiple subscribers to the same address, they will all receive a copy of each
- message sent to that address.
- - SSL connectors and listeners are supported but very lightly (and not recently) tested.
- - SASL authentication is not currently integrated into any authentication framework. Use
- ANONYMOUS for testing.
-
Modified: qpid/dispatch/trunk/python/qpid_dispatch/management/qdrouter.json
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/python/qpid_dispatch/management/qdrouter.json?rev=1650775&r1=1650774&r2=1650775&view=diff
==============================================================================
--- qpid/dispatch/trunk/python/qpid_dispatch/management/qdrouter.json (original)
+++ qpid/dispatch/trunk/python/qpid_dispatch/management/qdrouter.json Sat Jan 10 18:01:13 2015
@@ -195,10 +195,10 @@
"extends": "configurationEntity",
"operations": ["CREATE", "READ"],
"annotations": [
- "sslProfile",
"addrPort",
- "saslMechanisms",
- "connectionRole"
+ "connectionRole",
+ "sslProfile",
+ "saslMechanisms"
],
"attributes": {
"requirePeerAuth": {
@@ -233,10 +233,10 @@
"extends": "configurationEntity",
"operations": ["CREATE", "READ"],
"annotations": [
- "sslProfile",
"addrPort",
- "saslMechanisms",
- "connectionRole"
+ "connectionRole",
+ "sslProfile",
+ "saslMechanisms"
],
"attributes": {
"allowRedirect": {
Modified: qpid/dispatch/trunk/python/qpid_dispatch/management/qdrouter.json.readme.txt
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/python/qpid_dispatch/management/qdrouter.json.readme.txt?rev=1650775&r1=1650774&r2=1650775&view=diff
==============================================================================
--- qpid/dispatch/trunk/python/qpid_dispatch/management/qdrouter.json.readme.txt (original)
+++ qpid/dispatch/trunk/python/qpid_dispatch/management/qdrouter.json.readme.txt Sat Jan 10 18:01:13 2015
@@ -1,3 +1,22 @@
+<!--*-markdown-*-
+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.
+-->
+
# The qdrouter management schema
The schema `qdrouterd.json` is a JSON format file that defines annotations and
@@ -8,7 +27,7 @@ The schema is a JSON map with the follow
- "description": documentation string for the schema
- "prefix": Prefix prepended to schema names when they are exposed to AMQP management clients.
-- "annotations": map of annotation names to definitions (see below)
+
- "entityTypes": map of entity type names to definitions (see below)
Annotation and entity type definition maps have the following keys:
Modified: qpid/dispatch/trunk/python/qpid_dispatch_internal/management/schema.py
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/python/qpid_dispatch_internal/management/schema.py?rev=1650775&r1=1650774&r2=1650775&view=diff
==============================================================================
--- qpid/dispatch/trunk/python/qpid_dispatch_internal/management/schema.py (original)
+++ qpid/dispatch/trunk/python/qpid_dispatch_internal/management/schema.py Sat Jan 10 18:01:13 2015
@@ -35,6 +35,11 @@ class ValidationError(Exception):
"""Error raised if schema validation fails"""
pass
+def quotestr(value, quote="'"):
+ """Quote value if it is a string type, str() it if not """
+ if isinstance(value, basestring): return "'%s'" % value
+ else: return str(value)
+
class Type(object):
"""Base class for schema types.
@@ -142,10 +147,13 @@ class EnumType(Type):
def __str__(self):
"""String description of enum type."""
- return "One of [%s]"%(', '.join(self.tags))
+ return "One of [%s]" % ', '.join([quotestr(tag) for tag in self.tags])
-BUILTIN_TYPES = dict((t.name, t) for t in
- [Type("String", str), Type("Integer", int), Type("List", list), BooleanType()])
+BUILTIN_TYPES = OrderedDict(
+ (t.name, t) for t in [Type("String", str),
+ Type("Integer", int),
+ Type("List", list),
+ BooleanType()])
def get_type(rep):
"""
@@ -309,7 +317,7 @@ class Annotation(AttrsAndOps):
"""An annotation type defines a set of attributes that can be re-used by multiple EntityTypes"""
def __init__(self, name, schema, attributes=None, operations=None, description=""):
super(Annotation, self).__init__(name, schema, attributes, operations, description)
- attributes = attributes or {}
+ attributes = attributes or OrderedDict()
for a in self.attributes.itervalues():
a.annotation = self
@@ -487,8 +495,8 @@ class Schema(object):
for k, v in defs.iteritems():
t = thing(k, self, **v)
mymap[t.name] = t
- add_defs(Annotation, self.annotations, annotations or {})
- add_defs(EntityType, self.entity_types, entityTypes or {})
+ add_defs(Annotation, self.annotations, annotations or OrderedDict())
+ add_defs(EntityType, self.entity_types, entityTypes or OrderedDict())
for e in self.entity_types.itervalues():
e.init()
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org