From 8e69433bac5c020c51432e8a28b2b4f0b96fa845 Mon Sep 17 00:00:00 2001 From: "Rafael H. Schloming" Date: Mon, 28 Dec 2009 12:44:18 +0000 Subject: updated Session docs to include address syntax git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/qpid.rnr@894162 13f79535-47bb-0310-9956-ffa450edef68 --- python/Makefile | 2 +- python/qpid/messaging.py | 178 +++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 175 insertions(+), 5 deletions(-) diff --git a/python/Makefile b/python/Makefile index 7f475adc09..2c7f9b8de0 100644 --- a/python/Makefile +++ b/python/Makefile @@ -50,7 +50,7 @@ build: $(TARGETS) doc: @mkdir -p $(BUILD) - PYTHONPATH=. epydoc qpid.messaging -o $(BUILD)/doc --no-private --no-sourcecode --include-log + PYTHONPATH=. epydoc -v qpid.messaging -o $(BUILD)/doc --no-private --no-sourcecode --include-log install: build install -d $(PYTHON_LIB) diff --git a/python/qpid/messaging.py b/python/qpid/messaging.py index 4f2c190ce2..ca8483eef0 100644 --- a/python/qpid/messaging.py +++ b/python/qpid/messaging.py @@ -22,8 +22,6 @@ A candidate high level messaging API for python. Areas that still need work: - - asynchronous send - - asynchronous error notification - definition of the arguments for L{Session.sender} and L{Session.receiver} - standard L{Message} properties - L{Message} content encoding @@ -247,8 +245,180 @@ class Session: """ Sessions provide a linear context for sending and receiving - messages, and manage various Senders and Receivers. - """ + L{Messages}. L{Messages} are sent and received + using the L{Sender.send} and L{Receiver.fetch} methods of the + L{Sender} and L{Receiver} objects associated with a Session. + + Each L{Sender} and L{Receiver} is created by supplying either a + target or source address to the L{sender} and L{receiver} methods of + the Session. The address is supplied via a string syntax documented + below. + + Addresses + ========= + + An address identifies a source or target for messages. In its + simplest form this is just a name. In general a target address may + also be used as a source address, however not all source addresses + may be used as a target, e.g. a source might additionally have some + filtering criteria that would not be present in a target. + + A subject may optionally be specified along with the name. When an + address is used as a target, any subject specified in the address is + used as the default subject of outgoing messages for that target. + When an address is used as a source, any subject specified in the + address is pattern matched against the subject of available messages + as a filter for incoming messages from that source. + + The options map contains additional information about the address + including: + + - policies for automatically creating, and deleting the node to + which an address refers + + - policies for asserting facts about the node to which an address + refers + + - extension points that can be used for sender/receiver + configuration + + Mapping to AMQP 0-10 + -------------------- + The name is resolved to either an exchange or a queue by querying + the broker. + + The subject is set as a property on the message. Additionally, if + the name refers to an exchange, the routing key is set to the + subject. + + Syntax + ------ + The following regular expressions define the tokens used to parse + addresses:: + LBRACE: \\{ + RBRACE: \\} + LBRACK: \\[ + RBRACK: \\] + COLON: : + SEMI: ; + SLASH: / + COMMA: , + NUMBER: [+-]?[0-9]*\\.?[0-9]+ + ID: [a-zA-Z_](?:[a-zA-Z0-9_-]*[a-zA-Z0-9_])? + STRING: "(?:[^\\\\"]|\\\\.)*"|\'(?:[^\\\\\']|\\\\.)*\' + ESC: \\\\[^ux]|\\\\x[0-9a-fA-F][0-9a-fA-F]|\\\\u[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F] + SYM: [.#*%@$^!+-] + WSPACE: [ \\n\\r\\t]+ + + The formal grammar for addresses is given below:: + address = name [ "/" subject ] [ ";" options ] + name = ( part | quoted )+ + subject = ( part | quoted | "/" )* + quoted = STRING / ESC + part = LBRACE / RBRACE / COLON / COMMA / NUMBER / ID / SYM + options = map + map = "{" ( keyval ( "," keyval )* )? "}" + keyval = ID ":" value + value = NUMBER / STRING / ID / map / list + list = "[" ( value ( "," value )* )? "]" + + This grammar resuls in the following informal syntax:: + + [ / ] [ ; ] + + Where options is:: + + { : , ... } + + And values may be: + - numbers + - single, double, or non quoted strings + - maps (dictionaries) + - lists + + Options + ------- + The options map permits the following parameters:: + + [ / ] { + create: , + delete: , + assert: , + node-properties: { + type: , + durable: , + x-properties: { + bindings: ["/", ...], + : + } + } + } + + The create, delete, and assert policies specify who should perfom + the associated action: + + - I{always}: the action will always be performed + - I{sender}: the action will only be performed by the sender + - I{receiver}: the action will only be performed by the receiver + - I{never}: the action will never be performed (this is the default) + + The node-type is one of: + + - I{topic}: a topic node will default to the topic exchange, + x-properties may be used to specify other exchange types + - I{queue}: this is the default node-type + + The x-properties map permits arbitrary additional keys and values to + be specified. These keys and values are passed through when creating + a node or asserting facts about an existing node. Any passthrough + keys and values that do not match a standard field of the underlying + exchange or queue declare command will be sent in the arguments map. + + Examples + -------- + A simple name resolves to any named node, usually a queue or a + topic:: + + my-queue-or-topic + + A simple name with a subject will also resolve to a node, but the + presence of the subject will cause a sender using this address to + set the subject on outgoing messages, and receivers to filter based + on the subject:: + + my-queue-or-topic/my-subject + + A subject pattern can be used and will cause filtering if used by + the receiver. If used for a sender, the literal value gets set as + the subject:: + + my-queue-or-topic/my-* + + In all the above cases, the address is resolved to an existing node. + If you want the node to be auto-created, then you can do the + following. By default nonexistent nodes are assumed to be queues:: + + my-queue; {create: always} + + You can customize the properties of the queue:: + + my-queue; {create: always, node-properties: {durable: True}} + + You can create a topic instead if you want:: + + my-queue; {create: always, node-properties: {type: topic}} + + You can assert that the address resolves to a node with particular + properties:: + + my-transient-topic; { + assert: always, + node-properties: { + type: topic, + durable: False + } + } + """ def __init__(self, connection, name, transactional): self.connection = connection -- cgit v1.2.1