Author: mgoulish
Date: Mon Apr 15 13:49:21 2013
New Revision: 1468073
URL: http://svn.apache.org/r1468073
Log:
PROTON-260: initial checkin of addressing_and_routing.md
Added:
qpid/proton/trunk/docs/markdown/messenger/addressing_and_routing.md
Added: qpid/proton/trunk/docs/markdown/messenger/addressing_and_routing.md
URL:
http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/addressing_and_routing.md?rev=1468073&view=auto
==============================================================================
--- qpid/proton/trunk/docs/markdown/messenger/addressing_and_routing.md (added)
+++ qpid/proton/trunk/docs/markdown/messenger/addressing_and_routing.md Mon Apr
15 13:49:21 2013
@@ -0,0 +1,208 @@
+
+Messenger Addressing and Routing
+=================================================
+
+
+Addressing
+-------------------------
+
+An address has the following form:
+
+ [ amqp[s]:// ] [user[:password]@] domain [/[name]]
+
+Where domain can be one of:
+
+ host | host:port | ip | ip:port | name
+
+The following are valid examples of addresses:
+
+ * example.org
+ * example.org:1234
+ * amqp://example.org
+ * amqps://example.org
+ * example.org/incoming
+ * amqps://example.org/outgoing
+ * amqps://fred:trust...@example.org
+ * 127.0.0.1:1234
+ * amqps://127.0.0.1:1234
+
+The "/name" part of the address, that optionally follows
+the domain, is not used by the Messenger library.
+For example, if a receiver subscribes to
+
+ amqp://~0.0.0.0:5678
+
+Then it will receive messages sent to
+
+ amqp://~0.0.0.0:5678
+as well as
+ amqp://~0.0.0.0:5678/foo
+
+
+Likewise, if the receiver subscribes to
+
+ amqp://~0.0.0.0:5678/foo
+
+it will receive messages addressed to
+
+ amqp://~0.0.0.0:5678/foo
+ amqp://~0.0.0.0:5678
+
+and
+
+ amqp://~0.0.0.0:5678/bar
+
+
+
+
+<br/>
+Routing
+------------------------------
+
+### Pattern Matching and Address Translation ###
+
+The Messenger library provides message routing capability
+with an address translation table. Each entry in the table
+consists of a _pattern_ and a _translation_.
+
+You store a new route entry in the table with the call:
+
+ pn_messenger_route ( messenger, pattern, translation );
+
+
+The address of each outgoing message is compared to the
+table's patterns until the first matching pattern is found,
+or until all patterns have failed to match.
+
+If no pattern matches, then Messenger will send (or attempt
+to send) your message with the address as given.
+
+If a pattern does match your outgoing message's address, then
+Messenger will create a temporary address by transforming
+your message's address. Your message will be sent to the
+transformed address, but **(note!)** the address on your
+outgoing message will not be changed. The receiver will see
+the original, not the transformed address.
+
+
+<br/>
+
+### Two Translation Mechanisms ###
+
+
+Messenger uses two mechanisms to translate addresses.
+The first is simple string substitution.
+
+
+ pattern: COLOSSUS
+ translation: amqp://0.0.0.0:6666
+ input addr: COLOSSUS
+ result: amqp://0.0.0.0:6666
+
+
+The second mechanism is wildcard/variable substitution.
+A wildcard in the pattern matches all or part of your
+input address. The part of your input address that matched
+the wildcard is stored. The matched value is then inserted
+into your translated address in place of numbered variables:
+$1, $2, and so on, up to a maximum of 64.
+
+There are two wildcards: * and % .
+The rules for matching are:
+
+ * matches anything
+ % matches anything but a /
+ other characters match themselves
+ the whole input addr must be matched
+
+
+Examples of wildcard matching:
+
+ pattern: /%/%/%
+ translation: $1x$2x$3
+ input addr: /foo/bar/baz
+ result: fooxbarxbaz
+
+ pattern: *
+ translation: $1
+ inout addr: /foo/bar/baz
+ result: /foo/bar/baz
+
+ pattern: /*
+ translation: $1
+ input addr: /foo/bar/baz
+ result: foo/bar/baz
+
+ pattern: /*baz
+ translation: $1
+ input addr: /foo/bar/baz
+ result: foo/bar/
+
+ pattern: /%baz
+ translation: $1
+ input addr: /foo/bar/baz
+ result: FAIL
+
+ pattern: /%/baz
+ translation: $1
+ input addr: /foo/bar/baz
+ result: FAIL
+
+ pattern: /%/%/baz
+ translation: $1
+ input addr: /foo/bar/baz
+ result: foo
+
+ pattern: /*/baz
+ translation: $1
+ input addr: /foo/bar/baz
+ result: foo/bar
+
+
+Examples of route translation usage:
+
+ pattern: foo
+ translation: amqp://foo.com
+ explanation: Any message sent to "foo" will be routed to
"amqp://foo.com"
+
+
+ pattern: bar/*
+ translation: amqp://bar.com/$1
+ explanation: Any message sent to bar/<path> will be routed to the
corresponding path within the amqp://bar.com domain.
+
+
+ pattern: amqp:*
+ translation: amqps:$1
+ explanation: Route all messages over TLS.
+
+
+ pattern: amqp://foo.com/*
+ translation: amqp://user:passw...@foo.com/$1
+ explanation: Supply credentials for foo.com.
+
+
+ pattern: amqp://*
+ translation: amqp://user:password@$1
+ explanation: Supply credentials for all domains.
+
+
+ pattern: amqp://%/*
+ translation: amqp://user:password@proxy/$1/$2
+ explanation: Route all addresses through a single proxy while
preserving the
+ original destination.
+
+
+ pattern: *
+ translation: amqp://user:password@broker/$1
+ explanation: Route any address through a single broker.
+
+
+
+<br/>
+### First Match Wins ###
+
+If you create multiple routing rules, each new rule is appended
+to your Messenger's list. At send-time, Messenger looks down the
+list, and the first rule that matches your outgoing message's
+address wins. Thus, when creating your routing rules, you should
+create them in order of most specific first, most general last.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org
For additional commands, e-mail: commits-h...@qpid.apache.org
