[ https://issues.apache.org/jira/browse/DISPATCH-875?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16255807#comment-16255807 ]
ASF GitHub Bot commented on DISPATCH-875: ----------------------------------------- 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. > Document address and link route wildcards > ----------------------------------------- > > Key: DISPATCH-875 > URL: https://issues.apache.org/jira/browse/DISPATCH-875 > Project: Qpid Dispatch > Issue Type: Bug > Components: Documentation > Affects Versions: 1.1.0 > Reporter: Ben Hardesty > Assignee: Ben Hardesty > > Update Dispatch Router doc to describe how to define groups of addresses > using the new "pattern" address attribute. -- This message was sent by Atlassian JIRA (v6.4.14#64029) --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org For additional commands, e-mail: dev-h...@qpid.apache.org