Github user kgiusti commented on a diff in the pull request:
https://github.com/apache/qpid-dispatch/pull/218#discussion_r151509115
--- Diff: doc/new-book/routing.adoc ---
@@ -213,15 +213,17 @@ address {
}
----
-`prefix` | `pattern`:: The address or group of addresses to which the
address settings should be applied. You can specify a prefix to match an exact
address or segment of an address. Alternatively, you can specify a pattern to
match an address using wildcards.
+`prefix` | `pattern`:: The address or group of addresses to which the
address settings should be applied. You can specify a prefix to match an exact
address or beginning segment of an address. Alternatively, you can specify a
pattern to match an address using wildcards.
+
//tag::prefix-matching[]
-A _prefix_ matches either an exact address or a segment within an address
that is delimited by either a `.` or `/` character. For example, the prefix
`my_address` would match the address `my_address` as well as `my_address.1` and
`my_address/1`. However, it would not match `my_address1`.
+A _prefix_ matches either an exact address or the beginning segment within
an address that is delimited by either a `.` or `/` character. For example, the
prefix `my_address` would match the address `my_address` as well as
`my_address.1` and `my_address/1`. However, it would not match `my_address1`.
//end::prefix-matching[]
+
//tag::pattern-matching[]
A _pattern_ matches an address that corresponds to a pattern. A pattern is
a sequence of words delimited by either a `.` or `/` character. You can use
wildcard characters to represent a word. The `*` character matches exactly one
word, and the `#` character matches any sequence of zero or more words.
+
+The pattern configuration and the address(es) that match the pattern
should use the same delimiter character. For example, if you configure the
pattern to be `my.+`, then the addresses that match the pattern should also use
a `.` as a delimiter (instead of a `/`).
--- End diff --
Yeah that seems likely.
However on re-reading line 225 I'm not sure what it describes is actually
correct.
There really isn't a standard for the format of addresses. A proposal was
made to define the '/' character as a separator for hierarchical addresses, but
that never reached consensus.
In the meantime, dispatch tended to use "." as a separator when comparing
address prefixes. Later when the proposal surfaced dispatch was changed to
allow either '.' or '/' as separators, preserving backward compatibility and
anticipating future uses.
The new pattern matching feature follows the same behavior: either '.' or
'/' as a separator.
But that complicates things a bit, since the code can't be sure of the
intent when both '.' and '/' appear in a message's address. Should '.'
designate a token boundary, or should '/'?
In the end the router treats them both as separators *but* does not compare
the separators themselves when pattern matching the address. As an example,
let's assume the following pattern is configured:
a.b/c.d
Dispatch's token parser is going to split this up into the following token
sequence:
a, b, c, d
effectively stripping away the separators before the comparison is done.
So the above a.b/c.d pattern would match the following message addresses:
a.b.c/d
a/b/c/d
a.b.c.d
So for the purpose of documentation:
1 both '.' and '/' are considered separators when determining words
(tokens) both in the configured pattern and in incoming message addresses.
2 all '.' and '/' are ignored when comparing a message's address to a
configured pattern. This means a message with address 'a.b.c' will match the
pattern 'a/b/*'
3 asterisk and hash are reserved characters and must not appear in a
message's address (note: _address_, not _pattern_). Therefore a message with a
to: address of 'a.#.b' may not be routed properly.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org
For additional commands, e-mail: dev-h...@qpid.apache.org
